writing-skills

TDD for documentation applies a RED-GREEN-REFACTOR lifecycle to skill writing, turning informal notes into structured, testable artifacts. You run baseline tests first, write the documentation to pass them, and refactor for consistency and quality.

To create an OpenCode Skill, follow the RED-GREEN-REFACTOR workflow: establish baseline tests, draft the SKILL.md with required frontmatter fields, and iterate through testing and refactoring until the skill documentation passes all validation checks.

The validation process ensures SKILL.md frontmatter includes all required metadata fields, validates their structure, and coordinates optional resources like scripts, references, and assets to maintain progressive disclosure and discovery-friendly organization.

Yes, the TDD-driven documentation workflow requires establishing baseline tests before writing the SKILL.md. This prevents rationalization and ensures your skill artifacts remain testable and structurally sound throughout the refactoring cycle.

Using a TDD lifecycle for documentation prevents rationalization by enforcing a bulletproof RED-GREEN-REFACTOR cycle. This ensures your skill docs remain testable, consistent, and structurally validated rather than relying on informal, unstructured notes.

You should avoid TDD for documentation if your workflow lacks automated baseline tests or if your skills do not rely on structured SKILL.md files and frontmatter validation, as the RED-GREEN-REFACTOR lifecycle depends on iterative test execution.