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.
//
Search across all documentation pages
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.
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.
A description with concrete example phrasings ("weekly update," "status report," "team summary") matches a wider range of real requests than a single generic sentence.
A Skill that tries to cover several unrelated jobs produces a vaguer description and matches less reliably than several narrow, single-purpose Skills.
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.
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.
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."
Keep SKILL.md's instructions scannable, and put lengthy templates or style guides in a separate bundled file the body can point to.
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.
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.
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.
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.
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.
Build your first Skill around whatever you already explain to Claude most often - the payoff compounds fastest there.
Splitting a broad idea into distinct Skills, each with its own clear trigger, matches more reliably than one Skill trying to do it all.
A Skill enabled in claude.ai doesn't automatically work in Claude Code or Cowork - each surface needs its own enablement step.
Disable or remove Skills you no longer rely on - fewer, more distinct descriptions keep discovery cleaner as your library grows.
When testing or debugging, asking "which Skill did you use for that?" is a fast, reliable way to check whether a match actually happened.
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.
SKILL.md; bundled files are for genuinely long reference material.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.
Reviewed by Chris St. John·Last updated Jul 18, 2026