writing-skills

TDD-driven skill writing applies a RED-GREEN-REFACTOR cycle to validate documentation against baseline agent behavior, ensuring observed failures are remediated before deployment. You write a SKILL.md, run baseline tests, then refactor content for compliance.

Progressive disclosure keeps inline SKILL.md content lean for fast discovery while linking to heavy references when deeper exploration is needed. This minimizes context load and supports multi-domain skills with light references.

SKILL.md templates use lightweight frontmatter with name and description, plus inline guidance for organization, references, and tooling. This structure ensures consistency, testability, and repeatable quality across teams.

Cross-referencing other skills allows modular organization to minimize context load. The guide provides instructions for cross-referencing, enabling cross-skill reuse without duplicating heavy content inline.

Quality assurance checks include capturing rationalizations, monitoring red flags, and running deployment workflows to prevent regressions. These ensure baseline failures are observed and remediated during the RED-GREEN-REFACTOR cycle.

Avoid TDD-driven skill writing when documentation does not require repeatable quality or testability against agent behavior. It is designed for structured process documentation needing compliance validation, not lightweight ad-hoc notes.