Raising Claude Code - Part 4: Extension

CLAUDE.md (persuasion) and settings.json (enforcement) carry you a long way. But sooner or later you hit limits.

You’re typing the same long prompt over and over
One role isn’t enough — you can’t get a different perspective on review
CLAUDE.md crosses 200 lines and needs to be broken up

That’s where Skills and Subagents come in.

What Skills are

A reusable task definition that, when invoked, makes Claude actually start doing the work it describes. Not a document that just gets read — a trigger-bearing instruction set: when it fires, Claude immediately starts executing what the file describes.

.claude/skills/code-review/SKILL.md

A frontmatter + body structure:

---
name: code-review
description: A strict code review focused on separation of concerns,
  KISS / SOLID, security, error handling, and testability.
  Fires on /code-review, or on natural-language triggers like
  "review this" / "レビューして".
---

# Code Review

## Scope
- When called with no argument: the most recent git diff (uncommitted + last commit)
- /code-review <path> to specify a path explicitly
- If the target is ambiguous, confirm with the user before starting

## Perspectives
- Separation of concerns
- KISS / SOLID
- Security (input validation, authorization, secrets)
- Error handling
- Testability

## Output format
- ID / Severity / Category / Problem / Required Action / Verification

How Skills fire

Two firing paths:

Auto-fire — every turn, Claude compares the user’s input against each Skill’s description, and fires the matching one
Manual fire — the user explicitly invokes it with /skill-name

At session start, only the description of every available Skill is preloaded into Claude’s context, and Claude consults that summary list every turn to decide. So the precision of description directly determines how often the Skill auto-fires.

The description field is everything

This is the single most important part of Skill design.

👉 A vague description makes auto-fire unreliable.

Claude looks at the description to decide “should I use this Skill on this task?” Vague descriptions give Claude nothing to match on, so the Skill never gets called on related queries.

Bad:

description: Strict code review

→ From Claude’s side, “when should I use this?” is unanswered.

Good:

description: A strict code review focused on separation of concerns,
  KISS / SOLID, security. Fires on /code-review, or on natural-language
  triggers like "review this" / "レビューして".

What to write:

What it does
From which angle
When to fire (the explicit command name + natural-language triggers)

Strictly, name and description aren’t actually required (name defaults to the directory name, description defaults to the first paragraph of the body). But if you want to control when the Skill fires, write them explicitly.

When to extract a Skill

Bottom line:

👉 Don’t pre-build Skills.

Decide ahead of time “this should be a Skill” and you’ll accumulate Skills nobody uses.

The right timing:

Once you’ve written the same long prompt three times, extract it into a Skill.

Examples:

Writing review perspectives every time → /code-review
Writing the same legacy-system investigation procedure every time → /investigate
Writing the migration-plan format every time → /migration-plan

Below 3 repeats, CLAUDE.md or just typing the prompt is enough.

What Subagents are

(This part covers the concept and when to use them. The implementation specifics — how to actually write a Subagent — are covered in Part 5: Subagent implementation.)

Use them when you want to operate from a different role or in a different context.

.claude/agents/code-reviewer.md
.claude/agents/security-reviewer.md

The main agent invokes them via the Agent tool (formerly Task, renamed in v2.1.63), running them in a separate context window — and you can run multiple in parallel.

Properties:

They don’t bloat the main context
They can carry a different role / persona
Multiple can run concurrently for parallel investigations

When to reach for a Subagent

How to choose vs. a Skill:

Skill = hand a procedure to the same main agent
Subagent = delegate to a different agent

Reach for a Subagent when:

You want behavior fundamentally different from the main role (e.g., a strict reviewer)
You need to read a lot of files and don’t want to pollute the main context
You want multiple investigations to run in parallel
You want trial-and-error work hidden from the main thread

Don’t use a Subagent when:

You’ll be syncing back-and-forth a lot (the round-trip cost adds up)
The decision needs the main agent’s accumulated context
It’s a single-turn simple operation (a Skill is enough)

Skill / Subagent / CLAUDE.md — choosing where to put new rules

Decision table for adding a new rule:

A policy you want active in every session → CLAUDE.md
A procedure you want to be able to invoke any time → Skills
Behavior you want done in a different role → Subagents
Physical block on a dangerous operation → settings.json deny
Automatic check after every edit → Hooks

Keep this table memorized and “where do I put this?” stops being a question.

Wrap-up

Skills are reusable task definitions. A vague description won’t auto-fire reliably
Extract Skills on the rule of three (same long prompt three times)
Reach for Subagents when you want a different role / a separate context
Skill = hand off a procedure. Subagent = delegate the work.

When CLAUDE.md alone stops being enough, extend with these two. But don’t pre-build them — that applies to both.

Next is Part 5: Subagent implementation — concrete authoring, role design, multi-Subagent coordination, the parts left at “concept only” here. After that, Part 6 closes the series: Operations — the incident-driven improvement loop and replay tests.