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.

1. 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.

1. 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.

1. 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?"

1. Progressive disclosure — SKILL.md is the overview; reference files load on-demand.

Keep SKILL.md body under 500 lines.

1. Match freedom to fragility — text instructions for flexible tasks, exact scripts

for fragile operations, specialized agents for judgement-heavy tasks.

1. Default assumption — Claude is already very smart. Skip explanations of basic

concepts, library purposes, or general programming knowledge.

1. 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

| Content Type | Location | Why | |---|---|---| | Decision workflow | SKILL.md | Always loaded — guides what to do | | Trigger conditions | SKILL.md | Must be visible for skill activation | | Quick-reference commands | SKILL.md | Frequently needed during use | | Agent orchestration pattern | SKILL.md | Defines how agents coordinate | | Agent definitions | .claude/agents/ | Reusable across skills, standard location | | Lookup tables, field refs | references/ | Consulted occasionally, not always | | Code examples, case studies | references/ | Large blocks that dilute SKILL.md | | Executable procedures | scripts/ | Predictable, testable, reusable |

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:

````markdown

Quick Check

./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

| Signal | Agent Approach | Teams? | |--------|---------------|--------| | Task has 2+ independent subtasks | Parallel sub-agents for each | No | | Task requires web search, content reading, or AI judgement | Dedicated agent per domain | No | | Task processes N items of the same type | Fan-out: one agent per item (or per batch) | No | | Task has sequential phases with parallel work within | Orchestrator coordinates phase gates | Maybe | | Task is a single deterministic check | No agent — use a script instead | No | | Multi-phase workflow with inter-agent feedback | Named teammates via TeamCreate | Yes |

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

| Signal | Use Teams | Use Sub-Agents | |--------|-----------|----------------| | Multi-phase workflow with feedback loops | ✓ | | | Independent parallel tasks (fan-out) | | ✓ | | Teammates need each other's findings | ✓ | | | One-shot parallel analysis | | ✓ | | Iterative creative workflow (design, video) | ✓ | | | Quick research/validation | | ✓ |

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/.md:

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

You are a ****. Your mission is to .

## 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

| Signal | Required? | |--------|-----------| | 3+ sequential phases | Yes — users need visibility | | Multiple workflows/subcommands | Yes — each workflow gets its own manifest | | Single-phase script | No — overkill | | Pure decision guidance (no execution) | No — nothing to track |

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](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

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: abhattacherjee
• Source: abhattacherjee/claude-code-skills
• License: MIT

Install and usage instructions live in the source repository linked above.