Agents Spec Design — Defining and Using Sub-Agents

Designing agents (Agents) allows Claude Code to function not as a “general-purpose AI” but as a “team of specialists with specific responsibilities.” This page covers agent file format, how to write descriptions, tool restrictions, and model selection — while referencing actual examples in this project’s shared/agents/.

---

What Is an Agent?

An agent is a subprocess started by the Claude SDK’s Agent tool, with an independent conversation context. Agents operate as an “independent sub-conversation” separated from the main conversation, and complete specific tasks using only the designated tools.

There are two main reasons to use agents. First, separation of responsibilities: different tasks such as document creation, code review, and i18n sync can each be delegated to a specialized agent. Second, tool restriction: by limiting the tools available to each agent, unintended side effects can be prevented.

---

The Triangle of Commands, Skills, and Agents

The three main harness components each have different roles.

Aspect	Commands	Skills	Agents
Trigger	User types /command	User or Claude	Started by Claude SDK’s Agent tool
Role	Procedure manual for executing fixed work	Instruction document for changing behavior	Functions as a specialized expert
Tools	Claude’s default tools	Claude’s default tools	Only the specified tools
Context	Within the main conversation	Within the main conversation	Independent sub-conversation
File location	shared/commands/	shared/skills/	shared/agents/

Agents have the highest independence among the three and offer the strongest permission control.

---

The Format of an Agent File

An agent file consists of frontmatter and a body.

The Structure of frontmatter

---
name: agent-name
description: Description of the agent (what it does, when to use it)
tools: Read, Edit, Write, Bash, Glob, Grep
model: sonnet
---

The meaning of each field is as follows.

• name: An ID that identifies the agent. Match it to the filename (excluding .md)
• description: A description text read by Claude to judge which agent to start. This is the most important field
• tools: A list of tools this agent can use. Only listed tools are available; unlisted tools are blocked
• model: The model to use. Select from sonnet, opus, or haiku

The Structure of the Body

After the frontmatter, write instructions to the agent directly in Markdown.

---
name: docs-content
description: Responsible for creating, updating, and maintaining structural integrity of documentation articles (src/content/docs/). Use proactively when adding or editing docs pages.
tools: Read, Edit, Write, Glob, Grep, Bash
model: sonnet
---

I am a documentation specialist agent for AI Learning Playground.

## Role

- Create and update English and Japanese documentation under `src/content/docs/`
- Maintain frontmatter consistency

## Steps

1. Check CLAUDE.md and SKILL.md
2. Identify the target files
3. Create and update the Japanese page first

## Rules

- Do not use personal anecdotes or emotional expressions
- Japanese is the source of truth

The shared/agents/docs-content.md in this project is a real example of this format.

---

The Importance of description

description is the only field that Claude reads to judge “which agent to start.” The quality of the description directly determines the accuracy of agent selection.

How to Write an Effective description

It is important to clearly state not only “what it does” but also “when to use it” in the description.

# Good example: "When to use" is clear
description: Responsible for creating, updating, and maintaining structural integrity of documentation articles (src/content/docs/). Use proactively when adding or editing docs pages.

# Room for improvement: "When to use" is unclear
description: An agent that writes documentation.

Including “when not to use” conditions in the description further prevents incorrect invocations.

description: Responsible for security reviews. Use proactively when conducting security checks on PRs after code changes. Do not use for document creation or new code implementation.

---

Best Practices

One Agent, One Responsibility

Design a collection of specialized expert agents rather than a “general-purpose agent that can do anything.” This project separates responsibilities as follows.

Agent	Responsible Domain
docs-content	Creating and updating documentation articles
blog-content	Creating and updating blog posts
i18n-sync	i18n synchronization between Japanese and English
pr-review	Code review of PRs
test-verify	Testing and verification
code-implementation	Code implementation

Minimize Tools

Do not give agents more tools than necessary.

# Good example: An agent that only needs read-only operations
tools: Read, Glob, Grep

# Example to avoid: Including Write and Bash that are not actually used
tools: Read, Edit, Write, Glob, Grep, Bash

