Skills — Packaging Expertise as .md Files

Introduction

A slash command is a saved prompt. A skill is something more: a multi-step expert workflow with a verification gate that says when it's actually done.

The distinction matters because Claude Code's agentic workflows often require more than a single prompt. Auditing a codebase requires querying context, dispatching agents, collecting results, and writing a report. Shipping a feature requires building, testing, reviewing, and creating a PR. These are processes, not prompts — and skills are how you encode them.

The On-Disk Contract

On disk, a skill is a directory, not a flat file: ~/.claude/skills/<skill-name>/SKILL.md. The SKILL.md opens with YAML frontmatter — a name and a description — and the description is what Claude Code pre-loads for discovery: it's the trigger surface that decides when the skill applies. Supporting files (scripts, templates, reference docs) can live alongside SKILL.md in the same directory and load only when the skill runs.

~/.claude/skills/
  context-budget/
    SKILL.md        ← frontmatter (name, description) + the workflow body
  audit-swarm/
    SKILL.md
    templates/      ← optional supporting files

The Five-Section Structure

The five-section body below is Knox's house convention, layered on top of that contract. Every skill in Knox's ~/.claude/skills/ library follows it:

TRIGGERS are the phrases that invoke the skill. They include the slash form (/audit-swarm) and natural language variants ("audit the codebase," "weekly audit"). The more specific the trigger phrases, the less often the skill fires incorrectly.

WHEN TO USE is the decision contract. It's not just "what does this skill do" — it's "when is this the right tool." Knox's /ship skill includes WHEN TO USE: when you have a feature complete and need the full build → lint → test → PR pipeline. NOT for quick fixes. That distinction prevents /ship from firing on small one-liner corrections.

STEPS are the execution plan, numbered and concrete. Every step references real tools, real file paths, or real commands — never abstract descriptions. "Query Semantic memory layer for project context" is a weak step. memory_query("{project}") is a step Claude can execute.

ALLOWED TOOLS is the minimum tool set. It's visible to reviewers before they approve any elevated permissions the skill requests. It also constrains the skill — a documentation skill with Read and Write but no Bash cannot accidentally run destructive commands.

VERIFICATION GATE is what separates skills from prompts. It defines done. A skill that returns before the gate passes has not completed — it has failed prematurely.

How Progressive Disclosure Works

Skill bodies are not pre-loaded into the context window. This is the mechanism that makes 60+ skills possible without context pressure:

Only each skill's frontmatter metadata — the name and description, which carries the trigger phrases — is pre-loaded for skill discovery. When a trigger matches, Claude reads the WHEN TO USE section to decide if this is actually the right skill. Only then does the full skill body load. The bodies of the 59 skills you didn't invoke stay out of context entirely; each costs only its small metadata stub.

This is why trigger quality matters so much. Vague triggers cause false fires, which waste tokens loading the wrong skill. Precise triggers — "audit swarm," "ship feature," "morning brief" — fire reliably and rarely misfire.

Building a Real Skill

Knox's /context-budget skill is a good example of the pattern at production scale:

<!-- ~/.claude/skills/context-budget/SKILL.md -->
---
name: context-budget
description: Audit context window consumption across CLAUDE.md, MCP servers, and skills. Triggers - context-budget, context usage, token budget, why is it slow, context audit.
---

## TRIGGERS
context-budget, /context-budget, context usage, token budget, why is it slow, context audit

## WHEN TO USE
When Knox wants to understand how his context window is being consumed.
NOT for general performance debugging.

## STEPS
1. Read ~/.claude/settings.json and ~/.claude/CLAUDE.md
2. Count lines in all active CLAUDE.md files (global + project)
3. List active MCP servers from settings
4. Estimate token overhead per component (CLAUDE.md: ~4 tokens/line, MCP: ~200 tokens each)
5. Identify bloat: CLAUDE.md >300 lines, >10 MCPs, MEMORY.md truncation
6. Report: token budget table with available-for-work calculation

## ALLOWED TOOLS
Read, Bash(wc -l:*), Bash(cat:*)

## VERIFICATION GATE
Budget table produced. Available-for-work tokens calculated. 
At least one optimization recommendation surfaced.

The whole skill is readable in 30 seconds. Someone auditing Knox's settings can see exactly what this skill does, when it fires, and what permissions it needs. The verification gate prevents the skill from returning a "here's what I found" without surfacing an actionable recommendation.

Skills vs. Commands — When to Use Which

A command is the right choice when:

• The workflow is a single prompt, not a sequence of steps
• There's no meaningful done condition beyond "Claude responded"
• You want to share it with the team via the project repo

A skill is the right choice when:

• The workflow requires multiple tool calls in sequence
• There's a specific outcome that defines success (the verification gate)
• The workflow encodes enough domain knowledge to be worth packaging
• You want the workflow to run autonomously without prompting on each step

Knox's /pr-description is a command. Knox's /ship is a skill. The difference is the complexity of the process and the existence of a verifiable done condition.

What's Next

The next lesson covers the TDD approach to skill authoring — why starting with the failure scenario produces dramatically better skills than starting with the happy path.