造代

定 Claude Code 子代之身。含精目、選具、賦技、備檔。

用

• 為未涵域加專代
• 化復流或模為可重之代
• 以選技具造域專助
• 分過泛代為專責代
• 組多代團前設新員

入

• 必：代名（小寫、kebab-case，如 data-engineer）
• 必：一行述代主目
• 必：解所治問之目述
• 可：模選（默：sonnet；代：opus、haiku）
• 可：優先（默：normal；代：high、low）
• 可：skills/_registry.yml 中之技列
• 可：代需 MCP 服（如 r-mcptools、hf-mcp-server）

行

一：設代身

擇明專之代身：

• Name：小寫 kebab-case、述角。起於名詞或域辭：security-analyst、r-developer、tour-planner。避泛名如 helper、assistant
• Purpose：一段述此代解之具問。問：「此代為何無存代可代？」
• Communication style：考域。技代宜精引重。創代可更探。合規代宜正式而審導

繼前察 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

為 frontmatter 築技列：

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

要：諸代自動繼庫級 default_skills 之默技（meditate、heal）。勿於代 frontmatter 列此二除非為代法核（如 mystic 代列 meditate 因冥助為其主）。

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

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

五：書代檔

複模填 frontmatter：

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

填 YAML frontmatter：

---
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 frontmatter 無誤解析。諸必欄（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

得： 目具（非「助發」）、能具驗、技列合 frontmatter。

敗： 目感泛→答：「用者當請此代作何具任？」以此為目。

七：書用例與例

予 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

得： 限誠具。See Also 引存檔。

敗： 察引檔存：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 計。

得： 庫項合代檔 frontmatter。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

軟連全則無須外動——新代檔自動可發現。

行 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 代。勿略——缺譯積為陳備。

承新代後即為諸 4 支 locales 架譯檔：

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 frontmatter 無誤解析
• 諸必欄存：name、description、tools、model、version、author
• name 合檔名（無 .md）
• 諸節存：Purpose、Capabilities、Available Skills、Usage Scenarios、Examples、Limitations、See Also
• Frontmatter 中技存於 skills/_registry.yml
• 默技（meditate、heal）非列除非為代法核
• 具列循最少特權
• 代於 agents/_registry.yml 含正路與合備
• 庫中 total_agents 計已更
• .claude/agents/ 軟連解至新代檔
• 無顯著重於存代

忌

• 具過授：僅讀析而含 Bash、Write、WebFetch→破最少特權致副效。始於最小集、能需方加
• 缺或誤技賦：列庫無之技 ID 或全忘賦技。加前以 grep "id: skill-name" skills/_registry.yml 驗
• 無謂列默技：加 meditate 或 heal 於代 frontmatter 而庫已繼。僅核方列（如 mystic、alchemist、gardener、shaman）
• 範重存代：建代復 53 存代之能。先搜庫、考擴存代之技
• 目能泛：書「助發」而非「架 R 包含全構、備、CI/CD 設」。具為代用與可發之源

參

• create-skill - 建 SKILL.md 而非代檔之並程
• create-team - 組多代為調團（計中）
• commit-changes - 承新代檔與庫更