Agent Skill for Coding: How to Package Engineering Judgment

An agent skill for coding is a reusable engineering workflow that tells an AI coding agent how to make one class of repo change safely. It names the trigger, the files to inspect first, the conventions to follow, the tests to run, the stop conditions, and the evidence to report before the task is considered done.

The useful part is not "write code faster." The useful part is packaging the judgment a strong engineer applies before touching a real codebase: read the bug report, inspect the failing test, avoid unrelated cleanup, preserve local changes, patch the smallest path, and prove the result with a command or screenshot.

OpenAI's Codex skills documentation describes a skill as a directory with SKILL.md plus optional scripts/, references/, and assets/ (OpenAI Codex skills). That structure maps naturally to software work. The main file can hold the workflow, references can hold architecture notes or migration rules, and scripts can hold deterministic checks the model should not do by hand.

If you are still deciding whether a skill is the right abstraction, start with What Is an Agent Skill?. This article assumes the job is already recurring enough to deserve a reusable workflow and focuses on coding-specific patterns.

A coding skill should be narrower than "build software" and more durable than a one-off prompt. Good scopes line up with repeatable engineering jobs where the sequence matters and the expected evidence is known.

Change type	Useful skill scope	Completion evidence
Bug fix	Diagnose and patch a reproducible defect	failing test, fix, passing test
Migration	Update code from one API pattern to another	changed files, codemod notes, compatibility tests
Review	Inspect a diff against project rules	severity-ranked findings with file references
Refactor	Improve a bounded module without behavior change	before/after tests and rationale
Feature slice	Add a small user-visible behavior	tests, screenshots, route checks
Repo maintenance	Refresh generated files, lockfiles, or package setup	command output and limited diff

"Build this app" is too large for one coding skill. "Add a new authenticated settings panel following this repo's App Router patterns" is closer. "Migrate one package from Express middleware v4 to v5 conventions and run the route tests" is better still because the source path, allowed change type, and validation are all visible.

This is the same boundary discussed in Agent Skill vs Code: the skill should hold judgment and procedure, while scripts, tests, linters, and tools should own deterministic checks.

A coding skill should define:

• Trigger: the exact kind of coding task that should activate the skill.
• Non-trigger: adjacent work that should use a different skill or normal prompt.
• Change boundary: files, modules, routes, packages, or ownership area.
• Truth path: bug report, failing test, stack trace, issue, current implementation, or design doc.
• Local conventions: naming, state management, error handling, styling, logging, and dependency policy.
• Verification: unit tests, integration tests, type checks, lint, build, browser checks, or manual reproduction.
• Safety rules: preserve user changes, avoid destructive commands, keep diffs scoped, and stop before risky mutations.
• Final evidence: changed files, commands run, results, and known residual risk.

This is where a coding skill differs from a prompt. A prompt may generate code. A skill should make the agent behave like a careful contributor inside a living codebase.

GitHub makes the same point in its guidance for Copilot coding agent tasks: repository instructions should tell the agent how to understand the project and how to build, test, and validate changes in its own environment (GitHub Copilot coding agent best practices). Its code review guidance also shows how project-specific instructions can shift feedback from generic comments toward security, performance, and domain rules. A coding skill is a more portable version of that idea: not every repository-wide rule, but the rules for one recurring job.

---
name: focused-bug-fix
description: Reproduce, patch, and verify a bounded bug in an existing codebase. Use when given a failing behavior, test, issue, or stack trace. Do not use for broad refactors.
---

## Workflow

1. Read the bug report, stack trace, or failing test before searching broadly.
2. Reproduce the failure or explain exactly why reproduction is blocked.
3. Identify the smallest code path that explains the behavior.
4. Write or update a failing test before patching when feasible.
5. Patch only the relevant module and nearest test.
6. Run the focused test, then the nearest broader validation.
7. Report changed files, commands run, and any remaining risk.

Stop if the failure cannot be reproduced or the requested fix requires product clarification.

This skill is not just "write the fix." It defines the engineering loop. The loop is what keeps the agent from wandering into unrelated cleanup or unverified edits.

The strongest part is the stop rule. A coding agent that cannot reproduce a bug should not silently rewrite a subsystem. It should return the reproduction blocker, the inspected paths, and the next piece of evidence needed.

Migration work is one of the best places to use a coding skill because every migration has both mechanical and judgment-heavy parts. A codemod might update imports, but the agent still needs to know which package is in scope, how to handle ambiguous call sites, which tests prove compatibility, and what not to modernize while it is there.

---
name: next-api-route-migration
description: Migrate one Next.js API route from the old handler pattern to the current route-handler pattern. Use for bounded route migrations only. Do not use for unrelated refactors.
---

## Inputs

- route file or route directory
- target framework version
- migration reference
- validation command

## Workflow

1. Read the current route and its nearest tests before editing.
2. Read `references/next-route-migration.md` for accepted patterns.
3. Change only the route, directly required helpers, and tests.
4. Preserve behavior unless the migration reference explicitly says otherwise.
5. Run the focused route test, type check, and lint command named by the repo.
6. Report any call site that could not be migrated safely.

Stop if the target version is unknown, the route has no testable behavior, or the migration changes auth, billing, data deletion, or permissions.

This kind of skill helps because migrations invite scope creep. Without boundaries, an agent may update formatting, rename helpers, change error handling, or "improve" response shapes while doing a version migration. The skill should make that behavior out of bounds.

Coding skills often improve when SKILL.md stays short and references carry durable detail:

• references/testing.md for test command patterns.
• references/architecture.md for module boundaries.
• references/style.md for project conventions.
• references/migrations/ for API-specific migration rules.
• scripts/ for codemods, validators, or fixture generation.

