writing-skills

Outline the RED-GREEN-REFACTOR workflow for creating and editing SKILL.md files.

Updated Jan 12, 2026

Search Tags:#workflow #tdd #documentation #guidelines #skill-writing #rationalizations

Ready to run

npx skills add https://github.com/miguelarcjr/shark-ai --skill writing-skills-miguelarcjr

💬 Prompt for ChatGPT / Claude Chat▼

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Writing Skills provides a framework for capturing proven techniques as Skills, enabling disciplined, test-driven creation and governance of skill documentation.

Core Features & Use Cases

TDD-inspired workflow for skill creation (RED-GREEN-REFACTOR) and validation
Clear structure for SKILL.md with frontmatter and inline guidance
Guidance on organization, cross-references, and progressive disclosure for efficient discovery

Quick Start

Create a minimal SKILL.md with name and description frontmatter and run a micro-test to verify discovery.

Frequently Asked Questions about writing-skills

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

FAQPage Schema

What is test-driven development for skill documentation?▼

Test-driven development for skill documentation applies the RED-GREEN-REFACTOR workflow to authoring SKILL.md files, ensuring skills are tested and validated before deployment across agent workflows.

How do I create a SKILL.md file with the required frontmatter?▼

To create a SKILL.md file, add YAML frontmatter with required name and description fields, then run a minimal micro-test to verify skill discovery before expanding into full documentation.

Can I edit existing skills using the RED-GREEN-REFACTOR workflow?▼

Yes, the RED-GREEN-REFACTOR workflow applies to editing existing skills, allowing you to test changes and validate progressive-disclosure patterns before updating deployed agent workflows.

What's the best way to structure skill documentation for discovery?▼

The best way to structure skill documentation is using progressive-disclosure patterns with cross-references, inline guidance, and templates for testing, references, and tooling to ensure efficient discovery.

Do I need YAML frontmatter for skill creation and validation?▼

Yes, YAML frontmatter is enforced during skill creation, requiring at minimum name and description fields to validate the SKILL.md file before it can be deployed across agent workflows.