write-a-skill

Structure agent skills by creating a root SKILL.md with YAML frontmatter containing name and description, then split advanced details into linked files like REFERENCE.md and EXAMPLES.md to enable progressive disclosure and quick loading.

Progressive disclosure in skill authoring is the practice of splitting advanced operational details into linked files like REFERENCE.md, keeping the root SKILL.md focused. Use it when skills contain large content or deeper references that would slow down quick loading.

Create deterministic scripts by bundling them into a scripts directory only when tasks require validation and explicit error handling. This ensures the agent skill produces consistent, reliable outputs for predictable operations.

Yes, YAML frontmatter in SKILL.md is required for agent skill discovery. It must include the name and description fields, which allow the skill to be found and reliably activated by users and systems.

Organize reference documentation by placing concise operational guidance in SKILL.md, then moving deeper references and examples into separate REFERENCE.md and EXAMPLES.md files. This structure prevents missing metadata and poorly organized resources.

Avoid using deterministic scripts in an agent skill when tasks are not predictable or do not benefit from validation and explicit error handling. In these cases, rely on structured instructions within SKILL.md instead of bundled scripts.