writing-skills

Apply test-driven development cycles to SKILL.md documentation and YAML frontmatter.

Updated Dec 15, 2025

Search Tags:#documentation #red-green-refactor #quality-assurance #SKILL.md #test-driven-development #skill-writing

Ready to run

npx skills add https://github.com/scruffydan/AI-Agents --skill writing-skills-scruffydan

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: writing-skills
Source: https://github.com/scruffydan/AI-Agents/tree/main/source/skills/writing-skills
Command: npx skills add https://github.com/scruffydan/AI-Agents --skill writing-skills-scruffydan

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Writing skills provide a disciplined approach to creating, editing, and validating skill definitions using Test-Driven Development principles applied to process documentation. It ensures that every skill is tested before deployment and that documentation captures the intended behaviors and edge cases rather than just narrative explanations.

Core Features & Use Cases

TDD workflow for skills: RED-GREEN-REFACTOR cycles applied to documentation and frontmatter.
Frontmatter discipline: Enforces YAML with name and description, plus concise, trigger-focused descriptions.
Structured guidance: Provides sections for overview, triggering conditions, core patterns, quick start, and deployment readiness.
Quality checks: Includes common pitfalls, red flags, and deployment checklist to ensure tested skills.

Quick Start

Create a new directory skill-name.
Add SKILL.md with frontmatter name and description that start with "Use when...".
Write a baseline pressure scenario without the skill, then implement the skill, and re-run tests.

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 skill documentation?▼

Test-driven development for skill documentation uses red-green-refactor cycles to draft, verify, and deploy SKILL.md files. You write a baseline pressure scenario before implementation, then refine the documentation until it passes defined quality checks.

What is the required format for SKILL.md frontmatter?▼

SKILL.md frontmatter requires YAML syntax containing name and description fields. Descriptions must be concise and trigger-focused, ideally starting with 'Use when...' to ensure consistent quality checks before deployment across the skill namespace.

How do I validate skill readiness before deployment?▼

Validate skill readiness using a deployment checklist that reviews common pitfalls and red flags. Structured guidance ensures documentation captures intended behaviors and edge cases, confirming the skill passes all quality assurance checks.

Can I use TDD workflows for revising existing skill definitions?▼

TDD workflows apply to both drafting and revising skill definitions. The red-green-refactor cycle evaluates existing SKILL.md entries against baseline tests, ensuring structured updates maintain description quality and trigger accuracy.

What sections should I include when writing a SKILL.md file?▼

A SKILL.md file should include structured sections for overview, triggering conditions, core patterns, quick start, and deployment readiness. Optional references to scripts or assets can be added to support the skill's intended behaviors.

Why does my skill documentation fail quality assurance checks?▼

Skill documentation fails quality assurance when it lacks structured sections, proper YAML frontmatter, or trigger-focused descriptions. Documenting narrative explanations instead of intended behaviors and edge cases also causes deployment readiness failures.