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

Quick Reference

1. Skill Metadata Design (CRITICAL)

• meta-name-format – Use lowercase hyphenated skill names
• meta-name-hyphen-boundaries – Never start or end names with hyphens
• meta-name-no-consecutive-hyphens – Avoid consecutive hyphens in names
• meta-name-uniqueness – Ensure skill names are globally unique
• meta-required-frontmatter – Include all required frontmatter fields
• meta-allowed-frontmatter-fields – Use only allowed frontmatter fields
• meta-frontmatter-yaml-syntax – Use valid YAML frontmatter syntax
• meta-name-length – Keep skill names under 64 characters
• meta-directory-match – Match skill name to directory name

2. Description Engineering (CRITICAL)

• desc-specific-capabilities – Name specific capabilities in description
• desc-trigger-keywords – Include user trigger keywords in description
• desc-third-person-voice – Write descriptions in third person
• desc-length-optimization – Optimize description length for discovery
• desc-avoid-vague-terms – Avoid vague terms in descriptions
• desc-differentiate-similar-skills – Differentiate similar skills with distinct triggers
• desc-include-negative-cases – Include negative cases for precision

3. Content Structure (HIGH)

• struct-header-hierarchy – Use consistent header hierarchy
• struct-instructions-first – Put critical instructions early in content
• struct-imperative-instructions – Write instructions in imperative mood
• struct-code-blocks-with-language – Specify language in code blocks
• struct-line-limit – Keep SKILL.md under 500 lines
• struct-single-responsibility – One skill per domain

4. Trigger Optimization (HIGH)

• trigger-slash-command-aliases – Include slash command aliases in description
• trigger-file-type-patterns – Include file type patterns in description
• trigger-workflow-stages – Reference workflow stages in description
• trigger-error-patterns – Include error patterns in debugging skills
• trigger-synonym-coverage – Cover synonyms and alternate phrasings

5. Progressive Disclosure (MEDIUM-HIGH)

• prog-three-level-disclosure – Implement three-level progressive disclosure
• prog-one-level-deep-links – Limit reference links to one level deep
• prog-scripts-execute-not-read – Execute scripts instead of reading code
• prog-lazy-load-examples – Lazy load examples and reference material
• prog-mutual-exclusion – Separate mutually exclusive contexts

6. MCP Tool Design (MEDIUM)

• mcp-tool-naming – Use clear action-object tool names
• mcp-parameter-descriptions – Document all tool parameters
• mcp-error-messages – Return actionable error messages
• mcp-tool-scope – Design single-purpose tools
• mcp-allowed-tools – Use allowed-tools for safety constraints
• mcp-idempotent-operations – Design idempotent tool operations

7. Testing and Validation (MEDIUM)

• test-trigger-phrases – Test skill activation with real user phrases
• test-edge-cases – Test skills with edge case inputs
• test-negative-scenarios – Test that skills do NOT trigger on unrelated requests
• test-instruction-clarity – Test instructions with fresh context

8. Maintenance and Distribution (LOW-MEDIUM)

• maint-semantic-versioning – Use semantic versioning for skill releases
• maint-changelog – Maintain a changelog for skill updates
• maint-plugin-packaging – Package skills as plugins for distribution
• maint-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

References

• skills-ref specification
• Anthropic Engineering: Agent Skills
• Claude Code Skills Documentation
• Anthropic Skills Repository
• MCP Best Practices
• Prompt Engineering Guide: LLM Agents
• Claude Skills Deep Dive