writing-skills

Writing-skills is a professional methodology designed for software engineering agents to implement Test-Driven Development (TDD) principles within their own process documentation. By treating documentation as code, this skill ensures that instructions remain accurate, actionable, and resilient against agent misinterpretation. It is designed for developers and AI agents that need to manage complex, multi-step workflows while maintaining strict compliance with project standards.

The core of this skill is the RED-GREEN-REFACTOR cycle applied to documentation. Instead of writing static guidelines, agents create pressure scenarios to test their own understanding of instructions. If an agent violates a rule during a baseline test (RED), the skill requires updating the documentation to address the specific root cause of the violation. The agent then performs a verification (GREEN) to ensure the documentation now prevents the previous failure. This approach eliminates ambiguity and forces clarity, effectively turning documentation into a reliable, executable reference system.

• Enables Test-Driven Development for technical documentation and agent instructions.

• Facilitates automated verification using subagent pressure scenarios to mimic real-world task environments.

• Implements iterative refactoring to close loopholes and resolve edge-case rationalizations used by agents.

• Provides a robust mapping system to ensure documentation aligns with expected behavior, preventing drift in long-term projects.

• Standardizes skill development, including frontmatter specifications and directory structures for maintainable knowledge bases.

• Use this skill when you need to teach an agent a new, reliable technique or pattern that must be applied across multiple projects.

• Requires familiarity with the RED-GREEN-REFACTOR cycle; if an agent is failing to comply with rules, use this skill to codify the fix and verify it through testing.

• Ideal for documenting complex system patterns, API usage guides, and recurring engineering workflows where precision is required.

• Before creating a skill, always perform a baseline check to observe the agent's current failure patterns, then write the documentation to specifically address those gaps.

• Keep documentation concise and focused on triggering conditions, using 'Use when' phrasing to optimize for search and retrieval during task execution.

• Do not use for one-off tasks; save this process for techniques, patterns, or tools that have lasting, broad relevance in the engineering lifecycle.