create-agent

Create Agent

This is a guide for creating a Claude Code Agent.

Required Elements

Field	Description	Constraints
`name`	Agent identifier	Lowercase letters/hyphens only, cannot start with or have consecutive hyphens
`description`	Role + delegation conditions + "Use proactively"	Criteria for Claude's delegation decision

description writing pattern

Claude reads the description and decides whether to delegate. What (what it does) + When (when to use it) must both be included.

description: >
  [역할/전문 영역 - What]
  [언제 위임할지 조건 - When]
  Use proactively when/after [트리거 조건].

Good example:

description: >
  코드 리뷰 전문가. 품질, 보안, 유지보수성 검토.
  코드 작성/수정 후 사전에 사용.
  Use proactively after code changes.

Bad example:

description: 코드를 검토합니다.  # What만 있고 When 없음 → 위임 시점 판단 불가

Creation Steps

Step 1: Create file

Single file (simple agent):

touch .claude/agents/{name}.md

Folder structure (when references are needed):

mkdir -p .claude/agents/{name}/references

Step 2: Write AGENT.md

---
name: agent-name
description: >
  역할과 전문 영역 설명.
  언제 위임할지 조건 명시.
  Use proactively when [조건].
tools: Read, Grep, Glob, Bash
---

당신은 [역할] 전문가입니다.

## 호출 시 수행 단계

1. 단계 1
2. 단계 2
3. 단계 3

## 출력 형식

[결과물 형식 정의]

Optional Fields

Field	Purpose	Example
`tools`	Allowed tools (inherits all if omitted)	`Read, Grep, Glob, Bash`
`disallowedTools`	Denied tools	`Write, Edit`
`model`	Model selection	`haiku`, `sonnet`, `opus`, `inherit`
`permissionMode`	Permission mode	`default`, `acceptEdits`, `dontAsk`
`maxTurns`	Maximum number of agentic turns	`10`
`skills`	Skills to inject at startup	`[api-conventions, error-handling]`
`hooks`	Lifecycle hooks	`{PreToolUse: [...]}`
`mcpServers`	MCP servers to use	`{server-name: {command: "..."}}`
`memory`	Persistent memory scope	`user`, `project`, `local`

Tool restriction patterns

Pattern	tools	disallowedTools
Read-only	`Read, Grep, Glob, Bash`	`Write, Edit`
Can modify	`Read, Edit, Write, Grep, Glob, Bash`	-
Least privilege	`Read, Grep, Glob`	-
Spawn control	`Task(worker, researcher), Read, Bash`	-
Cannot spawn	`Read, Bash` (omit Task)	-

Model Selection Guide

Model	When to use
`haiku`	Fast exploration, simple searches
`sonnet`	Analysis, review, balanced tasks
`opus`	Complex reasoning, architecture decisions
`inherit`	Same as main conversation (default)

Checklist

□ name이 소문자/하이픈만 사용하는가?
□ description이 역할 + 위임 조건을 명확히 설명하는가?
□ description에 "Use proactively" 패턴이 있는가?
□ 필요한 도구만 tools에 명시되었는가?
□ 읽기 전용이면 disallowedTools에 Write, Edit이 있는가?
□ 시스템 프롬프트가 역할과 단계를 명확히 정의하는가?

About this skill