Use when creating new skills, editing existing skills, scaffolding skill directories, packaging skills for distribution, or verifying skills work before deployment. Combines Anthropic's official skill authoring guide with TDD methodology.
Create effective skills using TDD methodology with scaffolding scripts.
Skills are TDD applied to process documentation. Write test cases (pressure scenarios), watch them fail (baseline behavior), write the skill, watch tests pass, and refactor.
Core principle: If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.
# Initialize new skill
scripts/init_skill.py my-skill --path ~/.claude/skills
# Validate skill structure
scripts/quick_validate.py ~/.claude/skills/my-skill
# Package for distribution
scripts/package_skill.py ~/.claude/skills/my-skill
skill-name/
├── SKILL.md # Main reference (required)
├── scripts/ # Executable code (optional)
├── references/ # Documentation loaded as needed (optional)
└── assets/ # Templates, images, fonts (optional)
Only name and description fields. Max 1024 chars total.
---
name: hyphen-case-name
description: Use when [specific triggering conditions]. Start with "Use when..."
---
CRITICAL: Description = when to use, NOT what skill does. Testing revealed that workflow summaries in descriptions cause agents to skip reading the full skill.
# ❌ BAD: Summarizes workflow
description: Use when executing plans - dispatches subagent with code review between tasks
# ✅ GOOD: Just triggers
description: Use when executing implementation plans with independent tasks
# Skill Name
## Overview
Core principle in 1-2 sentences.
## When to Use
Symptoms and use cases (bullets). When NOT to use.
## Core Pattern
Before/after or key workflow.
## Quick Reference
Table or bullets for scanning.
## Common Mistakes
What goes wrong + fixes.
Ask: "What functionality should this skill support?" "Can you give usage examples?"
Run pressure scenario WITHOUT skill. Document:
Address those specific rationalizations. Don't add hypothetical content.
Run scenarios WITH skill. Agent should comply.
New rationalization found? Add explicit counter. Re-test until bulletproof.
See references/tdd-testing.md for full testing methodology.
Target word counts:
Techniques:
--help in scriptsFor skills with variants (frameworks, providers), keep core in SKILL.md, move variant details to references/:
cloud-deploy/
├── SKILL.md (workflow + selection)
└── references/
├── aws.md
├── gcp.md
└── azure.md
Deterministic code for fragile or repeated operations. May execute without loading into context.
Documentation loaded on-demand. For 100+ line files, include table of contents.
Templates, images, fonts used in output (not loaded into context).
Rich description: Include concrete triggers, symptoms, situations. Write in third person.
Keywords: Error messages, symptoms, synonyms, tool names.
Naming: Verb-first, hyphen-case: creating-skills not skill-creation.
| Anti-Pattern | Why Bad | |--------------|---------| | Narrative example ("In session 2025-10-03...") | Too specific, not reusable | | Multi-language examples | Mediocre quality, maintenance burden | | Code in flowcharts | Can't copy-paste | | Generic labels (step1, helper2) | Labels need semantic meaning |
Use ONLY for:
Never for: Reference material, code examples, linear instructions.
NO SKILL WITHOUT A FAILING TEST FIRST
This applies to NEW skills AND EDITS. Write skill before testing? Delete it. Start over.
RED Phase:
GREEN Phase:
REFACTOR Phase:
Quality:
Deploy:
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer