How to write better agent skills

A useful agent skill has a clear job, a narrow activation boundary, and a visible definition of done. It does not merely tell the agent to "be thorough." It tells the agent what to inspect first, what evidence counts, what must stay out of scope, and what to report when the work is blocked.

That distinction matters because agent skills are not just longer prompts. OpenAI describes Codex skills as directories containing a required SKILL.md plus optional scripts/, references/, and assets/ folders for reusable workflows (OpenAI Codex skills). Anthropic's Agent Skills docs describe the same operating model: skills package domain expertise and can be loaded automatically when relevant (Anthropic Agent Skills overview). The open Agent Skills specification formalizes the pattern around progressive disclosure: metadata first, instructions when activated, supporting resources only when needed (Agent Skills specification).

The practical consequence is simple. A better skill is not the longest skill. It gives the agent the right next action at the right moment, with enough context to avoid improvising the parts your workflow cannot tolerate. If you are still turning a raw prompt into a reusable package, start with How to Create an Agent Skill.

Weak skills usually start with a broad topic:

---
name: content-strategy
description: Helps with content strategy.
---

You are an expert content strategist. Help the user make great content.

That skill can activate for almost anything, and once it activates it still leaves the agent guessing. Does it create a brief? Review an article? Build a keyword map? Audit a funnel? The model may produce something fluent, but the workflow is not reusable.

A stronger version names the job, the input, the output, and the stopping rule:

---
name: article-brief-review
description: Review a draft SEO article brief before writing starts. Use when the user provides a title, audience, outline, or source list and asks whether the brief is strong enough to draft.
---

## Goal

Decide whether the article brief is ready for drafting.

## Required checks

1. Identify the primary reader and the decision they need to make.
2. Check whether each major claim has a credible source plan.
3. Flag generic sections that could appear in any article on the topic.
4. Return one of: `ready`, `needs-research`, or `needs-positioning`.

## Stop rule

Do not write the article. If the user asks for a draft, first return the brief review and ask whether to proceed.

The better skill is still short, but it is operational. It has a trigger, an expected input, a pass/fail decision, and a guardrail against scope drift. The same pattern applies to code review, sales call prep, data analysis, recruiting outreach, or legal document triage.

The description field is not decoration. In progressive-disclosure systems, the agent may initially see only the skill name and description before deciding whether to load the full body. OpenAI's Codex docs call out that metadata is part of the initial skills list, while the full instructions are read only after selection (OpenAI Codex skills). Anthropic's best-practices guide similarly treats SKILL.md as the overview that points to deeper materials as needed (Anthropic skill authoring best practices).

Treat the description as a routing rule:

• Use a verb and object: "Review pull requests for behavioral regressions."
• Name the activation signal: "Use when the user asks for a pre-merge review or provides a GitHub PR."
• Exclude adjacent work: "Do not use for implementing fixes unless the user explicitly asks."
• Mention hard dependencies: "Requires repository access and the ability to inspect diffs."

Avoid descriptions such as "helps with quality," "improves writing," or "supports engineering." They are too broad to route reliably. Broad triggers cause two expensive failures: the skill activates when it should not, and it fails to activate when the user's wording does not match your vague label.

For a deeper explanation of why skills load in stages, see How Agent Skill Works. The important authoring move is to make the first 200 tokens do real routing work.

An agent skill should cover one repeatable job. Branches should still belong to one workflow.

"Review a TypeScript pull request for correctness, test coverage, and migration risk" is a skill.

"Be my senior engineer for all backend work" is a persona.

Narrow scope improves quality because it lets you write concrete examples and eval cases. OpenAI's guide to testing skills recommends defining success before writing the skill, manually triggering it, and checking whether it activates too eagerly, too rarely, or with hidden assumptions (Testing Agent Skills Systematically with Evals). That advice only works when the skill is small enough to evaluate.

If a skill is getting long, split it by decision point rather than by file size. For example:

