create-subagents_skill

Overview

This skill provides expert guidance for creating, building, and using Claude Code subagents and the Task tool. It teaches how to define focused subagents, compose XML-structured system prompts, configure tool access, and orchestrate multi-agent workflows. The content emphasizes least-privilege tool configuration and practical patterns for delegation and automation.

How this skill works

The skill explains how subagents run in isolated contexts with focused roles and limited tools, returning only final outputs to the main conversation. It shows the file locations and precedence (project vs user), required YAML frontmatter, model selection, and the XML prompt structure Claude expects. It also describes the Task tool workflow for launching and coordinating subagents automatically or by explicit invocation.

When to use it

• Delegating research, code analysis, or reporting tasks that require no user interaction
• Generating code or tests from pre-defined requirements
• Running security, performance, or quality reviews as autonomous steps
• Orchestrating multi-step pipelines where the main chat handles decisions and the subagents execute work
• Enforcing least-privilege access to tools during automated runs

Best practices

• Give each subagent a specific, narrow role and domain-specific instructions
• Use pure XML tags (<role>, <constraints>, <workflow>, <output_format>) and remove markdown headings from the system prompt
• Define tools explicitly to follow least-privilege; omit tools only when you want inheritance
• Put project-specific subagents in .claude/agents/ to override user-level versions
• Write success_criteria and validation tags so outputs are verifiable
• Test subagents on representative inputs and add recovery instructions for common failure modes

Example use cases

• Create a code-reviewer subagent that reads diffs and reports security and style issues with file:line references
• Use an api-researcher subagent to gather API docs and produce a concise spec for the main chat to review
• Launch a test-writer subagent to generate unit tests after the main chat confirms scope
• Run a documentation-generator subagent to produce formatted docs from source comments
• Orchestrate sequential steps: main chat gathers requirements → subagent researches → main chat confirms → subagent generates deliverable