The Skills System

Tier 1 · Fundamentals 7 min read

As you work with Claude Code over time, you’ll find yourself writing the same kind of prompt repeatedly: “review the PR and post findings as inline comments,” “add authentication to this project,” “show me the morning briefing.” Skills are the answer to that pattern — named, reusable commands that the agent can invoke with a single phrase.

What a skill is

A skill is a Markdown file in .claude/skills/ that describes a multi-step behavior. When the agent sees a trigger phrase — either a /skill-name slash command or natural language that matches the skill’s triggers — it reads the skill file and executes the behavior described in it.

The skill file is just instructions. It isn’t code; it’s a detailed specification of what to do, written for the agent to follow. That means you can write a skill in plain English, and the agent executes it using whatever tools it needs.

A minimal skill file:

# Health Check

Run a system health check. Steps:
1. Check ~/agent-system/state/health.json for the last heartbeat timestamps.
2. Run `crontab -l | wc -l` to count active cron jobs.
3. Check disk usage with `df -h ~`.
4. Summarize: what's green, what needs attention. Keep it under 200 words.

Save that as .claude/skills/health-check.md. Now /health-check or “run a health check” will execute the full behavior every time.

Where skills live

Skills can be global or project-scoped:

Global (~/.claude/skills/): available in every session, everywhere. Good for behaviors you want in all contexts: briefing generation, PR review, logging a food entry.
Project-local (.claude/skills/ in the project root): available only in that project’s sessions. Good for project-specific workflows: “run the deployment pipeline for this service,” “generate a feature summary for this repo.”

The agent checks both locations when it sees a skill invocation.

Invoking a skill

Two ways to invoke a skill:

Explicit slash command:

/health-check
/code-review --effort high
/log-food "greek yogurt 200g"

Natural phrasing. Skill files can list trigger phrases that the agent recognizes without the slash prefix. The CLAUDE.md system prompt for this agent system includes triggers like “run a health check” and “show my briefing” that map to specific skill files. The agent pattern-matches and loads the skill transparently.

Skills vs. CLAUDE.md rules vs. hooks

These three mechanisms overlap enough to be worth distinguishing:

Mechanism	Best for
CLAUDE.md	Standing rules and context that apply to every action
Skill	A defined, repeatable multi-step workflow invoked on demand
Hook	Automatic behavior that fires at session events, not on demand

A skill is explicitly invoked. A hook fires automatically (on session stop, before a tool call, etc.). A CLAUDE.md rule is always in force. Put daily-briefing in a skill; put “confirm before rm -rf” in CLAUDE.md; put “auto-fire voice reply on summary messages” in a Stop hook.

Real skills in use

The system described in Tier 3 runs about 14 global skills, including:

briefing — reads domain state files, open loops, unread email count, and Garmin health data, then generates a morning summary.
code-review — diffs the current branch, optionally posts inline PR comments or applies fixes to the working tree.
health-check — reads health.json, counts cron jobs, checks disk, and reports what needs attention.
deep-research — spins up a multi-source research loop that fan-outs to web search, adversarially verifies claims, and writes a cited report to the Obsidian vault.
log-food — parses a food description, looks it up in the nutrition database, and logs it with a calorie count.

Each of these was once a repeated prompt. Turning it into a skill took 10–20 minutes and eliminated the re-prompting overhead forever.

Writing a good skill

A few habits that make skill files reliable:

Be explicit about the output. “Summarize in under 200 words” or “write the result to state/briefing.md” leaves no ambiguity about what done looks like.

List the files to read. If the skill depends on specific state files, name them. “Read ~/clawd/domains/health/state/report.md” is faster and more reliable than “look around for the health report.”

Name the edge cases. “If the Garmin data is stale (older than 48 hours), say so and proceed without it.” Skills that encounter missing data and fall apart are worse than no skill at all.

Next: Hooks: Automating Behavior the Model Can’t Reliably Remember — infrastructure-level automation that fires at session events, regardless of context drift.