• code-review identifies defects in a diff.
• review-fix-implementation applies accepted review comments.
• release-notes converts merged work into user-facing notes.

Those three workflows share context, but they have different inputs, risks, and completion criteria. Keeping them separate makes each one easier to trigger, test, and maintain.

Progressive disclosure is the main design advantage of agent skills. The Agent Skills spec recommends keeping the main instructions concise and moving detailed reference material into supporting files that agents load only when required (Agent Skills specification). Anthropic's engineering post makes the same point: skills can bundle far more knowledge than should sit in the model's immediate context, because the agent can pull in files and scripts on demand (Anthropic engineering post).

Use SKILL.md for:

• activation rules
• the core workflow
• required inputs
• stop rules
• output format
• references to supporting files

Use references/ for long checklists, policy details, examples, domain glossaries, and source excerpts you have rights to include.

Use scripts/ for:

• deterministic checks
• format validation
• data conversion
• repeatable setup

Use assets/ for templates, sample files, slide themes, spreadsheet shells, and design tokens.

Here is the common failure: authors put a 4,000-word policy manual directly in SKILL.md, then bury the workflow halfway down the page. The agent spends context on detail it may not need.

A better pattern is:

## Workflow

1. Read the user's request and classify it as `new-contract`, `renewal`, or `security-review`.
2. If the request is `security-review`, read `references/security-review-checklist.md`.
3. If the contract value is above $50,000, apply the approval path in `references/approval-matrix.md`.
4. Return a risk table with `issue`, `evidence`, `severity`, and `recommended_action`.

The main file stays readable. The deeper material is still available. The agent has explicit conditions for when to load it.

Examples are not decoration either. Anthropic's prompt guidance emphasizes clear instructions and examples because models do better when they can compare the target output to a concrete pattern (Claude prompting best practices). In a skill, examples should teach boundary judgment, not just formatting.

Weak example:

Return a useful review.

Better example:

Good finding:

- Severity: High
- File: `src/billing/reconcile.ts`
- Issue: Refund rows are filtered out before balance comparison, so negative adjustments disappear from the reconciliation total.
- Evidence: The changed query adds `amount > 0`, but the existing test fixture includes refund rows.
- Fix direction: Include refunds in the query and assert net balance in the reconciliation test.

Bad finding:

- Severity: Medium
- Issue: This code might have edge cases.
- Why it fails: no file, no mechanism, no evidence, no concrete user impact.

The second example teaches the standard. It also gives future reviewers a way to judge whether the skill worked. That is why Agent Skill for Code Review treats evidence as part of the skill contract, not a nice-to-have.

Agents are good at judgment, synthesis, and adapting procedures. They are worse than ordinary code at exact counting, parsing, formatting, and repetitive validation. If the skill requires a mechanical operation, package a script.

Examples:

• A blog-writing skill can include scripts/word_count.js to count body words after frontmatter.
• A data-analysis skill can include scripts/check_schema.py to verify required columns before analysis.
• A release skill can include scripts/changelog_guard.sh to confirm that user-facing changes appear in the changelog.
• A design QA skill can include scripts/screenshot_matrix.ts to capture fixed viewport sizes.

Scripts also reduce ambiguity. "Check the article is between 1,800 and 2,500 words" is useful, but a bundled counter makes the check repeatable. "Preserve frontmatter" is important, but a parser can prove it.

The tradeoff is maintenance. Every script introduces runtime assumptions: language version, dependencies, permissions, operating system behavior, and data location. Keep scripts small, name their expected inputs, and give the agent a fallback if the script cannot run. Do not make the skill fail silently because python points to the wrong interpreter.

Most bad skill runs do not fail because the model is incapable. They fail because the skill never says what to do when reality is messy.

Write the failure paths directly:

