writing-skills

Create and validate Skills documentation using test-driven development patterns.

1|Updated Apr 17, 2026

Search Tags:#workflow #documentation #discovery #quality #claude-skills #test-driven-development #skill-writing

Ready to run

npx skills add https://github.com/esneiderbravo/hackaton --skill writing-skills-esneiderbravo

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: writing-skills
Source: https://github.com/esneiderbravo/hackaton/tree/main/.github/skills/writing-skills
Command: npx skills add https://github.com/esneiderbravo/hackaton --skill writing-skills-esneiderbravo

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Writing Skills provide a test-driven approach to documenting and validating skill definitions, ensuring consistent structure and reliable deployment of Claude skills.

Core Features & Use Cases

TDD-based skill creation: draft failing baseline tests, then compose the SKILL.md to pass them.
Rationalization capture and verification: record agent rationalizations during RED and verify compliance in GREEN.
Progressive disclosure guidance: structure frontmatter with clear sections and link heavy references only when needed.
Discovery-friendly metadata: concise, searchable SKILL.md fields to improve Claude's retrieval and loading decisions.

Quick Start

Draft the SKILL.md frontmatter with name and description, then perform RED-GREEN-REFACTOR cycles to verify the skill's behavior.

Frequently Asked Questions about writing-skills

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

FAQPage Schema

How do I apply test-driven development to write Claude skill documentation?▼

Test-driven skill writing involves drafting failing baseline tests for your SKILL.md, then composing the documentation to pass them through RED-GREEN-REFACTOR cycles. This ensures baseline failures are captured and addressed before deployment.

What is the required structure for a SKILL.md file to ensure reliable discovery?▼

A reliable SKILL.md requires YAML frontmatter with name and description fields, followed by a concise body defining triggering conditions, patterns, and minimal implementation details. This discovery-friendly metadata improves Claude's retrieval and loading decisions.

How do I validate existing skill definitions before deployment?▼

You validate existing skill definitions by running RED-GREEN-REFACTOR cycles to verify consistent frontmatter and navigable content. This process checks agent rationalizations and ensures baseline failures are addressed before deployment.

Does writing Claude skills require heavy reference documentation in the SKILL.md body?▼

No, skill writing uses progressive disclosure guidance to structure frontmatter with clear sections and link heavy references only when needed. The SKILL.md body should contain minimal implementation details rather than exhaustive documentation.

How do I capture and verify agent rationalizations during skill creation?▼

Agent rationalizations are recorded during the RED phase when baseline tests fail, then verified for compliance during the GREEN phase. This TDD-driven approach ensures the final skill definition meets the required behavior.

What's the best way to automate skill documentation quality checks?▼

Automating skill documentation quality checks requires applying test-driven development patterns to capture and address baseline failures. This ensures consistent frontmatter structure and navigable content across newly created or edited skills.