write-a-skill

To write a Claude skill, draft a SKILL.md file with YAML frontmatter containing a name and description, then add operational instructions and progressive disclosure to separate quick steps from deeper agent workflows. This structure ensures discoverability and reduces omissions in your agent skill directory.

Progressive disclosure in skill writing is the practice of separating quick operational instructions from deeper workflows to keep the SKILL.md maintainable. You should use progressive disclosure when your agent workflows contain both simple triggers and complex multi-step processes that require reference organization.

Structure a new agent skill directory by creating a SKILL.md with YAML frontmatter, then add bundled artifacts like reference files and utility scripts for deterministic validation tasks. Split content into additional files when the skill scope requires supporting references that would otherwise clutter the main instructions.

You should split skill content into additional reference files when your agent workflows require detailed supporting documentation or deterministic scripts that exceed quick operational instructions. Keeping these bundled artifacts separate maintains the progressive disclosure structure and prevents the SKILL.md from becoming unmanageable.

Yes, you need YAML frontmatter with both a name and description to create a valid agent skill. These fields satisfy the core requirements for skill authoring by enabling discoverability and defining the triggers and scope that Claude uses to identify when the skill should activate.

Yes, you can include deterministic utility scripts in your Claude skill as bundled artifacts alongside your documentation. Adding these validation-style scripts ensures the skill stays reliable for tasks requiring consistent outputs, while the SKILL.md provides the prompt structure and operational guidance.