Creating Skills

Document skills using test-driven development with a RED-GREEN-REFACTOR workflow.

Updated Nov 27, 2025
One-click install
npx skills add https://github.com/barrydobson/dotfiles_extra --skill creating-skills-barrydobson
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: Creating Skills
Source: https://github.com/barrydobson/dotfiles_extra/tree/main/packages/claude/dot-claude/skills/meta/creating-skills
Command: npx skills add https://github.com/barrydobson/dotfiles_extra --skill creating-skills-barrydobson

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill provides a systematic, TDD-driven approach to creating high-quality, bulletproof AI skills. It ensures that new skills are effective, discoverable, and resistant to AI rationalization, preventing the deployment of untested or ineffective process documentation.

Core Features & Use Cases

  • TDD for Documentation: Applies the RED-GREEN-REFACTOR cycle to skill creation, starting with baseline testing to identify AI failures.
  • Skill Structure & Content: Guides on organizing SKILL.md with rich when_to_use, clear overviews, and concise examples.
  • Claude Search Optimization (CSO): Provides critical techniques for making skills easily discoverable by future Claude instances through keyword coverage, descriptive naming, and token efficiency.
  • Bulletproofing Against Rationalization: Teaches how to explicitly counter AI rationalizations with specific negations, rationalization tables, and red flags.
  • Use Case: When you identify a new best practice or tool worth documenting for your AI, use this skill to systematically create, test, and refine the skill until it reliably guides your AI's behavior under pressure.

Quick Start

To create a new skill, first identify a technique or pattern. Then, before writing the skill, run a baseline test (RED phase) with a subagent to see how it naturally behaves without the skill. Document its failures and rationalizations. Only then, write your skill (GREEN phase) to address those specific failures.

Frequently Asked Questions about Creating Skills

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

FAQPage Schema
How do I use test-driven development to document AI skills?

TDD for skill documentation starts with a RED phase: run baseline tests with a subagent to identify how AI behaves without your skill, then document failures. In the GREEN phase, write the skill to address those specific failures. Finally, REFACTOR to optimize clarity and coverage. This cycle ensures skills reliably guide AI behavior under pressure.

What should I include in a skill's SKILL.md file?

A strong SKILL.md contains a clear when_to_use section, concise overview, and specific examples. Structure it with rich context so Claude Search can discover it. Include rationalization tables and red flags that explicitly counter AI rationalization. Organize for inline reuse across projects and cross-file consistency.

How do I make my AI skill discoverable through Claude Search?

Claude Search Optimization (CSO) requires keyword coverage matching your skill's domain vocabulary, descriptive naming conventions, and token-efficient phrasing. Front-load technical terms users search for and avoid burying the skill's function. Ensure consistency across skill references so future Claude instances reliably find and apply your documented behavior.

What does it mean to bulletproof a skill against AI rationalization?

Rationalization occurs when AI justifies ignoring guidance through plausible reasoning. Bulletproof skills include specific negations, rationalization tables listing common excuses AI makes, and red flags that signal when the skill applies. Pressure scenarios tested by subagents reveal rationalizations before deployment.

Can I use this approach for technique, pattern, and reference skills?

Yes. This Skill applies the RED-GREEN-REFACTOR workflow across all skill types: technique skills for procedural guidance, pattern skills for recognizable structures, and reference skills for lookup tables. Subagent-based testing validates each type under pressure. Cross-file reuse ensures consistency regardless of skill category.

What happens if I skip the baseline test phase?

Skipping the RED phase means writing a skill without knowing how AI actually fails in its absence. This risks deploying documentation that doesn't address real rationalization or gaps. Baseline testing identifies the specific failures your skill must solve, making the GREEN phase targeted and effective rather than speculative.