superpowers-writing-skills

To write agent skills documentation that Claude can discover and apply correctly, structure the frontmatter with essential metadata and organize the body using progressive-disclosure patterns so the agent loads only what is needed, when needed.

Progressive disclosure in skill writing is a content organization pattern that structures documentation so Claude loads only what is needed, when needed, reducing misinterpretation and deployment risk across discipline-enforcing and reference-style skills.

Yes, you can use test-driven development to evaluate and refine skill documentation by implementing RED-GREEN-REFACTOR workflows with subagents, tracking rationalizations, and iteratively refining the skill body based on evaluative tests.

Yes, this skill writing approach works for both discipline-enforcing and reference-style skills across Claude Code and pi-coding-agent ecosystems, ensuring structured frontmatter and body formats that support correct loading in the appropriate context.

The best way to structure frontmatter and body content for a new agent skill is to include essential metadata like name and description in the frontmatter, then apply progressive-disclosure patterns in the body with RED-GREEN-REFACTOR workflows and evaluative tests.

Agent skills fail to load or get misinterpreted by Claude when frontmatter lacks essential metadata like name and description, or when the body does not follow progressive-disclosure patterns, increasing misinterpretation and deployment risk.