Best Practices and Anti-Patterns
What Makes a Skill Excellent
Across everything in this course, a handful of practices separate skills that quietly work from skills that frustrate. They all flow from two ideas: the description determines whether the skill is used, and context is a budget you should spend carefully.
- 1.Start from a real pain point — the best skills come from instructions you actually repeat.
- 2.Write a specific description that names what the skill does AND when to use it, echoing the phrases you'd really type.
- 3.Keep SKILL.md concise (under 500 lines) and push detail into supporting files via progressive disclosure.
- 4.Bundle scripts for deterministic work and tell Claude to RUN them, not read them.
- 5.Limit and pre-approve tools deliberately with allowed-tools; restrict with disallowed-tools or permissions.
- 6.Use disable-model-invocation: true for anything with side effects (deploys, sends) so Claude can't auto-run it.
Be concise — every line is a recurring cost
Once a skill is invoked, its content stays in context for the session. So state WHAT to do rather than narrating how or why, and apply the same conciseness test you would to CLAUDE.md. A bloated skill taxes every subsequent turn.
Description Discipline
Because the description is doing the matching, it deserves the most care. A good description is specific, keyword-rich, and distinct from your other skills.
| Do | Don't |
|---|---|
| Name the action + the trigger ('Reviews PRs. Use when reviewing a PR or diff.') | Be vague ('helps with code') |
| Echo the phrases users actually type | Assume Claude infers your intent |
| Make each skill's description distinct | Let several skills sound the same |
| Put the key use case first (1,536-char cap) | Bury the trigger keywords at the end |
Description discipline is the highest-leverage habit — it controls whether the skill ever runs.
Anti-Patterns to Avoid
Just as important as best practices is knowing what NOT to do. These are the recurring mistakes that make skills unreliable or wasteful.
- •Vague descriptions — the #1 reason skills don't trigger.
- •Near-duplicate descriptions across skills — causes the wrong one to fire.
- •Cramming everything into one giant SKILL.md — wastes context and is unmaintainable.
- •Putting always-on facts in a skill — that belongs in CLAUDE.md; skills are for on-demand task expertise.
- •Letting Claude auto-invoke side-effecting skills (deploy, send) — gate them with disable-model-invocation: true.
- •Expecting subagents to inherit your skills — they don't; list them in the subagent's skills: field.
- •Reading a script into context instead of running it — defeats progressive disclosure.
Right tool for the job
Don't force everything into skills. Always-on standards → CLAUDE.md. Event-driven automation → hooks. Isolated delegated work → subagents. External integrations → MCP. Skills are for task-specific expertise Claude should apply automatically when relevant — combine features rather than overloading one.
A Quality Checklist
Before you ship a skill — especially a shared one — run it through this checklist to catch the common problems proactively.
- 1.Does the description name both WHAT it does and WHEN to use it, with the phrases you'd actually type?
- 2.Is it distinct from your other skills' descriptions?
- 3.Is SKILL.md under ~500 lines, with detail in supporting files?
- 4.Are scripts referenced with ${CLAUDE_SKILL_DIR} and run, not read?
- 5.Are tools pre-approved/restricted appropriately, and side-effect skills set to manual-only?
- 6.For shared/project skills: have you reviewed it for safe tool access before trusting the repo, and validated its structure?
Next
You now know how to build skills that work the first time. The final lesson consolidates the whole course and gives you exam-focused pointers.
Key Takeaways
- ✓Excellent skills flow from two ideas: the description determines use, and context is a budget — be specific and concise.
- ✓Best practices: start from a real pain point, write a specific keyword-rich description, keep SKILL.md under 500 lines, run (don't read) bundled scripts, and set side-effecting skills to manual-only.
- ✓Once invoked, a skill's content stays in context for the session, so state WHAT to do tersely — every line is a recurring token cost.
- ✓Description discipline is the highest-leverage habit: name the action + trigger, echo real phrasing, keep each distinct, and front-load the key use case.
- ✓Anti-patterns: vague or near-duplicate descriptions, one giant SKILL.md, always-on facts in a skill, auto-invoking side-effect skills, and expecting subagents to inherit skills.
- ✓Use the right feature: CLAUDE.md for always-on facts, hooks for events, subagents for delegation, MCP for integrations — skills for on-demand task expertise.
Check Your Understanding
Test what you learned in this lesson.
Q1.Why should a skill's SKILL.md be kept concise?
Q2.Which is a skill anti-pattern?
Q3.How should you handle a skill that has side effects, like /deploy?
Q4.What's the highest-leverage habit for reliable skills?
Practice This Lesson