By narrowing down tools, you can eliminate the risk of an agent unintentionally overwriting files.

Choose model to Match the Use Case

Model	Suitable Cases
haiku	High speed, large volume processing. Text classification, simple conversions
sonnet	Balanced. Most development tasks
opus	Complex judgments, architecture design, difficult bug analysis

Using opus for agents that don’t require heavy judgment unnecessarily increases cost and response time.

Place in shared/agents/ and Symlink

Place agent files in shared/agents/. Since .claude/agents/ is a symlink to this directory, editing shared/agents/ is immediately reflected in Claude Code tools.

---

Hands-on Exercise

Step 1: Check the List of Existing Agents

ls shared/agents/

Example output:

blog-content.md
code-implementation.md
docs-content.md
i18n-sync.md
pr-review.md
test-verify.md

✅ Verify: If multiple agent files are displayed, the agent layer is correctly in place.

Step 2: Check the Structure of an Agent Spec

cat shared/agents/docs-content.md

Check the name, description, tools, and model in the frontmatter, and the “Role,” “Steps,” and “Rules” sections in the body.

✅ Verify: If a description like tools: Read, Edit, Write, Glob, Grep, Bash is included in the frontmatter, the tool restrictions are correctly defined.

Step 3: Create a New Agent shared/agents/security-review.md

Create a new security review specialist agent.

Content of shared/agents/security-review.md:

---
name: security-review
description: Responsible for security reviews. Use proactively when conducting security checks on PRs after code changes. Focuses on checking OWASP Top 10, authentication/authorization issues, and secret leakage risks.
tools: Read, Glob, Grep, Bash
model: sonnet
---

I am a security review specialist agent.

## Role

- Evaluate security risks in changed code
- Check for vulnerabilities based on OWASP Top 10
- Detect secret leakage risks

## Steps

1. Check the changed files
2. Check for security risks
3. Report issues and recommended fixes

## Rules

- Do not output actual secrets
- Explicitly state when there are no issues as well

✅ Verify: Run cat shared/agents/security-review.md to confirm the contents are displayed.

Step 4: Confirm the Agent Is Launched

In a Claude Code session, make the following request.

Please run a security review

Confirm that Claude selects and launches the security-review agent, and executes file reading and security checks.

✅ Verify: If Claude’s response contains “I will launch the security-review agent” or equivalent text, the automatic selection based on description is functioning.

---

Summary

• An agent operates as an independent sub-conversation, using only specified tools to complete specific tasks
• description is the only clue for Claude to judge agent selection. Including “when to use” and “when not to use” improves selection accuracy
• tools should be kept to the minimum necessary to prevent unintended side effects
• model should be selected according to the use case (haiku / sonnet / opus)
• Agent files are placed in shared/agents/. The symlink in .claude/agents/ automatically reflects changes

---

Next Steps

• Hooks Implementation — Learn about hook configuration that inserts shell commands before and after tool execution
• Harness Testing and Validation — Move on to systematically verifying that agents function as intended

---

Frequently Asked Questions

Q: Which should I use, agents or skills?

A: Use agents when you want to “delegate a task as an independent process,” and use skills when you want to “change Claude’s behavior within the same conversation.” Agents can restrict tools, so they are suitable for tasks where side effects need to be strictly managed.

Q: Are agents selected automatically, or can they also be specified manually?

A: Depending on the Claude SDK implementation, Claude automatically selects the appropriate agent by writing the description field appropriately. If you want to reliably start a specific agent, the user can also explicitly specify “use the X agent.”

Q: Can multiple agents be linked for one task?

A: Yes. For example, “sync translations with the i18n-sync agent, then review with the pr-review agent” linkage is possible. However, the mechanism for passing data between agents depends on the Claude SDK implementation, so it is recommended to check the SDK documentation before designing a linkage pattern.

Q: What happens if the tools field is omitted?

A: Tool restrictions are not applied, and all of Claude’s default tools become available. From a security and side effects perspective, it is recommended to explicitly specify tools for agents.

See the references for the external specifications and background sources used on this page.[1][2]

References

1. Anthropic, Claude Code documentation
2. Anthropic, Claude API documentation