• If a required file is missing, report blocked: missing file and name the path.
• If two sources disagree, cite both and explain the discrepancy instead of choosing the more convenient one.
• If a command fails, include the command, exit status, and the relevant stderr.
• If the user asks for a destructive operation, stop and ask for approval.
• If the task expands beyond the skill's scope, complete the in-scope portion and name the out-of-scope follow-up.

Security belongs in this section too. Anthropic warns that skills can introduce vulnerabilities because they contain instructions and code that may direct an agent toward unintended actions or data exposure (Anthropic engineering post). Community discussions around skill runtime structure often converge on the same separation: keep skill source immutable and put mutable project data somewhere explicit, rather than letting a skill write state into its own package (Reddit discussion on skill source vs skill data).

A skill folder should behave like source code: reviewed, versioned, and safe to reinstall. Run artifacts, credentials, customer data, screenshots, and temporary exports should live in the project workspace or a declared output directory.

Do not evaluate a skill by asking whether the final prose "sounds good." Evaluate whether the workflow produced the right behavior.

For each skill, keep a small test set:

• three requests that should trigger the skill
• three adjacent requests that should not trigger it
• two happy-path tasks with expected output shape
• two blocked tasks with expected blocker reports
• one adversarial task that tries to expand scope or skip approval

OpenAI's skill eval guide recommends manual triggering first because it exposes hidden assumptions quickly, then compact prompt sets that can be repeated as the skill changes (Testing Agent Skills Systematically with Evals). Anthropic defines an eval as an input plus grading logic that measures success; for skills, the grading logic checks activation, tool use, evidence, and output quality (Anthropic on agent evals).

Skillfully's Measuring Agent Skill Quality goes deeper on quality signals after real use. For authoring, start with a smaller loop:

1. Run the skill on a realistic task.
2. Record what it did wrong.
3. Patch the instruction that would have prevented that failure.
4. Run the same task again.
5. Add the task to your regression set if it represents a likely repeat failure.

The best eval cases are boring and specific. "Write better" is hard to grade. "When the article has no external sources, the skill must block drafting and request research" is easy to grade.

A skill is a versioned workflow. Treat it that way.

Keep a short changelog:

## 2026-04-25

- Tightened trigger to article brief reviews only.
- Added blocked path for missing source list.
- Moved long publication checklist to `references/publication-checklist.md`.
- Added `scripts/count_body_words.js`.

Version changes by behavior, not by vibes. A meaningful update changes one of these:

• when the skill activates
• what context it loads
• what steps it performs
• what evidence it requires
• what output it returns
• what it refuses to do
• how it validates completion

When a skill becomes popular, resist the urge to turn it into a catch-all. Add companion skills instead. Five Agent Skill Design Patterns is useful here because it separates checklist skills, research skills, review skills, transformation skills, and operating skills. Different patterns deserve different tests.

Maintenance also means pruning. Remove examples that no longer match the workflow. Delete references that agents never need. Replace aspirational language with instructions grounded in actual runs. If users keep overriding the skill, the skill is either too broad, too rigid, or missing the real decision point.

Before publishing or reinstalling a skill, review it against this checklist:

• The description names the task, trigger, and important exclusions.
• The first screen of SKILL.md explains the job, stop rule, and first inspection step.
• Required inputs are named explicitly.
• The output format is clear enough for another person to judge.
• Examples show good and bad outputs.
• Long reference material lives in references/, not the middle of the workflow.
• Mechanical checks live in scripts when a script would be more reliable than prose.
• Failure modes include missing files, conflicting evidence, failed commands, missing permissions, and scope expansion.
• Destructive actions and sensitive data handling have explicit approval rules.
• The skill has at least a small trigger and regression test set.
• The last revision was based on a real failure, not a vague desire to make the skill more impressive.

Better skills feel less like clever prompts and more like durable work standards. They tell the agent where to look first, what tradeoffs matter, what proof counts, and when to stop. That is the difference between a reusable skill and another instruction blob that works only when the task is easy.