writing-skills

Create Skill documentation with YAML frontmatter and TDD cycles.

Updated Aug 23, 2026
One-click install
npx skills add https://github.com/bearhedge/APE-YOLO --skill writing-skills-bearhedge
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: writing-skills
Source: https://github.com/bearhedge/APE-YOLO/tree/main/.claude/skills/writing-skills
Command: npx skills add https://github.com/bearhedge/APE-YOLO --skill writing-skills-bearhedge

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill provides a structured, test-driven approach to creating and validating Skill documentation, ensuring discoverability, conciseness, and resistance to rationalization under pressure.

Core Features & Use Cases

  • Enforces YAML frontmatter with exact fields (name and description) at the SKILL.md root for reliable discovery.
  • Guides RED-GREEN-REFACTOR testing cycles to verify Skill correctness before deployment.
  • Supports progressive disclosure, reference organization, and concise inline guidance.

Quick Start

Draft a new Skill directory with SKILL.md containing the frontmatter and a concise description. Run the RED phase to observe baseline behavior, then implement the GREEN skill and REFACTOR to close gaps. Keep content focused and within a single Skill before expanding with references or tools.

Frequently Asked Questions about writing-skills

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write testable process documentation?

Testable process documentation uses a TDD-inspired workflow to verify clarity and correctness before deployment. You draft a SKILL.md with YAML frontmatter, run a RED phase to observe baseline behavior, then implement and REFACTOR to close gaps.

What is the RED-GREEN-REFACTOR cycle for skill writing?

The RED-GREEN-REFACTOR cycle for skill writing verifies documentation correctness: RED observes baseline behavior, GREEN implements the skill, and REFACTOR closes gaps to ensure discoverability and resistance to rationalization under pressure.

How do I structure SKILL.md for reliable discoverability?

To structure SKILL.md for reliable discoverability, include YAML frontmatter with exact name and description fields at the root. Add a concise structured body, keeping content focused before expanding with optional references or scripts.

Can I use TDD for documentation without writing code scripts?

Yes, you can apply TDD for documentation without code scripts by using a structured SKILL.md body. Optional references and scripts provide heavy guidance, but the core workflow relies on progressive disclosure and concise inline guidance.

When should I not use a TDD workflow for skill documentation?

You should avoid a TDD workflow for skill documentation if your environment cannot support YAML frontmatter validation. The framework requires exact name and description fields to ensure discoverability and guardrails against rationalization under pressure.

What's the best way to ensure documentation quality under pressure?

The best way to ensure documentation quality under pressure is applying a TDD-inspired workflow with structured YAML frontmatter. This enforces discoverability, conciseness, and guardrails against rationalization, verifying correctness through progressive disclosure.