AI Agent Skills Best Practices
Design and development guide for AI agent skills, including Claude Code skills and MCP tools. Contains 46 rules across 8 categories, prioritized by impact to guide skill creation, review, and optimization.
When to Apply
- Creating new Claude Code skills or MCP tools
- Writing or reviewing SKILL.md metadata and descriptions
- Optimizing skill trigger reliability
- Structuring content for progressive disclosure
- Testing skill activation and behavior
- Designing tool interfaces for agent workflows
Core Principles
1. Descriptions drive activation. Claude selects skills based on description matching against user intent. Include specific capabilities, trigger keywords, and negative cases. A skill with a vague description activates inconsistently or never.
2. Front-load critical instructions. Claude may truncate long content. Place non-negotiable rules in the first 100 lines. Bury important constraints at the end and they get ignored.
3. Progressive disclosure saves tokens. Load detailed content only when needed. A 2000-line skill wastes context on every activation. Structure as: SKILL.md (overview) → references/ (details) → scripts/ (execution).
4. Test activation, not just execution. A skill that works perfectly but never triggers provides zero value. Test with real user phrases, synonyms, and edge cases before deployment.
5. One skill per domain. Overlapping skills create activation conflicts. Split by clear boundaries (language, framework, workflow stage) with distinct trigger keywords.
Rule Categories
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Skill Metadata Design | CRITICAL | meta- |
| 2 | Description Engineering | CRITICAL | desc- |
| 3 | Content Structure | HIGH | struct- |
| 4 | Trigger Optimization | HIGH | trigger- |
| 5 | Progressive Disclosure | MEDIUM-HIGH | prog- |
| 6 | MCP Tool Design | MEDIUM | mcp- |
| 7 | Testing and Validation | MEDIUM | test- |
| 8 | Maintenance and Distribution | LOW-MEDIUM | maint- |
Quick Reference
1. Skill Metadata Design (CRITICAL)
meta-name-format- Use lowercase hyphenated skill namesmeta-name-hyphen-boundaries- Never start or end names with hyphensmeta-name-no-consecutive-hyphens- Avoid consecutive hyphens in namesmeta-name-uniqueness- Ensure skill names are globally uniquemeta-required-frontmatter- Include all required frontmatter fieldsmeta-allowed-frontmatter-fields- Use only allowed frontmatter fieldsmeta-frontmatter-yaml-syntax- Use valid YAML frontmatter syntaxmeta-name-length- Keep skill names under 64 charactersmeta-directory-match- Match skill name to directory name
2. Description Engineering (CRITICAL)
desc-specific-capabilities- Name specific capabilities in descriptiondesc-trigger-keywords- Include user trigger keywords in descriptiondesc-third-person-voice- Write descriptions in third persondesc-length-optimization- Optimize description length for discoverydesc-avoid-vague-terms- Avoid vague terms in descriptionsdesc-differentiate-similar-skills- Differentiate similar skills with distinct triggersdesc-include-negative-cases- Include negative cases for precision
3. Content Structure (HIGH)
struct-header-hierarchy- Use consistent header hierarchystruct-instructions-first- Put critical instructions early in contentstruct-imperative-instructions- Write instructions in imperative moodstruct-code-blocks-with-language- Specify language in code blocksstruct-line-limit- Keep SKILL.md under 500 linesstruct-single-responsibility- One skill per domain
4. Trigger Optimization (HIGH)
trigger-slash-command-aliases- Include slash command aliases in descriptiontrigger-file-type-patterns- Include file type patterns in descriptiontrigger-workflow-stages- Reference workflow stages in descriptiontrigger-error-patterns- Include error patterns in debugging skillstrigger-synonym-coverage- Cover synonyms and alternate phrasings
5. Progressive Disclosure (MEDIUM-HIGH)
prog-three-level-disclosure- Implement three-level progressive disclosureprog-one-level-deep-links- Limit reference links to one level deepprog-scripts-execute-not-read- Execute scripts instead of reading codeprog-lazy-load-examples- Lazy load examples and reference materialprog-mutual-exclusion- Separate mutually exclusive contexts
6. MCP Tool Design (MEDIUM)
mcp-tool-naming- Use clear action-object tool namesmcp-parameter-descriptions- Document all tool parametersmcp-error-messages- Return actionable error messagesmcp-tool-scope- Design single-purpose toolsmcp-allowed-tools- Use allowed-tools for safety constraintsmcp-idempotent-operations- Design idempotent tool operations
7. Testing and Validation (MEDIUM)
test-trigger-phrases- Test skill activation with real user phrasestest-edge-cases- Test skills with edge case inputstest-negative-scenarios- Test that skills do NOT trigger on unrelated requeststest-instruction-clarity- Test instructions with fresh context
8. Maintenance and Distribution (LOW-MEDIUM)
maint-semantic-versioning- Use semantic versioning for skill releasesmaint-changelog- Maintain a changelog for skill updatesmaint-plugin-packaging- Package skills as plugins for distributionmaint-audit-security- Audit skills before installing from external sources
Creating Rules
Copy assets/templates/_template.md and follow the frontmatter schema:
---
title: Rule Title Here
impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW
impactDescription: Quantified impact (e.g., "2-10x improvement")
tags: prefix, technique, related-concepts
---Reference files use the pattern: references/{prefix}-{slug}.md