Skill Authoring

Skill Authoring

Core Principles

1. Decompose into agents — break complex skills into an orchestrator + specialized sub-agents. Each sub-agent has a single focused responsibility. The orchestrator delegates, coordinates, and reports — it never does the work itself.
2. Parallelize aggressively — launch independent sub-agents in a SINGLE Task tool message. If 3 catalogs need processing, launch 3 agents simultaneously, not sequentially. Time savings compound: 3 parallel agents = ~1x latency, not 3x.
3. Script-first for determinism — if the skill's value can be captured in a deterministic script, write the script FIRST, then wrap SKILL.md around it. Scripts are testable, runnable outside Claude, and keep SKILL.md lean. Agents handle judgement; scripts handle procedure.
4. Concise is key — the context window is a shared resource. Only add what Claude doesn't already know. Challenge each paragraph: "Does this justify its token cost?"
5. Progressive disclosure — SKILL.md is the overview; reference files load on-demand. Keep SKILL.md body under 500 lines.
6. Match freedom to fragility — text instructions for flexible tasks, exact scripts for fragile operations, specialized agents for judgement-heavy tasks.
7. Default assumption — Claude is already very smart. Skip explanations of basic concepts, library purposes, or general programming knowledge.
8. Track progress for long workflows — skills with 3+ sequential phases must include a task manifest script. Use TaskCreate/TaskUpdate to give real-time progress visibility. Users should never wonder "what phase is it on?" during a 5-minute workflow.

Frontmatter Rules

Supported fields: name, description, metadata, compatibility, license.

---
name: kebab-case-name          # ≤64 chars, lowercase + hyphens only
description: "Third-person description. Use when: (1) ..., (2) ..."  # ≤1024 chars, single-line quoted
metadata:
  version: 1.0.0               # semver: patch=typos, minor=new content, major=breaking
---

Do NOT include: author, date, tags, allowed-tools, category, or top-level version (use metadata.version instead). Use double-quoted single-line strings for description — block scalars (description: |) cause VS Code linter errors.

Description rules:

• Write in third person ("Processes files..." not "I help you..." or "You can...")
• Include both what it does AND when to use it
• Add numbered trigger conditions: Use when: (1) ..., (2) ..., (3) ...
• Include specific symptoms, error messages, framework names
• Claude uses this to choose from 100+ skills — be specific enough to win selection

Directory Layout

your-skill/
├── SKILL.md              # Required — decision workflow, when-to-use, key rules
├── scripts/              # Optional — executable automation
│   ├── extract.sh        # Pre-processing: deterministic data extraction
│   └── apply-fixes.sh    # Post-processing: apply agent results
└── references/           # Optional — lookup material loaded on-demand
    ├── field-tables.md   # Tables, matrices, lookup data
    └── examples.md       # Code examples, past case studies

# Agent definitions live alongside other agents (not inside the skill):
.claude/agents/
├── your-orchestrator.md       # Pure orchestrator — delegates everything
├── your-sub-agent-a.md        # Focused specialist (NOT user-invocable)
└── your-sub-agent-b.md        # Focused specialist (NOT user-invocable)

What Goes Where

Reference Rules

• One level deep from SKILL.md — no references linking to other references
• Descriptive filenames — api-field-reference.md not ref1.md
• Files > 100 lines should have a table of contents at the top

Script Extraction

Default: extract a script. Only skip if the skill is purely decision guidance with no deterministic steps.

Extract into scripts/ when ANY apply:

• The skill checks, validates, or detects something (staleness, sync, coverage)
• The code handles error conditions (missing deps, wrong directory, invalid args)
• The same code block appears in multiple skills
• The script composes with other scripts or CI/hooks
• Users may run it standalone outside the skill context

Script requirements:

