Claude Code Skills and Subagents: Reusable Workflows and Isolated Contexts

Skills contain domain knowledge or repeatable workflows that load on demand, making them suitable for API conventions, release processes, and established troubleshooting steps. A subagent has an independent context and tool set, making it suitable for reading large files, specialized reviews, or parallel investigations.

Use MCP when a task requires real-time access to external systems, and Hooks for deterministic lifecycle actions. Do not build an entire extension system for a prompt used only once.

A project Skill lives at .claude/skills/<name>/SKILL.md. Its frontmatter should provide at least a clear name and description so Claude knows when to load it; the body contains project-specific rules, steps, and verification methods.

The description should identify the triggering scenario, and the body should include only what execution requires. Split long reference material into other files in the Skill directory so Claude can read it on demand.

A Skill can describe an entire workflow from reading an issue through testing and creating a PR. A Skill that publishes, commits, or writes to an external system should not trigger automatically based only on semantic similarity.

With manual invocation, parameters enter the workflow through $ARGUMENTS. Scripts still require permission approval, and a Skill does not bypass Claude Code's security rules.

Place a custom subagent in .claude/agents/; its frontmatter defines the name, description, model, and available tools. It works in an isolated context and returns a concise result to the main session.

Minimize tool permissions for the task. A code-review-only agent usually needs Read, Grep, and Glob; add restricted Bash access only when it must run verification.

A delegated task needs a clear question, scope, and return format, such as locating the token refresh path or reviewing the current diff only against PLAN.md. The main agent does not need every file the subagent read.

An independent post-implementation review uses fresh context and reduces the tendency to defend the original solution. Keep the review prompt focused on real correctness issues so it does not encourage over-engineering merely to produce findings.

Skill and subagent files should go through code review. Use representative tasks to verify that they trigger correctly and respect tool boundaries. An overly broad description causes false triggers, while an overly long body consumes context.

Subagents have independent contexts but still consume tokens and may modify files in parallel. Make the investigation agent read-only by default; use a separate worktree and specify file ownership when parallel editing is required.