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 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

skill-authoring