Anthropic's Claude Code docs describe the same practical pattern: create SKILL.md files for domain knowledge and reusable workflows, and load the body only when the skill is used (Claude Code skills). VS Code's Agent Skills docs also show a SKILL.md file with optional scripts, examples, and resources, and explicitly tell authors to reference supporting files from the skill body so the agent can pick them up (VS Code Agent Skills).

The tradeoff is runtime realism. In a GitHub Copilot community thread about Agent Skills in VS Code, practitioners liked that skills can combine prompt, context, and scripts, but noted that scripts still need dependencies installed in the execution environment (Reddit discussion). That is why a coding skill should document whether npm, pnpm, Docker, Playwright browsers, or secrets are required.

For coding, that progressive loading model matters. A repo might have 40 pages of architecture notes, but the agent should not load all of them before every task. A bug-fix skill can reference the testing guide. A migration skill can reference the migration guide. A frontend QA skill can reference Playwright commands. The right detail appears only when the task needs it.

Use scripts for work where exactness matters:

Need	Better as script or test	Better as skill instruction
Check Markdown frontmatter	parser script	when to run it and how to report failures
Rewrite import paths	codemod	which package/version is in scope
Verify UI flow	Playwright test	which route and persona to test
Score skill behavior	eval harness	what success means
Review architecture risk	not fully deterministic	source order and severity rubric

OpenAI's article on testing agent skills recommends evaluating not only final output but also whether the agent invoked the skill, ran expected commands, and followed conventions (Testing Agent Skills Systematically with Evals). That is especially relevant for coding. A skill that says "run the focused test" should be tested on whether the agent actually did that, not whether the final paragraph sounded confident.

A coding skill should not become a dumping ground for every engineering preference in the company. Always-on repository instructions can carry broad defaults like package manager, formatting, language version, and security posture. A skill should carry the procedure for one job.

Avoid these patterns:

• A "senior engineer" skill that tries to cover every possible code task.
• A migration skill that includes unrelated style, performance, and naming cleanups.
• A review skill that reports taste preferences as blocking bugs.
• A bug-fix skill that says to write tests but never names which tests count.
• A script-backed skill with undocumented dependencies or no failure behavior.

For coding teams, progressive disclosure is more than packaging hygiene. It keeps the main workflow readable enough for humans to review.

Treat a coding skill like a small engineering artifact. It needs examples, negative cases, and a way to detect regressions.

Start with three test prompts:

Test case	Example prompt	Expected behavior
Explicit trigger	"Use the focused bug-fix skill to fix this failing test."	skill activates and follows the loop
Implicit trigger	"This checkout test fails after my change; diagnose and patch it."	skill activates from the description
Negative control	"Explain what this function does."	skill does not activate or edit files

Then run the skill against a small fixture repo or a real low-risk issue. Check whether it read the right files first, preserved unrelated changes, updated a test when appropriate, ran the expected command, and reported evidence honestly. How to Test an Agent Skill Before You Publish It goes deeper on this release step, but the coding-specific point is simple: final code is not the only output. The trace matters.

For larger changes, borrow the review pattern many agent-heavy developers already use: implementation in bounded phases, then a separate review pass against requirements, runtime code, and tests. One r/codex discussion described phase-by-phase reviews plus blind final reviews against architecture docs and commit ranges (r/codex code review discussion). That is a good shape for a coding-plan-review or migration-review skill.

MCP tools, IDE integrations, and shell access give the agent capabilities. The coding skill decides how to use them for a job.

Skyscanner's write-up about connecting Codex CLI to JetBrains through MCP is a useful example. The integration gave Codex access to IDE checks such as file problems and run configurations, including unit tests, linters, and formatters (Skyscanner Codex and JetBrains MCP). That kind of tool access is powerful, but it does not replace the workflow. A skill still needs to say which run configuration proves the change, when to inspect compiler errors, and when to stop.

For a frontend bug, the skill might say:

Use the browser test only after the focused unit test passes.
If the browser flow fails, capture the route, viewport, console error, and screenshot.
Do not rewrite unrelated UI components while fixing the flow.

The browser tool performs the action. The skill defines the discipline around the action.

• Does the skill say when it should and should not trigger?
• Does it force the agent to inspect current code before editing?
• Does it name the expected tests or verification commands?
• Does it protect unrelated changes in a dirty worktree?
• Does it include stop rules for unclear product behavior?
• Does it report evidence instead of claiming confidence?
• Does it separate workflow judgment from deterministic scripts?
• Does it include at least one negative trigger example?
• Does it avoid duplicating broad repository instructions?

If the answer is no, the skill may still work once, but it will be hard to reuse. A good coding skill should be boring in the best way: predictable trigger, bounded scope, concrete evidence, and fewer surprises in the diff.

Use a normal prompt for a disposable snippet, an explanation, or a one-off example. Use repository instructions for always-on conventions. Use a script, test, or MCP tool for deterministic work. Use an agent skill when the work repeats inside a real codebase and the team cares about consistency.

The best coding skills feel less like code generators and more like lightweight engineering playbooks. They make the agent inherit the team's habits before it touches the files: inspect first, change less, verify honestly, and leave a reviewable trail.

For Skillfully authors, coding skills are valuable because their quality is observable. Did the agent run the test? Did it preserve unrelated files? Did it stop when the migration touched auth? Did it return a useful residual-risk note? Those signals are exactly the kind of feedback that helps a skill improve after publication.

If you are writing your first one, keep it narrow: one repeatable coding job, one source hierarchy, one verification path, and one final evidence format. That shape is easier to test, share, and revise than a broad instruction file that tries to be an entire engineering department.