Skills Primer
What’s a skill?
Section titled “What’s a skill?”A skill is a YAML-frontmatter + markdown bundle that tells Claude Code how to execute a specific reusable behavior. Think of it as a recipe card: the frontmatter names the skill and declares which tools it needs; the markdown body explains the workflow, the file paths it touches, and worked examples. When a skill is invoked, Claude reads that file and follows it — no guessing, no improvising.
Every skill lives at ~/.claude/skills/<name>/SKILL.md. For example, ~/.claude/skills/dispo-blast/SKILL.md contains the full blast workflow for pushing a deal to four buyer channels. Skills are not agents (no persistent memory or identity) and not MCP servers (those expose tool surfaces from external systems). Skills are focused, callable behaviors.
Two ways skills get invoked
Section titled “Two ways skills get invoked”Explicit slash command. Henry types /dispo-blast or /discord. The Claude Code harness detects that a matching skill name was requested and calls the Skill tool, which loads the corresponding SKILL.md into context. Claude reads it and executes from there.
Keyword auto-trigger. CLAUDE.md contains a “Tool Trigger Conditions” table — about 80 entries mapping specific keywords, file events, and context signals to skill invocations. When Claude detects a match mid-conversation, it invokes the skill automatically, without Henry having to name it. For example, if Henry says “blast deal to buyers,” Claude matches that phrase to /dispo-blast and loads it before responding. This is why you’ll sometimes see Claude switch into a structured workflow mode without any explicit command.
Trigger priorities (P0–P3)
Section titled “Trigger priorities (P0–P3)”The trigger table uses four priority levels. These affect how quickly Claude should invoke the skill and how much oversight applies.
| Priority | Meaning | Examples |
|---|---|---|
| P0 | Critical execution, governance, or safety path — invoke immediately, never skip | /gsd:execute-phase, /security-review, /acquisitions-outreach |
| P1 | High-leverage workflows — invoke proactively when keyword appears | /dispo-blast, /claude-api, /loop, /openclaw:status |
| P2 | Domain-specific helpers — invoke on request or strong match | /docx, /pdf, /xlsx, /horse-racing, /model-usage |
| P3 | Niche customization — invoke only on direct match | /keybindings-help |
A representative slice of the trigger table
Section titled “A representative slice of the trigger table”| Skill | Priority | Trigger keyword or event | What it does |
|---|---|---|---|
/gsd:execute-phase | P0 | ”advance phase”, “resume work”, .gsd/STATE.md exists | Runs all steps in the current GSD plan phase — wave-based, atomic, blocks on unmet exit criteria |
/acquisitions-outreach | P0 | ”send initial CH outreach”, “trigger Stage 1 SMS” | First-touch SMS to contract holders — 5-gate compliance check before any send |
/acquisitions-followup | P0 | ”schedule follow-ups”, “handle inbound reply”, “re-engage stalled deals” | NO_REPLY/PRICE_DROP cadence + A-G inbound reply classification and response |
/security-review | P0 | ”webhook endpoint”, “WAF”, “credential”, FUNNEL-REGISTRY.md modified | Security audit on pending webhook or tunnel changes |
/hubspot-deal-ingest | P0 | ”push deal to HubSpot”, “create HS deal” | Source-agnostic deal ingestion — dedup, contact find-or-create, dual-pipeline write |
/claude-api | P1 | ”Anthropic SDK”, “prompt caching”, file imports anthropic | Build/debug/optimize Anthropic SDK apps with caching and tool-use patterns |
/dispo-blast | P1 | ”blast deal to buyers”, “weekly w4 broadcast”, “showing day blast” | 4-channel buyer broadcast — InvestorBase, CRMLS, PropStream, showing-day cohort |
/discord | P1 | ”discord”, “post to channel”, “#ops” | Post, react, search, or manage threads in Discord via the message tool |
/loop | P1 | ”check every 5 min”, “keep running”, “poll for status” | Recurring interval task runner — self-pacing or fixed interval |
/openclaw:status | P1 | ”system health”, “everything running”, “services ok” | Comprehensive health check across gateway, proxy, agents, and services |
/docx | P2 | ”word document”, “Word doc”, “letterhead” | Generate or process .docx files |
/pdf | P2 | ”PDF”, “extract text from”, “OCR” | Generate or extract from PDF files |
/xlsx | P2 | ”spreadsheet”, “excel file”, .xlsx/.csv extension | Generate or process spreadsheet files |
Three worked examples
Section titled “Three worked examples”Example 1 — dispo-blast triggered by keyword. Henry says “blast deal to buyers for the Compton property.” Claude detects the phrase “blast deal to buyers” in the trigger table (P1, openclaw category) and calls the Skill tool, loading ~/.claude/skills/dispo-blast/SKILL.md. The skill instructs Claude to run dispo-blast-engine.js with --dry-run first — showing estimated recipient counts, dedup hits, and cost — then to ask Henry for explicit authorization before any live blast. The skill also prevents bypassing the four pre-blast history checks (already-blasted, recent-engagement, saturation, suppression). Henry confirms, Claude dispatches a Sonnet subagent to execute, and the blast runs across all four channels.
Example 2 — discord invoked via slash command. Henry types /discord and asks to post a status update to #ops. Claude calls the Skill tool, loads ~/.claude/skills/discord/SKILL.md, and learns to use the message tool with channel: "discord". The skill specifies that rich messages should use Discord Components v2, not legacy embeds, and that markdown tables should be avoided. Claude formats the message accordingly and calls message with action: "send", to: "channel:<ops-channel-id>". The post is confirmed.
Example 3 — plan-eng-review fires automatically. Henry finishes describing a multi-phase architecture plan and Claude writes the plan file to ~/.claude/plans/. Immediately after writing it, the P0 trigger “event: plan file just written OR ExitPlanMode called” fires. Claude invokes /plan-eng-review without Henry asking. The review skill audits the plan for unresolved blockers, missing rollback steps, and governance gate compliance, then reports findings back before execution begins.
How skills compose with subagent dispatch
Section titled “How skills compose with subagent dispatch”A skill can either BE the complete work (like /discord, which is a short leaf action) or ORCHESTRATE further subagent dispatches (like /gsd:execute-phase or /dispo-blast). The orchestrating skills follow the model-routing rules baked into CLAUDE.md: Opus reads the skill and plans the work; Sonnet subagents (dispatched via the Agent tool) do the mechanical execution. Each Sonnet dispatch includes an 8-element prompt contract — goal, evidence, tool path, test requirements, acceptance criteria, rollback command, rule constraints, and output format.
This matters for understanding what you’re watching when a complex skill runs. You’ll see Claude break the work into chunks, dispatch multiple sub-tasks in sequence or parallel, then verify each result before marking it done. For the full dispatch flow, see How It Works.
Where to find them all
Section titled “Where to find them all”ls ~/.claude/skills/There are currently around 94 entries in that directory — roughly 54 have a valid SKILL.md with frontmatter and body. The rest are scaffolds or aliases. Each SKILL.md begins with YAML frontmatter (name:, description:, allowed-tools:) and continues with an architecture diagram, capabilities table, worked commands, failure modes, and cross-references. Open any one to see the pattern.
What skills are NOT
Section titled “What skills are NOT”Not agents. Agents (like Aurora, Acq, Dispo) have persistent identity, a SOUL.md that governs their behavior, a SQLite memory database, and long-running service processes. Skills have none of that — they’re stateless recipe cards Claude reads at invocation time.
Not MCP servers. MCP servers (like openclaw-tools, aurora-orchestrator, context7) expose external tool surfaces that Claude calls via function calls. Skills are purely documentation that shapes how Claude uses tools it already has access to.
Not Claude Code built-ins. Commands like /help, /clear, and /config are built into Claude Code itself. Skills live in ~/.claude/skills/ and are loaded on demand by the Skill tool.
Where to go next
Section titled “Where to go next”- How It Works — subagent dispatch, model routing, and the Opus/Sonnet/Haiku split
- Architecture Snapshot — full system map with ports, agents, and service boundaries