What is Test-Driven Development (TDD) for skills?

TDD for skills involves creating a pressure scenario where an agent fails a task, writing the skill documentation to address that specific failure, and then verifying the agent complies with the new instructions.

How does this skill help with context window management?

It provides strategies for token efficiency, such as moving technical details to tool help commands, using minimal code examples, and avoiding forced-loading of cross-referenced skills.

Why shouldn't I summarize the workflow in a skill description?

Summarizing the workflow in the description field creates a 'shortcut' that Claude may follow instead of reading the full skill content, which can lead to the agent skipping critical steps or logic.

When is it appropriate to create a new skill?

Create a skill when a technique isn't intuitively obvious, applies broadly across different projects, or provides a proven pattern that others would benefit from referencing.

Skill Authoring & TDD Documentation

Name: Skill Authoring & TDD Documentation
Author: Ibrahim-3d

byIbrahim-3d

•

291

•

Learning & Documentation

Standardizes the creation and optimization of Claude Code skills using a Test-Driven Development approach to ensure agent compliance.

This skill provides a rigorous framework for authoring, testing, and optimizing Claude Code skills by applying Test-Driven Development (TDD) principles to documentation. It guides users through the Red-Green-Refactor cycle—watching an agent fail a task before writing the skill to fix it—to ensure that every instruction is effective and necessary. It includes specialized guidance on Claude Search Optimization (CSO) and token efficiency, ensuring that skills are both discoverable by the AI and context-friendly.

Key Features

01291 GitHub stars

02Token-efficient documentation patterns and compression techniques

03Cross-referencing logic to prevent context bloat

04Standardized SKILL.md structure with YAML frontmatter validation

05TDD-based skill creation (Red-Green-Refactor for documentation)

06Claude Search Optimization (CSO) for better skill discovery

Use Cases

01Optimizing skill descriptions for faster and more accurate AI retrieval

02Building new domain-specific capabilities for Claude Code agents

03Refactoring existing documentation to improve agent adherence

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add ibrahim-3d/conductor-orchestrator-superpowers writing-skills

For use in Claude.ai and ChatGPT

Download Skill