Chapter

Learn the primitives — so the rest of the guide clicks (your building blocks)

Before the tiers, the vocabulary. The tiers show how to use these well; this is what they are and how to make one.

All of them are just Markdown/JSON files in your repo — check them in, and the whole team (and your CI) inherits them.

Most of these are files you commit. The central config is .claude/settings.json (precedence: managed › project › user › local) — it's where permissions, hooks, mcpServers, model, and inline agents can all be declared. A plugin is just a pre-packaged set of these files, so a teammate runs /plugin install on day one and inherits your whole setup.

Skill anatomy — auto-loaded by its description, otherwise invisible; it's a folder, so it can ship scripts:

.claude/skills/pdf-forms/SKILL.md
---
name: pdf-forms
description: Use when filling or extracting fields from PDF forms.
---
# How we handle PDF forms
- Use pdftk; never re-flatten a signed PDF.
- Helper: ./fill.py <template> <data.json>

A slash command is the same idea you trigger by hand. In fact commands are now skills under the hood — .claude/commands/review.md and .claude/skills/review/SKILL.md both make /review. Add disable-model-invocation: true to a skill to make it explicit-only.

Subagent anatomy — required fields are name and description; the body is its system prompt; it runs in its own context window and hands back only a result:

.claude/agents/security-reviewer.md
---
name: security-reviewer
description: Use proactively after auth or data-handling changes, or on "audit for security".
tools: Read, Grep, Glob      # read-only — it can't modify files
model: opus                  # high-stakes review gets max effort
---
You are a senior application security engineer. Review the diff for injection,
authz flaws, leaked secrets, and unsafe data handling. Report findings by
severity (blocker/major/minor) with file:line references. Don't pre-filter.

Create it with /agents (guided), or drop the file in.

Invoke it three ways: auto (the parent delegates when the task matches the description — that's why the description matters most), explicitly ("use the security-reviewer subagent on the auth diff"), or @security-reviewer.

Omit tools and it inherits everything; whitelist to keep it tight. (For multiple communicating sessions rather than one-shot workers, there's experimental Agent Teams — a step beyond subagents.)

The distinction that matters — skill vs subagent vs command. Same Markdown-plus-frontmatter shape; the difference is where the work happens.

A command/skill loads into your current conversation — its instructions join the active context and every step accumulates in your main window. A subagent runs in its own context window and returns just a summary.

So: reach for a skill to teach the main thread a workflow; reach for a subagent to offload heavy work and protect the main thread's context. (You can even preload skills into a subagent with a skills: frontmatter field.)