---

name: create-agent locale: wenyan source_locale: en source_commit: 82c77053 fence_basis_commit: 82c77053 translator: "Julius Brussee homage — caveman" translation_date: "2026-04-19" description: > Create a new agent definition file following the agent-almanac agent template and registry conventions. Covers persona design, tool selection, skill assignment, model choice, frontmatter schema, required sections, registry integration, and discovery symlink verification. Use when adding a new specialized agent to the library, defining a persona for a Claude Code subagent, or creating a domain-specific assistant with curated skills and tools. license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: general complexity: intermediate language: multi tags: meta, agent, creation, persona, agentskills

建新行者

定 Claude Code 之子行者，有專之志、擇之器、配之技、全之文，循行者樣與籍制。

用時

• 為未覆之域增新專行者於籍
• 轉反復之流或提示模式為可重用行者
• 建域專之助，有擇技與限器
• 析過廣行者為專職單責
• 設團前擬新成員

入

• 必要：行者之名（小寫中劃線，如 data-engineer）
• 必要：行者主志之一行述
• 必要：志明所解之題
• 可選：模型（默 sonnet；替 opus、haiku）
• 可選：優先（默 normal；替 high、low）
• 可選：由 skills/_registry.yml 配之技集
• 可選：所需 MCP 伺（如 r-mcptools、hf-mcp-server）

法

第一步：設行者之人格

擇清晰專之身：

• 名：小寫中劃線，明職。始以名詞或域飾：security-analyst、r-developer、tour-planner。避泛名如 helper 或 assistant。
• 志：一段述此行者所解之具體題。問：「此行者為何？何行者未覆？」
• 語調：按域。技術者宜精引證多；創意者可探；合規者宜正式具審。

行前察與現 53 行者之重：

grep -i "description:" agents/_registry.yml | grep -i "<your-domain-keywords>"

得： 無現行者覆同利基。若部分重，宜擴現者非建新。

敗則： 若現行者重甚，或擴其技集，或窄新者範以補而非重。

第二步：擇器

擇行者所需之最小器集。最小權之則施：

器集	用時	例行者
[Read, Grep, Glob]	唯讀析、審、查	code-reviewer, security-analyst, auditor
[Read, Grep, Glob, WebFetch]	析兼外查	senior-researcher
[Read, Write, Edit, Bash, Grep, Glob]	全開發——建改碼	r-developer, web-developer, devops-engineer
[Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch]	開發兼外研	polymath, shapeshifter

唯析碼者勿含 Bash。不需外查者勿含 WebFetch 或 WebSearch。

得： 器列唯含行者實用之器。

敗則： 察行者能力列——若能力不需器，刪之。

第三步：擇模型

按任務繁選：

• sonnet（默）：多行者。推理速度衡。用於開發、審、析、標準流。
• opus：繁推、多步劃、微判。用於高級行者、架構決、需深域專者。
• haiku：簡速應。用於直查、格、填樣者。

得： 模型合行者主用案之認知需。

敗則： 疑則用 sonnet。唯試示推理不足乃升 opus。

第四步：配技

覽技籍擇行者域相關者：

# List all skills in a domain
grep -A3 "domain-name:" skills/_registry.yml

# Search for skills by keyword
grep -i "keyword" skills/_registry.yml

為前言建技列：

skills:
  - skill-id-one
  - skill-id-two
  - skill-id-three

要： 諸行者自動繼籍之 default_skills（meditate、heal）。勿列於前言，除其為行者法之核心（如 mystic 列 meditate 乃因冥想之引為其主志）。

得： 技列含 3-15 存於 skills/_registry.yml 之技 ID。

敗則： 驗每技 ID 存：grep "id: skill-name" skills/_registry.yml。刪不合者。

第五步：書行者文件

複樣填前言：

cp agents/_template.md agents/<agent-name>.md

填 YAML 前言：

---
name: agent-name
description: One to two sentences describing primary capability and domain
tools: [Read, Write, Edit, Bash, Grep, Glob]
model: sonnet
version: "1.0.0"
author: Philipp Thoss
created: YYYY-MM-DD
updated: YYYY-MM-DD
tags: [domain, specialty, relevant-keywords]
priority: normal
max_context_tokens: 200000
skills:
  - assigned-skill-one
  - assigned-skill-two
# Note: All agents inherit default skills (meditate, heal) from the registry.
# Only list them here if they are core to this agent's methodology.
# mcp_servers: []  # Uncomment and populate if MCP servers are needed
---

得： YAML 前言無訛而解。諸必要域（name、description、tools、model、version、author）皆存。

敗則： 驗 YAML 語法。常病：版本字串缺引號、縮進誤、器列括弧未閉。

第六步：書志與能

替樣之虛位：

Purpose：一段述此行者所解之題及所供之值。具體——名域、流、果。

Capabilities：粗體領之點列。能多則依類分組：

## Capabilities

- **Primary Capability**: What the agent does best
- **Secondary Capability**: Additional functionality
- **Tool Integration**: How it leverages its tools

