Learn Claude Code

Claude Code skills and subagents

Learn how Claude Code skills (SKILL.md) package reusable know-how and how subagents work in isolated context to keep your main session clean and fast.

Lesson 4.1⏱ 9 min read🏎️ Power user❓ 3-question quiz
The short answer

Skills are folders containing a SKILL.md file that Claude loads on demand when a task matches their description, perfect for repeatable workflows. Subagents are specialist helpers with their own context window, tools and instructions, used to delegate noisy or parallel work.

Skills: expertise in a folder

A skill is a folder with a SKILL.md file (plus optional scripts, templates or reference files). Claude sees each skill's short description and loads the full instructions only when relevant, so you can have many skills without bloating context.

.claude/skills/proposal-writer/SKILL.md
---
name: proposal-writer
description: Drafts client proposals for AI projects in our house style. Use when asked for a proposal or SOW.
---
1. Ask for client name, problem and budget range.
2. Use the structure in template.md.
3. Keep it under two pages, British English.
  • .claude/skills/: project skills, shared via git.
  • ~/.claude/skills/: personal skills.
CLAUDE.md vs skills: CLAUDE.md = always-on universal rules. Skills = on-demand task playbooks. Don't stuff procedures into CLAUDE.md.

Useful skill settings

Skill frontmatter can control behaviour, for example:

  • allowed-tools: tools the skill may use without asking you first. It does not remove other tools; use disallowed-tools for that.
  • context: fork: run the skill in an isolated subagent context so its verbose output doesn't clutter your main conversation.
  • argument-hint: shows a hint in autocomplete for the inputs the skill expects.

Subagents: specialists with their own desk

A subagent is a separate Claude instance that the main session delegates work to. It gets its own fresh context window, its own system prompt and, optionally, a restricted toolset. When done, it returns a summary.

Define one as a markdown file in .claude/agents/ (or ask Claude to create one for you):

---
name: code-reviewer
description: Reviews diffs for bugs and security issues. Use after significant code changes.
tools: Read, Grep, Glob
---
You are a meticulous senior reviewer. Report issues by severity with file and line.
Analogy: the main session is the project manager; subagents are freelancers. A freelancer only knows what's in the brief you hand them, so write good briefs.

When to use subagents

  • Noisy exploration: "find everything related to payments" without flooding your main context.
  • Parallel work: research three options at once.
  • Independent review: a fresh reviewer spots issues the author-session misses.
  • Least privilege: a read-only reviewer can't accidentally edit anything.
Key fact: subagents do not automatically inherit your conversation history. Anything they need must be in their instructions or the task you give them.

Check yourself

Three quick questions to check it stuck.

Ask the tutor

Stuck on something in this lesson? Ask the AI tutor. It answers from this lesson and points you to others that help. Answers are written by AI and can be wrong. Do not include personal details, passwords or company secrets.

Frequently asked

What are Claude Code skills?

Skills are folders containing a SKILL.md file with a name, description and instructions (plus optional resources). Claude loads them on demand when a task matches the description.

What is a subagent in Claude Code?

A subagent is a specialist Claude instance with its own context window, prompt and tool permissions. The main session delegates tasks to it and receives a summary back.

Do subagents share context with the main conversation?

No. Subagents start with fresh context. Everything they need must be passed explicitly in their instructions or task description.