---
name: authoring-skills
description: Guides the creation of effective AI Agent Skills. Use when creating new skills, writing skills, editing skills, improving existing skills, reviewing skill quality, or verifying skills work before deployment. Covers the full workflow from understanding requirements through packaging, including scripts for initialization and validation. Also covers TDD-based testing of skills with subagents, Claude Search Optimization (CSO), and bulletproofing discipline-enforcing skills against rationalization.
enabled: false
source: github:JuanJoseGonGi/skills
imported-from: github:JuanJoseGonGi/skills
---

# Agent Skills Authoring Guide

Complete guide for creating, testing, and packaging AI Agent Skills. Covers structure, naming, writing, TDD-based verification, and deployment.

## Core Principles

### 1. Concise is Key

The context window is a shared resource. Challenge each piece of information:
- "Does the agent really need this explanation?"
- "Does this paragraph justify its token cost?"

**Default assumption**: The agent is already very smart. Only add context it doesn't already have. Prefer concise examples over verbose explanations.

### 2. Progressive Disclosure

Skills use a three-level loading system:

1. **Metadata** (name + description) - Always in context (~100 words)
2. **SKILL.md body** - When skill triggers (< 500 lines)
3. **Bundled resources** - As needed (unlimited, scripts can execute without reading)

Keep `SKILL.md` lean. Split content into `references/` when approaching limits. Always clearly reference external files so the agent knows they exist.

### 3. Appropriate Degrees of Freedom

Match specificity to task fragility:

| Freedom | Use When | Example |
|---------|----------|---------|
| **High** (text instructions) | Multiple approaches valid | Code review guidelines |
| **Medium** (pseudocode) | Preferred pattern exists | Report templates |
| **Low** (specific scripts) | Operations are fragile | Database migrations |

### 4. Skills are TDD for Documentation

**Creating skills IS Test-Driven Development applied to process documentation.** Write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).

**Core rule:** If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.

## Skill Anatomy

```
skill-name/
├── SKILL.md              # Required: frontmatter + instructions
├── scripts/              # Optional: executable code
├── references/           # Optional: detailed documentation
└── assets/               # Optional: templates, images, files for output
```

### YAML Frontmatter

```yaml
---
name: skill-name        # lowercase, hyphens, max 64 chars, must match directory
description: What it does. Use when [triggers].  # max 1024 chars, third person
---
```

**Description must include**: what the skill does (capability) AND when to use it (trigger conditions).

**Critical:** Description = When to Use, NOT What the Skill Does. Never summarize the skill's workflow in the description — testing shows Claude may follow the description shortcut instead of reading the full skill body.

```yaml
# BAD: Summarizes workflow - Claude may follow this instead of reading skill
description: Use when executing plans - dispatches subagent per task with code review

# GOOD: Just triggering conditions, no workflow summary
description: Use when executing implementation plans with independent tasks
```

See [NAMING.md](references/NAMING.md) for detailed naming conventions.

### Bundled Resources

| Directory | Purpose | When to Include |
|-----------|---------|-----------------|
| `scripts/` | Executable code (Python/Bash) | Same code rewritten repeatedly; deterministic reliability needed |
| `references/` | Documentation loaded into context | Detailed info only needed for specific use cases |
| `assets/` | Files used in output (not loaded) | Templates, images, boilerplate for final output |

**Important**: Don't create extraneous files (README.md, CHANGELOG.md, etc.). Skills contain only what the agent needs.

See [STRUCTURE.md](references/STRUCTURE.md) for organization patterns.

## When to Create a Skill

**Create when:**
- Technique wasn't intuitively obvious
- You'd reference this again across projects
- Pattern applies broadly (not project-specific)
- Others would benefit

**Don't create for:**
- One-off solutions
- Standard practices well-documented elsewhere
- Project-specific conventions (put in CLAUDE.md)
- Mechanical constraints enforceable with regex/validation

## Skill Types

| Type | Description | Examples |
|------|-------------|---------|
| **Technique** | Concrete method with steps | condition-based-waiting, root-cause-tracing |
| **Pattern** | Way of thinking about problems | flatten-with-flags, test-invariants |
| **Reference** | API docs, syntax guides | API documentation, command references |

## Skill Creation Workflow

### Step 1: Understand with Concrete Examples

Ask clarifying questions to understand how the skill will be used:
- "What functionality should this skill support?"
- "Can you give examples of how it would be used?"
- "What would a user say that should trigger this skill?"

### Step 2: Plan Reusable Contents