Available Skills：列諸配技並簡述。用赤技 ID（斜線命令名）：

## Available Skills

- `skill-id` - Brief description of what the skill does

得： 志具體（非「助開發」），能力具體可驗，技列合前言。

敗則： 若志感泛，答：「用者會請此行者作何具體事？」以答為志。

第七步：書用案與例

供 2-3 用案，示如何呼行者：

### Scenario 1: Primary Use Case
Brief description of the main scenario.

> "Use the agent-name agent to [specific task]."

### Scenario 2: Alternative Use Case
Description of another common use case.

> "Spawn the agent-name to [different task]."

增 1-2 具體例，示用者請求與期行：

### Example 1: Basic Usage
**User**: [Specific request]
**Agent**: [Expected response pattern and actions taken]

得： 案實，例示實值，呼式合 Claude Code 慣。

敗則： 心試諸例——行者能以其器技實現乎？

第八步：書限與參

Limitations：3-5 誠實之限。行者不能為、不宜用、或果劣之處：

## Limitations

- Cannot execute code in language X (no runtime available)
- Not suitable for tasks requiring Y — use Z agent instead
- Requires MCP server ABC to be running for full functionality

See Also：交叉引補行者、相關指南、相關團：

## See Also

- [complementary-agent](complementary-agent.md) - handles the X side of this workflow
- [relevant-guide](../guides/guide-name.md) - background knowledge for this domain
- [relevant-team](../teams/team-name.md) - team that includes this agent

得： 限誠實具體。參引現文件。

敗則： 察引文件存：ls agents/complementary-agent.md。

第九步：入籍

編 agents/_registry.yml 按字母位增新行者：

  - id: agent-name
    path: agents/agent-name.md
    description: Same one-line description from frontmatter
    tags: [domain, specialty]
    priority: normal
    tools: [Read, Write, Edit, Bash, Grep, Glob]
    skills:
      - skill-id-one
      - skill-id-two

增頂之 total_agents 計。

得： 籍項合行者文件前言。total_agents 等實項數。

敗則： 以 grep -c "^ - id:" agents/_registry.yml 計之，驗合 total_agents。

第十步：驗發現

Claude Code 由 .claude/agents/ 發現行者。此庫該目錄為 agents/ 之符號鏈：

# Verify the symlink exists and resolves
ls -la .claude/agents/
readlink -f .claude/agents/<agent-name>.md

若 .claude/agents/ 鏈完，無他須為——新行者自動可發現。

運 README 自動更以更行者 README：

npm run update-readmes

得： .claude/agents/<agent-name>.md 解至新行者文件。agents/README.md 含新行者。

敗則： 若鏈斷，重建：ln -sf ../agents .claude/agents。若 npm run update-readmes 敗，察 scripts/generate-readmes.js 存且 js-yaml 已裝。

第十一步：搭翻譯之架

諸行者必需。 此步施於人作者與循此法之 AI 行者。勿略——缺翻譯積為陳積。

提交新行者後即時為四支持語搭翻譯文件：

for locale in de zh-CN ja es; do
  npm run translate:scaffold -- agents <agent-name> "$locale"
done

而後譯各文件之散文（代碼塊與 ID 留英）。終重生狀態文件：

npm run translation:status

得： 四文件建於 i18n/{de,zh-CN,ja,es}/agents/<agent-name>.md，source_commit 皆合當前 HEAD。npm run validate:translations 顯新行者無陳警。

敗則： 若搭架敗，驗行者存於 agents/_registry.yml。若狀態文件不更，明運 npm run translation:status——CI 不自動觸之。

驗

• 行者文件存於 agents/<agent-name>.md
• YAML 前言無訛而解
• 諸必要域皆存：name、description、tools、model、version、author
• name 合文件名（無 .md）
• 諸節皆存：Purpose、Capabilities、Available Skills、Usage Scenarios、Examples、Limitations、See Also
• 前言之技存於 skills/_registry.yml
• 默技（meditate、heal）未列，除非行者法之核心
• 器列循最小權之則
• 行者列於 agents/_registry.yml，路與元資料相合
• 籍之 total_agents 計已更
• .claude/agents/ 符號鏈解至新行者文件
• 與現行者無顯重

陷

• 器過配：僅需讀析者卻含 Bash、Write、WebFetch。違最小權，或致意外副作用。始於最小集，唯能需時增器。
• 缺或誤技配：列不存於籍之技 ID，或忘配技。增前皆以 grep "id: skill-name" skills/_registry.yml 驗各 ID。
• 無謂列默技：於前言加 meditate 或 heal 而其已由籍繼。唯為行者法之核心（如 mystic、alchemist、gardener、shaman）乃列。
• 與現者範圍重：建新行者而其能已覆於 53 現行者之一。先搜籍，考擴現者之技而非重。
• 志能泛：書「助開發」而非「建 R 包，含全構、文、CI/CD 設」。具體乃行者有用可發現之由。

參

• create-skill — 建 SKILL.md 文件之平行法，非行者文件
• create-team — 組多行者為協團（劃中）
• commit-changes — 提交新行者文件與籍更