writing-skills

Writing-skills provides a structured, TDD-based methodology for creating, refining, and verifying software agent skills. By treating documentation as code, this system requires developers to define specific pressure scenarios with subagents to establish a baseline of agent behavior before drafting the actual documentation. This ensures that every skill is grounded in empirical validation—watching an agent fail to follow a rule, writing the skill to address that failure, and verifying compliance through subsequent testing. It is designed for engineers and power users building custom skills for coding agents like Claude Code or Codex who need to ensure their documentation is actionable, accurate, and resistant to hallucinations or misinterpretation.

• Implements the RED-GREEN-REFACTOR cycle for process documentation.

• Enables the creation of pressure-test scenarios to validate skill efficacy.

• Provides a flat, searchable namespace for managing complex agent-specific skills.

• Separates documentation into technique, pattern, and reference types for modularity.

• Leverages YAML frontmatter for machine-readable triggering conditions.

• Prevents 'workflow summary' traps where agents might ignore logic in favor of oversimplified descriptions.

• Always run baseline tests before drafting any content to witness original agent rationalizations.

• Use this skill to create reusable techniques, patterns, or tools, not for one-off solutions or project-specific conventions.

• If a task can be solved with regex or automated validation, prioritize automation over manual documentation.

• Structure documentation with clear triggering conditions starting with 'Use when...'.

• Maintain a strictly modular directory structure to allow for easy lookup and integration.

• Use alongside Claude Code or Codex environments to standardize agent behavior during development cycles.

• Ensure documentation is kept concise, avoiding narratives in favor of actionable patterns and code comparisons.