A good skill is not a place to store every thought about a domain. It is a small, durable operating procedure for a task the agent would otherwise perform inconsistently. Start there: not with a template, but with a real repeated workflow.
"Good Skills are concise, well-structured, and tested with real usage." Claude Platform Docs, skill authoring best practices
Start from real work
The best skills come from traces of actual execution: a release checklist that keeps catching the same omissions, a document-formatting workflow with fragile conversion steps, a data analysis routine that needs the same schema every week, or a code review process with project specific risks. If you cannot name the task that activates the skill, it is probably too broad.
Write down what the agent gets wrong without the skill. That list is the raw material. Keep the parts that are non-obvious, project-specific, or easy to mess up. Cut background knowledge that a strong model already has.
Scope the unit like a function
A skill should have one coherent job. "Review a pull request against this repository's release gates" is coherent. "Do all engineering tasks" is not. A skill that is too narrow forces the agent to activate several skills for one ordinary task; a skill that is too broad creates vague triggers and conflicting guidance.
| Too broad | Better scope | Why |
|---|---|---|
| Documents | Generate board-ready quarterly PDFs from the finance template | The trigger, assets, and validation rules are concrete. |
| Backend work | Add a new MCP tool to the existing FastMCP server | The skill can route to exact files, schema rules, and test commands. |
| Marketing | Rewrite launch copy in the company's approved product voice | The skill can carry voice rules and examples without becoming a CMS. |
Write the description first
The description is the skill's activation contract. It should be concise, concrete, and loaded with the words a user will actually use. Include both the capability and the conditions for use. For example:
description: Reviews release readiness for Astro and static websites, including build output, sitemap, robots.txt, source citations, Cloudflare Pages deploys, and final report requirements. Use before publishing or auditing a static site.That description is better than "website helper" because the agent can match it to build, deploy, citation, and report requests. It also makes the boundaries visible.
Design the main file
The main SKILL.md should be the material the agent needs on almost every activation:
mission, triggers, source-of-truth files, required order of operations, validation steps, and
output requirements. It should be easy to skim. Use short sections. Prefer commands and checks
over motivational language.
The most useful sections are often:
- When to use: confirms the trigger and exclusions.
- Workflow: the ordered steps the agent should follow.
- Validation: commands, assertions, or review criteria that define success.
- References: exact file names and conditions for reading them.
- Output: the final artifact shape or response format.
- Gotchas: the small failures agents repeatedly make.
Split for progressive disclosure
Progressive disclosure is not just a storage trick. It is how a skill avoids crowding out the user's active problem. Keep the main file lean. Move stable, detailed material into references. Move fragile operations into scripts. Move templates into assets. Then route the agent with explicit conditions.
Always-needed workflow, validation gates, names of source-of-truth files, and final output contract.
Long API docs, style examples, schema references, template files, and rare error handling details.
Transforms, validators, data extraction, package commands, and any sequence that needs exact repeatability.
Test like users ask
Test prompts should look like real requests. Include casual wording, precise wording, missing context, file paths, and at least one edge case. A skill is working when it triggers for the right jobs, stays out of unrelated jobs, and improves the result after activation.
- Run the task without the skill and save the failure modes.
- Install the skill and rerun realistic prompts.
- Check whether the agent loaded the right reference files or scripts.
- Revise the description if activation is wrong.
- Revise the body if activation is right but execution is weak.
Distribute with expectations
The portable unit is the skill directory. Some clients can read that directory directly; others package skills inside a plugin or an extension mechanism. Distribution should include a README, license decision, compatibility notes, and any runtime dependencies. If a script needs network access, Node, Python, or a private token, say so.
Treat skills as code-adjacent artifacts. Version them. Review diffs. Run tests after edits. Avoid embedding secrets. Avoid time-sensitive facts that will go stale unless the skill is explicitly about checking live sources.