writing-skills

To standardize AI agent skills documentation, use a YAML frontmatter-based pattern with required fields like name and description. This ensures consistent discovery and activation across project teams by codifying skill structure in modular files such as SKILL.md.

The modular file layout for organizing Claude AI agent skills places files under .claude/skills/[skill-name]/. This structure includes SKILL.md for core definitions, REFERENCE.md for deeper context, STATE_MACHINE.md for advanced guidance, and supporting examples.

You should create, update, or retire modular AI skills when project requirements or platform capabilities change. Regularly reviewing skills ensures your documentation reflects current needs and prevents outdated workflows from cluttering the system.

Progressive disclosure for AI agent skills works by linking deeper references only when needed. This enables fast startup with basic SKILL.md frontmatter while providing richer depth through supporting files like REFERENCE.md and STATE_MACHINE.md for advanced usage.

Yes, YAML frontmatter is required to structure AI agent workflows effectively. It provides essential metadata like name and description for skill activation, ensuring the skill can be properly discovered and referenced by developers and AI agents.

The best way to catalog and codify AI agent skills is implementing a reusable YAML frontmatter pattern with a modular file layout. This provides concise, production-ready descriptions of skill roles and integration points for developers and Claude-like agents.