For each example, analyze:
1. How would you execute this from scratch?
2. What scripts/references/assets would help when doing this repeatedly?

### Step 3: Initialize the Skill

```bash
python scripts/init_skill.py <skill-name> --path <output-directory>
```

### Step 4: RED Phase — Baseline Testing

**Before writing the skill**, run pressure scenarios WITHOUT it:

1. Create pressure scenarios (3+ combined pressures for discipline skills)
2. Run scenarios WITHOUT skill — document baseline behavior verbatim
3. Identify patterns in rationalizations/failures

This is "write the failing test first." You MUST see what agents naturally do before writing the skill.

For technique/reference skills, test retrieval and application scenarios instead.

See [TESTING.md](references/TESTING.md) for complete testing methodology.

### Step 5: GREEN Phase — Write the Skill

Start with bundled resources (scripts, references, assets), then update SKILL.md.

**For SKILL.md:**
- Write for another Claude instance to use
- Include non-obvious procedural knowledge
- Address specific baseline failures identified in RED phase
- One excellent code example beats many mediocre ones
- Reference design patterns: [WORKFLOWS.md](references/WORKFLOWS.md), [OUTPUT-PATTERNS.md](references/OUTPUT-PATTERNS.md)

**For scripts**: Test by actually running them.

Run same scenarios WITH skill. Agent should now comply.

### Step 6: REFACTOR Phase — Close Loopholes

Agent found new rationalization? Add explicit counter. Re-test until bulletproof.

For each new rationalization:
1. Add explicit negation in rules
2. Add entry in rationalization table
3. Add to red flags list
4. Update description with violation symptoms

### Step 7: Package and Deploy

```bash
python scripts/quick_validate.py <skill-directory>
python scripts/package_skill.py <path/to/skill-folder> [output-directory]
```

### Step 8: Iterate

1. Use the skill on real tasks
2. Notice struggles or inefficiencies
3. Update SKILL.md or bundled resources
4. Test again

## SKILL.md Structure Template

```markdown
---
name: skill-name
description: Use when [specific triggering conditions and symptoms]
---

# Skill Name

## Overview
Core principle in 1-2 sentences.

## When to Use
Bullet list with symptoms and use cases. When NOT to use.

## Core Pattern
Before/after code comparison (for techniques/patterns).

## Quick Reference
Table or bullets for scanning common operations.

## Implementation
Inline code for simple patterns. Link to file for heavy reference.

## Common Mistakes
What goes wrong + fixes.
```

## Claude Search Optimization (CSO)

### Description Field Best Practices

- Start with "Use when..." — focus on triggering conditions
- Write in third person (injected into system prompt)
- Include concrete triggers, symptoms, situations
- Describe the *problem* not *language-specific symptoms*
- **NEVER summarize the skill's process or workflow**
- Keep under 500 characters if possible, max 1024

### Keyword Coverage

Use words Claude would search for:
- Error messages: "Hook timed out", "ENOTEMPTY", "race condition"
- Symptoms: "flaky", "hanging", "zombie", "pollution"
- Synonyms: "timeout/hang/freeze", "cleanup/teardown/afterEach"
- Tools: Actual commands, library names, file types

### Naming

Use gerund form (verb + -ing): `creating-skills` not `skill-creation`. Active, descriptive names.

See [NAMING.md](references/NAMING.md) for full conventions.

### Cross-Referencing Other Skills

Use skill name only, with explicit requirement markers:
- **Good**: `**REQUIRED:** Use superpowers:test-driven-development`
- **Bad**: `@skills/testing/test-driven-development/SKILL.md` (force-loads, burns context)

### Token Efficiency

Target word counts: getting-started workflows <150 words, frequently-loaded skills <200 words, other skills <500 words.

Techniques: move details to `--help`, use cross-references, compress examples, eliminate redundancy.

## Bulletproofing Discipline Skills

Skills that enforce discipline need to resist rationalization.

### Close Every Loophole Explicitly

Don't just state the rule — forbid specific workarounds:

```markdown
Write code before test? Delete it. Start over.

**No exceptions:**
- Don't keep it as "reference"
- Don't "adapt" it while writing tests
- Delete means delete
```

### Build Rationalization Table

Capture rationalizations from baseline testing. Every excuse agents make goes in the table:

```markdown
| Excuse | Reality |
|--------|---------|
| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
| "Tests after achieve same goals" | Tests-after confirms; tests-first specifies. |
```

### Create Red Flags List

```markdown
## Red Flags - STOP and Start Over
- Code before test
- "I already manually tested it"
- "This is different because..."
```

### Persuasion Principles

