2.3 · Skills, slash commands, subagents

A skill is a folder with a SKILL.md describing when to trigger it and what to do. The frontmatter has 'name' and 'description'; the description is the trigger — Claude reads it and decides whether the skill applies to the current task. Skills can also include supporting scripts and reference files.

.claude/skills/release-prep/
├── SKILL.md              # the entry point Claude reads
├── changelog_template.md  # optional reference material
└── check_version.sh      # optional supporting script

# SKILL.md contents:
---
name: release-prep
description: Use when preparing a versioned release — bumping
  the version, generating changelog from git log, tagging, and
  opening a release PR. Do NOT use for hotfixes.
---

# Release preparation

Steps:
1. Check current version in package.json
2. Determine bump type (major/minor/patch) from user or commits
3. Update version, run `./check_version.sh` to verify
4. Generate changelog from `git log v{last}..HEAD`
   using ./changelog_template.md as the structure
5. Commit with message "release: v{new_version}"
6. Tag and open a PR to main

The description field is not marketing copy. Write it like a router: 'Use when X. Do not use when Y. Trigger phrases include...' Vague descriptions get skills fired at the wrong times or ignored when they should fire.

Custom commands live in .claude/commands/. The file name becomes /name. The file body is the prompt template. Use for repeatable workflows: /pr-review, /new-endpoint, /incident-triage.

.claude/agents/ holds subagent definitions: name, when to invoke, allowed tools, model choice. Configure per-agent tool restriction, not universal access. Model choice per subagent lets you use a cheap model for triage and a strong model for reasoning.

Explore subagent → gets read-only tools + fast model
Code-writer subagent → gets edit tools + strong model

Skills can specify 'context: fork' in their frontmatter. When set, the skill runs in an isolated subagent context — the skill's verbose intermediate output stays out of the main conversation window. Use when the skill produces lots of tool calls or noisy analysis that would bloat the parent context.

---
name: full-repo-audit
context: fork      # runs in isolated subagent context
description: Audit the entire repo against security patterns.
  Returns a summary; intermediate scans stay in the fork.
---

(instructions...)

Skill: context and instructions that get injected when triggered by description matching. Slash command: an on-demand user-triggered prompt template. Subagent: a delegated worker with its own context window and tool set. Different jobs; don't conflate them.