• Always support --help / -h with usage examples
• Validate inputs before operating (check files exist, directories writable)
• Use meaningful exit codes (0 = success, 1 = error, 2 = usage)
• Include a --fix mode where applicable (detect + auto-remediate)
• Make executable: chmod +x scripts/*.sh
• Use #!/usr/bin/env bash shebang (portable)
• Choose set flags by script purpose (see Pitfall below)

Pitfall: set -e interacts badly with bash arithmetic and pipes. Common triggers: (1) find | sort | head -N — head closes the pipe causing SIGPIPE (exit 141) with pipefail, (2) grep -c returns exit 1 when count is 0, (3) echo "$var" | while read in subshells, (4) ((var++)) when var=0 — ((0)) evaluates to false, causing set -e to terminate the script. Fix: use VAR=$((VAR + 1)) instead of ((VAR++)). Use set -euo pipefail for validation scripts; use set -eu (without pipefail) for context-gathering scripts.

After writing the script, slim SKILL.md:

• Replace procedural prose with a Quick Check section pointing to the script
• Keep SKILL.md focused on when/why/context, not how (the script handles that)
• Move lookup tables (field mappings, inventories) into the script or references/

Reference from SKILL.md:

## Quick Check
```bash
./scripts/validate.sh /tmp/data.json           # Report only
./scripts/validate.sh /tmp/data.json --fix     # Auto-remediate
./scripts/validate.sh --help                   # Usage
```

Agent & Orchestration Design

Default: decompose into agents. Only skip if the skill is a single-step check or pure decision guidance. Every skill with 2+ independent subtasks should use parallel agents.

When to Use Agents

Orchestrator Pattern

The pure orchestrator pattern is the gold standard for complex skills:

Orchestrator (coordinates, decides, reports)
├── Sub-agent A (focused task 1) ─── launched in parallel ──┐
├── Sub-agent B (focused task 2) ─── launched in parallel ──┤ SINGLE message
├── Sub-agent C (focused task 3) ─── launched in parallel ──┘
└── Script (deterministic pre/post-processing)

Orchestrator rules:

• Pure delegation — the orchestrator NEVER does the work itself. It launches agents, collects results, makes phase-gate decisions, and generates the final report.
• Parallel by default — launch all independent agents in a SINGLE Task tool message. Only sequence agents when one depends on another's output.
• Progress reporting — output status updates between tool calls so the user is never left wondering what's happening.

MCP Tool Constraint (CRITICAL for skills using MCP servers)

Agent Teams teammates and sub-agents CANNOT call MCP tools. MCP server connections and tool permissions are session-scoped — they don't propagate to tmux panes or child agent sessions. When a teammate calls an MCP tool, it shows "Permission request sent to team leader" and deadlocks — the lead has no mechanism to approve.

"Lead Reads, Agents Analyze" pattern:

1. The orchestrator/lead reads ALL MCP content in Phase 1 (it has the permissions)
2. File contents are passed as TEXT in agent prompts — agents analyze text, not MCP resources
3. Agents must NOT call any mcp__* or ReadMcpResourceTool tools

This applies to ALL MCP servers (Figma, Sentry, Railway, etc.) and both Agent Teams teammates and non-team sub-agents (Agent tool calls). Always design skills that use MCP data with this constraint in mind.

Sub-Agent Design

Each sub-agent should be maximally specialized:

• Single responsibility — one agent per focused task (e.g., "validate curated catalog URLs" not "validate all URLs across all catalogs")
• Self-contained prompt — include all context the agent needs in its Task prompt. Don't rely on the agent inferring context from the conversation.
• Structured output — define the exact JSON/report format the agent should return. The orchestrator parses this to make decisions.
• Appropriate model — use haiku for fast/simple tasks (data extraction, formatting), sonnet for moderate judgement (code review, validation), opus only when deep reasoning is essential.

Parallelization Patterns

Fan-out by item — one agent per catalog, per PR, per test folder:

# 3 catalogs → 3 parallel agents (SINGLE message)
Task(agent=general-purpose, prompt="Validate curated catalog URLs...")
Task(agent=general-purpose, prompt="Validate google-places catalog URLs...")
Task(agent=general-purpose, prompt="Validate experiences catalog URLs...")

Fan-out by concern — one agent per review dimension:

# 3 review concerns → 3 parallel agents (SINGLE message)
Task(agent=code-reviewer, prompt="Review for bugs/correctness...")
Task(agent=code-reviewer, prompt="Review for simplicity/DRY...")
Task(agent=code-reviewer, prompt="Review for project conventions...")

Phased parallelism — sequential phases, parallel within each:

Phase 1: Script extracts data (deterministic)
Phase 2: 3 parallel agents process data (judgement)
Phase 3: Script applies fixes (deterministic)
Phase 4: 1 agent validates results (judgement)

Agent + Script Composition

The most powerful pattern combines both:

• Scripts handle deterministic pre-processing (extraction, transformation, validation)
• Agents handle judgement-heavy work (content verification, research, code review)
• Scripts handle deterministic post-processing (applying fixes, generating reports)

Example flow: extract-urls.sh → 3 parallel verification agents → apply-fixes.sh

Agent Teams Orchestration

Use Agent Teams when teammates need to communicate with each other across phases — not just report back to an orchestrator.

When to Use Teams vs Sub-Agents

Team Orchestration Pattern

TeamCreate("my-workflow")
├── TaskCreate tasks for each work item
├── Spawn teammates (Agent tool with team_name + name)
│   ├── Teammate A claims + works tasks
│   ├── Teammate B claims + works tasks
│   └── Teammates communicate via SendMessage
├── Lead monitors progress via TaskList
├── Lead synthesizes results
└── TeamDelete (cleanup)

Conditional Team Usage

Skills should support both modes — teams when available, sub-agents as fallback:

## Orchestration Mode

Check `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`:
- **If enabled**: Use TeamCreate for persistent multi-phase coordination
- **If disabled** (default): Use parallel Agent tool calls (existing pattern)

Both modes produce identical results. Teams add inter-agent communication.

Complex Skill Template (Teams Variant)

When using teams instead of anonymous sub-agents:

## Full Workflow (Team Orchestration)

### Step 1: Create Team
TeamCreate("my-workflow") → spawns shared task list.

### Step 2: Define Tasks
TaskCreate for each work item (extraction, validation, enrichment, etc.)

### Step 3: Spawn Named Teammates
Launch via Agent tool with `team_name` + `name` parameters.
Each teammate claims tasks from the shared list.

### Step 4: Monitor & Synthesize
Lead polls TaskList, teammates SendMessage findings to each other.
Lead collects completed results and generates final report.

### Step 5: Cleanup
TeamDelete("my-workflow")

Defining Agent Files

For skills that spawn agents, create .claude/agents/<agent-name>.md:

---
name: agent-name
description: "Single-purpose description. NOT user-invocable — spawned by <orchestrator>."
model: sonnet  # or haiku for simple tasks
---

You are a **<Role Name>**. Your mission is to <focused task>.

## Input (provided by orchestrator)
[What the orchestrator passes in the Task prompt]

## Output Format
[Exact JSON/report structure to return]

## Workflow
[Step-by-step procedure]

Agent registration: If the skill uses an orchestrator, include a Sub-Agent Registry table in the orchestrator's agent file listing all sub-agents, their concurrency model (parallel/sequential), purpose, and model tier.

Progress Tracking for Long-Running Workflows

Skills with 3+ sequential phases or workflows lasting >2 minutes should include a task manifest — a script that defines the exact TaskCreate checklist for each workflow the skill supports.

When to Add Task Tracking

Task Manifest Script Pattern

Every skill with tracking should include scripts/task-manifest.sh — a bash case statement that emits a JSON array of tasks per workflow. Each task has subject, activeForm, and description fields matching TaskCreate parameters.

See references/task-tracking-pattern.md for the full script template with examples.

Key rules:

• Each workflow is a case branch emitting a JSON array
• --list returns machine-readable workflow names; --help shows usage
• SKILL.md includes a "Progress Tracking (MANDATORY)" section with the task table
• Mark tasks in_progress before starting, completed after, deleted on abort

Generating a Task Manifest for a New Skill

~/.claude/skills/skill-authoring/scripts/generate-task-manifest.sh \
  --skill-dir /path/to/my-skill \
  --workflows "full-audit:5,quick-check:2"

Creating a New Skill — Workflow

1. Check existing skills — search project + user-level directories
2. Decide: create new vs update existing (see decision table below)
3. Evaluate decomposition — can this be split into parallel agents? (see below)
4. Evaluate script-first — can deterministic parts be captured in scripts? (see below)
5. Evaluate progress tracking — does the skill have 3+ phases? (see below)
6. Write agents (if applicable) — orchestrator + sub-agent definitions
7. Write scripts (if applicable) — with --help, error handling, exit codes
8. Write task manifest (if applicable) — scripts/task-manifest.sh for each workflow
9. Write SKILL.md — frontmatter + body; reference agents, scripts, and task manifest
10. Extract references/ — if lookup material exceeds ~30 lines
11. Validate — run the quality checklist
12. Dry-run test — run scripts against real project data (see below)
13. Version — start at 1.0.0

Decomposition Evaluation (Step 3)

Ask: "Can this task be split into independent subtasks that run in parallel?"

Script-First Evaluation (Step 4)

Ask: "Can the skill's core action be expressed as a deterministic check or procedure?"

Why script-first wins: A 140-line script replaces ~60 lines of prose in SKILL.md while being testable, runnable standalone, and composable with CI/hooks. The SKILL.md drops from "explain everything" to "explain when/why + point to script".

Progress Tracking Evaluation (Step 5)

Ask: "Does this skill have 3+ sequential phases or take >2 minutes?"

Dry-Run Testing (Step 12)

Every skill with scripts MUST be dry-run tested against real project data before release. Scripts that look correct often fail due to: regex format mismatches, grep pipe chains where head causes SIGPIPE, find including coverage/build artifacts, and classification heuristics that misfire on edge cases.

Procedure:

1. Run each script with human-readable output (no --json), scan for zero counts, unexpected items, misclassified entries, empty sections
2. Run with --json — verify field values match human-readable output
3. Test with 2-3 varied inputs (different formats, different project areas)
4. Fix and re-test — bugs cluster (one broken heuristic often means others are too)

Common catches: grep -rlq ... | head -1 always exits 0 on empty -q output; find without -not -path "*/coverage/*" includes test artifacts; regex assumes one heading format but project uses another (e.g., ### Sub-Task vs ### AC1:).

Create vs Update Decision

Skill Template

Simple Skill (script-only, no agents)

---
name: descriptive-kebab-name
description: "Third-person description. Use when: (1) ..., (2) ..., (3) .... Covers: topic1, topic2."
metadata:
  version: 1.0.0
---

# Skill Title

## Problem
[2-3 sentences max.]

## Quick Check
```bash
./scripts/check.sh              # Report only
./scripts/check.sh --fix        # Auto-remediate

Solution

[Decision guidance for non-scripted parts.]

See Also

[Cross-references to related skills.]

### Complex Skill (orchestrator + parallel agents + scripts + task tracking)

```markdown
---
name: descriptive-kebab-name
description: "Third-person description. Use when: (1) ..., (2) .... Covers: orchestration, parallel agents, topic."
metadata:
  version: 1.0.0
---

# Skill Title

## Problem
[2-3 sentences max.]

## Quick Check
```bash
./scripts/extract.sh --summary          # Pre-processing (deterministic)
./scripts/task-manifest.sh full-run     # Task checklist for full workflow

Progress Tracking (MANDATORY)

Create task checklist from scripts/task-manifest.sh full-run before starting. Mark in_progress → completed per phase. On abort, mark remaining deleted.

Full Workflow (Orchestration Pattern)

Step 1: Extract Data (Script)

MANIFEST=$(./scripts/extract.sh --json)

Step 2: Launch Parallel Agents

Launch N parallel general-purpose agents via the Task tool — one per . Each agent receives its slice of data and saves results to /tmp/<skill>-report-<domain>.json.

Step 3: Apply Fixes (Script)

./scripts/apply-fixes.sh --all --dry-run    # Preview
./scripts/apply-fixes.sh --all              # Apply

Step 4: Validate

npm run validate  # Or whatever validation command applies

Agent Definitions

• orchestrator-agent.md — pure orchestrator, delegates everything
• specialist-agent.md — focused sub-agent, NOT user-invocable

See Also

[Cross-references to related skills.]

## Quality Checklist

**Decomposition & agents:**
- [ ] Decomposition evaluated: can this be split into parallel sub-agents?
- [ ] If yes: orchestrator defined as pure delegator (never does the work itself)
- [ ] Independent agents launched in SINGLE Task tool message (not sequentially)
- [ ] Each sub-agent has single focused responsibility
- [ ] Sub-agents use appropriate model tier (haiku/sonnet/opus)
- [ ] Agent definitions include structured output format

**Scripts & determinism:**
- [ ] Script-first evaluated: can deterministic parts be captured in scripts?
- [ ] If yes: script written first, SKILL.md references it (not duplicates it)
- [ ] Scripts have `--help` and `--fix`/`--dry-run` support and are executable
- [ ] Scripts dry-run tested against real project data (2-3 varied inputs)

**Progress tracking:**
- [ ] Progress tracking evaluated: does the skill have 3+ sequential phases?
- [ ] If yes: `scripts/task-manifest.sh` created with one `case` per workflow
- [ ] Each workflow defines tasks with `subject`, `activeForm`, `description`
- [ ] SKILL.md includes "Progress Tracking (MANDATORY)" section with task table
- [ ] Task update rules documented (in_progress → completed, abort → deleted)

**Teams (optional):**
- [ ] Team mode evaluated: does this skill have multi-phase feedback loops?
- [ ] If yes: team pattern documented alongside sub-agent pattern
- [ ] Conditional check for `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` documented
- [ ] TeamDelete cleanup documented in workflow

**Structure & content:**
- [ ] SKILL.md body ≤ 500 lines
- [ ] Description ≤ 1024 chars, third person, with trigger conditions, double-quoted single-line
- [ ] Frontmatter has only `name`, `description`, `metadata`
- [ ] References are one level deep from SKILL.md
- [ ] All cross-reference links resolve to existing files

## Anti-Patterns

- **Sequential when parallel is possible** — if agents don't depend on each other's
  output, launch them in a SINGLE message. Sequential = N x latency for no reason.
- **Monolithic agent** — one agent doing 5 things. Split into 5 focused agents.
- **Orchestrator doing work** — the orchestrator should delegate, not fetch/validate/enrich.
- **Missing structured output** — agents returning prose instead of parseable JSON/reports
  forces the orchestrator to guess at results.
- **Verbose explanations** — Claude knows what PDFs are. Skip the intro paragraph.
- **Too many options** — provide a default with escape hatch, not 5 alternatives.
- **Deeply nested references** — SKILL.md → ref.md → detail.md causes partial reads.
- **Time-sensitive info** — "After August 2025, use X" becomes stale. Use "Current method" / "Legacy" sections.
- **Inconsistent terminology** — pick one term ("endpoint" not alternating "URL/route/path").
- **Non-standard frontmatter** — `author`, `date`, `tags` waste tokens and aren't used.
- **Incomplete CLI templates in agents** — when agents create GitHub artifacts (`gh issue
  create`, `gh pr create`), include ALL metadata flags (`--label`, `--assignee`,
  `--milestone`) explicitly in the template. Agents improvise missing fields with
  plausible-but-wrong values (e.g., `dependencies` label instead of project's `dependabot`
  label). Include a selection guide for dynamic fields like priority labels.
- **Silent long-running workflows** — skills with 3+ phases that don't use TaskCreate leave
  users staring at a spinner for minutes with no visibility. Always include a task manifest
  and update tasks between phases. If a sub-agent takes >30 seconds, the user should see
  which task is `in_progress`.
- **Untested scripts shipped as "done"** — scripts that pass code review but fail on real
  data. Always dry-run against the current project with varied inputs before declaring
  complete. Bugs cluster: if one heuristic is wrong, test the others too.
- **Using teams for one-shot parallel work** — teams add overhead (shared task list, message
  routing). For independent fan-out tasks, sub-agents are faster and cheaper.

## Optimizing Existing Skills

When a skill exceeds 500 lines, has poor structure, or runs slowly:

1. **Audit for parallelization** — identify independent subtasks that could be agents
2. **Decompose monolithic agents** — split "does everything" agents into focused specialists
3. **Extract scripts/** — move deterministic procedures out of agent prompts
4. **Extract references/** — move lookup tables and code examples
5. **Replace inline content** with links:
   `See **[references/your-file.md](references/your-file.md)** for the full lookup table.`
6. **Validate cross-references** — grep for `references/` and `scripts/` links, verify all exist
7. **Fix stale cross-references** — search for skill names that no longer exist
8. **Bump version** — minor for content reorganization, major for agent architecture changes

## See Also
- `claudeception` — when to extract knowledge into skills (the WHY/WHEN)
- Anthropic docs: [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
- GitHub: [skill-authoring](https://github.com/abhattacherjee/claude-code-skills/tree/main/skill-authoring) — install instructions, changelog, and releases