writing-skills

To write agent skills that are followed, include YAML frontmatter with name and description, add concise operational guidance, and validate the SKILL.md file loads from its root directory. This structure ensures reusable instructions are discoverable and resilient against incomplete execution.

A SKILL.md file is a standalone document containing YAML frontmatter and operational guidance that turns a repeatable workflow or best practice into an agent skill. You need it when creating reusable instructions for prompt engineering workflows that other agents should reliably follow.

You validate existing skill documentation by reviewing the SKILL.md structure, confirming discoverability from its root directory, checking YAML frontmatter completeness, and evaluating token efficiency of the operational guidance to ensure resilient and reusable agent instructions.

Yes, YAML frontmatter with name and description is required to create a new skill for subagents. This frontmatter ensures the skill can be discovered and loaded properly, providing the necessary metadata for agents to locate and follow the operational guidance.

Yes, you can include optional support files for scripts, references, or assets when authoring agent skills. These complement the core SKILL.md file and its operational guidance, providing additional context and functionality for reusable agent instructions.

Agent skills fail to load correctly when the SKILL.md file lacks proper YAML frontmatter, contains verbose operational guidance instead of concise instructions, or cannot be discovered and loaded from its root directory. Validating structure and discoverability resolves these execution issues.