Understanding why compliance techniques work helps design more effective skills. Authority, commitment, and scarcity are most effective for discipline-enforcing skills. See [PERSUASION.md](references/PERSUASION.md) for research foundation.

## Flowcharts

**Use ONLY for:** non-obvious decision points, process loops, "when to use A vs B" decisions.

**Never for:** reference material, code examples, linear instructions.

See [graphviz-conventions.dot](references/graphviz-conventions.dot) for style rules. Use `scripts/render-graphs.js` to render diagrams to SVG.

## Testing by Skill Type

| Skill Type | Test With | Success Criteria |
|------------|-----------|-----------------|
| **Discipline** (TDD, verification) | Pressure scenarios, multiple combined pressures | Agent follows rule under maximum pressure |
| **Technique** (how-to guides) | Application scenarios, edge cases, missing info | Agent successfully applies technique |
| **Pattern** (mental models) | Recognition, application, counter-examples | Agent correctly identifies when/how to apply |
| **Reference** (docs/APIs) | Retrieval, application, gap testing | Agent finds and correctly applies info |

See [TESTING.md](references/TESTING.md) for complete testing methodology including pressure types, scenario writing, meta-testing, and worked examples.

## Anti-Patterns

- **Narrative storytelling**: "In session X, we found..." — too specific, not reusable
- **Multi-language dilution**: example-js, example-py, example-go — mediocre quality, maintenance burden
- **Vague descriptions**: "Helps with documents" — not discoverable
- **Deeply nested references**: SKILL.md → advanced.md → details.md — keep one level deep
- **Time-sensitive info**: "Before August 2025, use old API" — use "old patterns" sections instead
- **Too many options**: "Use pypdf, or pdfplumber, or PyMuPDF..." — provide a default with escape hatch

## Validation

Before sharing, verify:

```bash
python scripts/quick_validate.py <skill-directory>
```

Or use the full checklist: [CHECKLIST.md](references/CHECKLIST.md)

## Skill Creation Checklist

**RED Phase:**
- [ ] Created pressure scenarios (3+ combined pressures for discipline skills)
- [ ] Ran scenarios WITHOUT skill — documented baseline behavior verbatim
- [ ] Identified patterns in rationalizations/failures

**GREEN Phase:**
- [ ] Name uses only letters, numbers, hyphens (matches directory)
- [ ] YAML frontmatter with name and description (max 1024 chars)
- [ ] Description starts with "Use when..." — no workflow summary
- [ ] Description written in third person
- [ ] Keywords throughout for search (errors, symptoms, tools)
- [ ] Clear overview with core principle
- [ ] Addresses specific baseline failures
- [ ] One excellent example (not multi-language)
- [ ] Ran scenarios WITH skill — agents comply

**REFACTOR Phase:**
- [ ] Identified NEW rationalizations from testing
- [ ] Added explicit counters (if discipline skill)
- [ ] Built rationalization table from all test iterations
- [ ] Created red flags list
- [ ] Re-tested until bulletproof

**Quality:**
- [ ] SKILL.md body under 500 lines
- [ ] Small flowchart only if decision non-obvious
- [ ] Consistent terminology throughout
- [ ] No time-sensitive information
- [ ] File references one level deep
- [ ] Supporting files only for tools or heavy reference

**Deployment:**
- [ ] Pass `quick_validate.py` check
- [ ] Package with `package_skill.py`
- [ ] Tested with real usage scenarios

## Reference Documentation

- **[NAMING.md](references/NAMING.md)**: Naming conventions and description guidelines
- **[STRUCTURE.md](references/STRUCTURE.md)**: File organization and progressive disclosure
- **[WORKFLOWS.md](references/WORKFLOWS.md)**: Workflow patterns and iteration
- **[OUTPUT-PATTERNS.md](references/OUTPUT-PATTERNS.md)**: Template and example patterns for output
- **[CHECKLIST.md](references/CHECKLIST.md)**: Quality checklist before sharing
- **[TESTING.md](references/TESTING.md)**: TDD-based skill testing with subagents, pressure scenarios, and meta-testing
- **[PERSUASION.md](references/PERSUASION.md)**: Persuasion principles for designing compliance-resistant skills
- **[ANTHROPIC-BEST-PRACTICES.md](references/ANTHROPIC-BEST-PRACTICES.md)**: Anthropic's official skill authoring guidance
- **[graphviz-conventions.dot](references/graphviz-conventions.dot)**: Graphviz style rules for flowcharts
- **[examples/](references/examples/)**: Worked examples of skill testing campaigns
