writing-skills

To write Claude skills using TDD principles, you document rules, workflows, and validation steps by first running a baseline test to observe failures, then implementing the minimal skill to address those failures.

Progressive disclosure in skill documentation is an organizational strategy that loads additional references and content only when needed, ensuring clear discovery and robust execution without overwhelming the Claude agent upfront.

To structure a SKILL.md file for Claude agents, include frontmatter containing the skill name and description, ensure content adheres to structure guidelines, and wire references or executables for on-demand loading.

Yes, you can reuse and reference other skills within a new SKILL.md by linking to existing skills and standards, which promotes cross-skill referencing and reduces duplication across your Claude agent workflows.

The best way to validate Claude skill documentation is through a TDD-aligned cycle: validate failure cases, implement minimal rules to close gaps, and refactor until no new rationalizations appear in the skill.

Claude skills fail to load references on demand when the SKILL.md content does not adhere to progressive disclosure guidelines or when references and executables are not properly wired for on-demand loading.