AI Skill Best Practices

Canonical version: AI Skill Best Practices.

Principles and patterns for writing effective, maintainable, and reusable AI Agent Skills. Drawn from practical experience building skill libraries.

Structure

• One skill, one job: each skill should do one thing well. Complex workflows should compose smaller skills (AI Skill Composability)
• Progressive disclosure: three levels of detail. Level 1: name + description (always in context, ~100 tokens). Level 2: SKILL.md body (loaded on trigger, <500 lines). Level 3: reference files (loaded as needed)
• Lean by default: every paragraph costs tokens from the Context Budget. After drafting, review with fresh eyes: does this change behavior, or is it noise? Can two paragraphs become one sentence?

Writing

• Imperative voice: "Check for duplicates" not "You should check for duplicates"
• Explain why, not just what: "Validate format before returning; downstream tools break on malformed output" is better than "ALWAYS validate format". Reasoning lets the model apply judgment to edge cases
• One default approach: avoid listing multiple equivalent options. Pick one; note the escape hatch for edge cases
• Consistent terminology: pick one term per concept and stick with it throughout
• No time-sensitive info: use "current method" / "legacy pattern" instead of dates that go stale

Resilience (see AI Skill Resilience)

• No hardcoded paths: use relative references or discovery (glob patterns) instead of absolute paths
• Describe intent, not implementation: "find all TypeScript files" instead of "run find . -name '*.ts'"
• Check before assuming: verify files exist before reading; verify tools are available before calling
• Parameterize variable things: folder names, file patterns, output locations should be configurable, not baked in
• Fail gracefully: when a dependency is missing, explain what's needed instead of producing garbage

Triggering

The description field is the primary triggering mechanism. Get it wrong and the skill never fires.

• Be slightly "pushy": Claude tends to under-trigger. Include concrete trigger keywords
• Cover both what the skill does AND when to use it
• Third person always ("Processes files..." not "I process...")
• Max 1024 characters; be precise, not exhaustive
• Test with realistic queries, not abstract ones

Testing (see AI Skill Testing)

• Write 2-3 realistic test prompts with concrete context
• Run with-skill vs baseline to measure improvement
• Read the transcripts, not just the outputs: how did the model work, not just what did it produce
• If every test run writes a similar helper script, bundle it in the skill

Maintenance

• Version skills meaningfully (AI Skill Versioning)
• Review skills periodically for Context Drift
• Keep reference files one level deep (no chains of files referencing files)
• No extraneous files (README.md, CHANGELOG.md) inside the skill directory
• Descriptive filenames: form_validation_rules.md not doc2.md

Scoping (see AI Skill Scoping)

• Personal skills (~/.claude/skills/) for preferences that apply across all projects
• Project skills (.claude/skills/) for project-specific knowledge
• Plugin skills for team-shared or published skills
• Don't put personal preferences in project skills; don't keep project-critical skills in your personal directory

Anti-patterns

• The novel: a 2000-line SKILL.md that tries to cover everything. Split into smaller skills or use reference files
• The copy-paste: same skill duplicated across projects instead of shared at team level
• The rigid robot: ALWAYS/NEVER rules without reasoning. The model follows them blindly in edge cases
• The optimist: no error handling; assumes every file exists, every tool works, every path is correct
• The overloader: one skill that does five different things depending on input. Split it

References

Related

• AI Agent Skills
• AI Skill Resilience
• AI Skill Testing
• Archify (example: a skill that ships validators and repair hints with its instructions)
• AI Skill Versioning
• AI Skill Scoping
• AI Skill Portability
• AI Skill Composability
• AI Skill Distribution
• Context Budget
• Context Drift
• Prompt Lazy Loading AI Design Pattern (PLL)
• SOLID Principles
• Atomicity
• Design by Contract
• Fail Fast
• Convention over Configuration
• Software Design Patterns for AI Skills and Agents

About Sébastien

Ready to get to the next level?