# 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]] - [[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]]