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.