How do I make my skills context-efficient?

Keep frequently-loaded skills under 200 words, use cross-references instead of repeating instructions, and move technical details to tool help commands.

What does it mean to apply TDD to writing skills?

It means you write a test case (a pressure scenario) and watch the agent fail before writing the actual documentation. You then write the skill and verify the agent now complies.

When is the right time to create a new skill?

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

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

If the description summarizes the process, Claude may follow that shortcut and skip reading the detailed instructions in the main skill body, leading to missed steps.

Skill Authoring & Documentation TDD

Name: Skill Authoring & Documentation TDD
Author: julianromli

byjulianromli

•

101

•

Developer Tools

Applies Test-Driven Development principles to the creation and validation of agent skills and documentation.

This skill provides a rigorous framework for authoring Claude Code skills by treating documentation as production code and agent behavior as test results. By following a strict Red-Green-Refactor cycle—writing pressure scenarios, observing baseline failures, and then drafting targeted documentation—developers ensure that their custom skills actually improve agent performance and aren't just redundant text. It emphasizes Claude Search Optimization (CSO) to ensure skills are discoverable and context-efficient.

Key Features

01101 GitHub stars

02Token-efficient documentation patterns

03Claude Search Optimization (CSO) guidelines

04Red-Green-Refactor cycle for documentation

05Pressure scenario testing with subagents

06Standardized SKILL.md structure templates

Use Cases

01Authoring new domain-specific skills for Claude Code

02Optimizing existing skills for better discovery and lower context usage

03Verifying agent compliance through baseline failure testing

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add julianromli/opencode-template writing-skills

For use in Claude.ai and ChatGPT

Download Skill