Agent Skills Best Practices
A working Skill is mostly a matter of habit, not complexity - the same handful of practices show up across every reliable Skill library.
The list below covers writing, naming, and maintaining Skills so that Claude finds them when it should and only when it should.
1. Write the Description Like a Trigger, Not a Label
State what the Skill does and when to use it, using the actual words someone would type to ask for that task - not an abstract category name.
2. Include Two or Three Real Trigger Phrases
A description with concrete example phrasings ("weekly update," "status report," "team summary") matches a wider range of real requests than a single generic sentence.
3. Keep Each Skill Focused on One Task
A Skill that tries to cover several unrelated jobs produces a vaguer description and matches less reliably than several narrow, single-purpose Skills.
4. Test With Natural Phrasing, Not a Generic Test Message
Validate a new Skill using the exact kind of request you'd actually type in real work, since that's what discovery has to succeed against.
5. Confirm a Match Before Blaming the Instructions
If output doesn't match what a Skill describes, check whether the Skill fired at all before revising its body - a discovery miss and a bad instruction produce the same symptom.
6. Give the Body Clear, Specific Steps
Write instructions the way you'd explain the task to a capable new teammate - concrete steps or rules, not vague goals like "do this well."
7. Move Long Reference Material Out of the Body
Keep SKILL.md's instructions scannable, and put lengthy templates or style guides in a separate bundled file the body can point to.
8. Scope Tool Access Deliberately
Set allowed-tools when a Skill should only be able to do part of what the surface allows - for example, reading but not writing files.
9. Give Skills a Stable, Descriptive Name
Use a name that still makes sense to you months later, since it's what you'll recognize the Skill by while managing a growing library.
10. Avoid Overlapping Descriptions
Check a new Skill's description against your existing ones - if two describe similar territory, Claude has to choose, and the result becomes less predictable.
11. Revise the Description Before the Body When Something Feels Off
The description is cheaper to test and iterate on than the full instructions, and it's the more common source of a Skill not behaving as expected.
12. Revisit Descriptions After Terminology Changes
A rebrand, a renamed report, or a new process can quietly break a description that used to match perfectly - review Skills after any such change.
13. Start With Your Most Repeated Task
Build your first Skill around whatever you already explain to Claude most often - the payoff compounds fastest there.
14. Prefer Several Narrow Skills Over One Broad One
Splitting a broad idea into distinct Skills, each with its own clear trigger, matches more reliably than one Skill trying to do it all.
15. Enable a Skill on Every Surface You Actually Use It On
A Skill enabled in claude.ai doesn't automatically work in Claude Code or Cowork - each surface needs its own enablement step.
16. Periodically Prune Unused Skills
Disable or remove Skills you no longer rely on - fewer, more distinct descriptions keep discovery cleaner as your library grows.
17. Ask Claude Directly to Confirm Discovery
When testing or debugging, asking "which Skill did you use for that?" is a fast, reliable way to check whether a match actually happened.
18. Treat a Skill Like Living Documentation
Update a Skill's instructions the same way you'd update any process doc - when the real process changes, the Skill should change with it, not drift out of sync.
FAQs
Which of these matters most if I can only fix one thing?
- The description field - specific, trigger-worded descriptions fix more discovery problems than any other single change.
Should every Skill have a bundled reference file?
- No - most simple Skills need only
SKILL.md; bundled files are for genuinely long reference material.
How many Skills is too many?
- There's no fixed number - the practical limit is how distinct you can keep each description as the library grows.
Is it bad practice to have two Skills for similar tasks?
- Not inherently, as long as their descriptions are narrow enough to stay distinct - the problem is overlap, not similarity of topic.
How often should I review my Skill library?
- Whenever a discovery problem shows up, and periodically as a general habit, especially after process or terminology changes.
Do these practices apply the same way across Claude Code, Cowork, and claude.ai?
- Yes - the writing and maintenance practices are the same everywhere; only enablement is surface-specific.
Related
- What Are Agent Skills? - the foundational concept behind every practice above
- How Claude Discovers and Loads Skills Automatically - why description quality matters this much
- Signs Your Skill Isn't Being Discovered by Claude - what it looks like when these practices are skipped
- Anatomy of a SKILL.md File - where each of these practices lives in the file
Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5. Model names, pricing, and product features move quickly - verify current specifics at platform.claude.com/docs before relying on them.