agent-add-skill

name	agent-add-skill
description	在 opencc 中添加自定义 Agent 的操作指南。支持三种方式： (1) Markdown Agent —— 最简单，放 .md 文件即生效 (2) TypeScript Built-in Agent —— 编译到 CLI 二进制中，始终可用 (3) JSON Agent —— 通过 settings.json 配置 当你需要在 opencc 中创建新的 Agent（比如一个专门做代码审查的 agent、一个专门写测试的 agent 等）时使用。不涉及 AgentTool 本身的修改，只教你怎么新增一个 agent 定义。

Agent 添加指南

三种方式对比

方式	难度	灵活性	适用场景
Markdown Agent	⭐ 简单	中	快速原型、个人专用 agent
TypeScript Built-in	⭐⭐⭐ 复杂	高	核心功能、需要编程逻辑的 agent
JSON Agent (settings)	⭐⭐ 中等	低	简单配置、团队共享

---

方式 1：Markdown Agent（最简单）

在 ~/.claude/agents/ 或项目级 .claude/agents/ 目录中放入 .md 文件。

文件结构

~/.claude/agents/
└── my-agent.md

格式要求

---
name: my-agent
description: 简短描述，告诉 AI 什么时候用这个 agent
tools: [GlobTool, GrepTool, FileReadTool, BashTool]
model: sonnet
background: false
---

# My Agent

这里是 Agent 的系统提示词（body 全文都是提示词）。

告诉 Agent 它是什么、有什么能力、应该怎么工作。

支持的 frontmatter 字段：

| 字段 | 必需 | 说明 |
|------|------|------|
| `name` | ✅ | Agent 名称，用作 identifier |
| `description` | ✅ | Agent 的 when-to-use 描述 |
| `tools` | ❌ | 允许的工具列表，不设置则继承父级 |
| `disallowedTools` | ❌ | 禁止的工具列表 |
| `model` | ❌ | 模型：`sonnet`/`opus`/`haiku`/`inherit` |
| `color` | ❌ | 终端颜色：`blue`/`green`/`vermilion` 等 |
| `background` | ❌ | `true` 则默认后台运行 |
| `permissionMode` | ❌ | `plan` 要求 plan 审批模式 |
| `maxTurns` | ❌ | 最大 agentic turn 数 |
| `isolation` | ❌ | `worktree` 在隔离副本中运行 |
| `memory` | ❌ | 记忆范围：`user`/`project`/`local` |
| `effort` | ❌ | 投入度：`low`/`medium`/`high` 或数字 |
| `mcpServers` | ❌ | 需要的 MCP 服务器 |
| `hooks` | ❌ | 注册的 hooks |

示例：代码审查 Agent

---
name: code-reviewer
description: Review changed code for reuse, quality, and efficiency, then fix any issues found.
tools: [GlobTool, GrepTool, FileReadTool, FileEditTool, BashTool]
model: sonnet
---

# Code Reviewer

审查代码变更，检查：
- 是否有重复代码可以抽象复用
- 是否有不安全的操作
- 是否符合项目规范

存放位置

Agent 会自动从以下位置发现：

~/.claude/agents/         → 用户级（全局可用）
{project}/.claude/agents/ → 项目级（仅该项目可用）

---

方式 2：TypeScript Built-in Agent（高级）

编译在 CLI 二进制中，默认可用，无需额外配置。

步骤

2.1 创建 Agent 文件

src/tools/AgentTool/built-in/
└── myAgent.ts

import type { BuiltInAgentDefinition } from '../loadAgentsDir.js'

function getMyAgentSystemPrompt(): string {
  return `你是 [Agent 名称]。

描述你的角色、能力和工作方式。

可用工具：
- ToolA — 做什么
- ToolB — 做什么
- ToolC — 做什么

工作流程：
1. 第一步...
2. 第二步...
3. 第三步...`
}

export const MY_AGENT: BuiltInAgentDefinition = {
  agentType: 'my-agent',
  whenToUse: '描述这个 agent 什么时候被调用',
  tools: ['*'],      // '*' = 允许所有工具
  // disallowedTools: ['AgentTool'],  // 或排除特定工具
  source: 'built-in',
  baseDir: 'built-in',
  // model: 'haiku',  // 可选，默认使用子 agent 模型策略
  getSystemPrompt: getMyAgentSystemPrompt,
}

关键接口：

字段	类型	说明
agentType	string	Agent 名称，AgentTool 的 subagent_type 参数使用
whenToUse	string	AgentTool 工具描述中显示的用途
tools	string[]	允许的工具列表，['*'] 表示全部
disallowedTools	string[]	禁止的工具
getSystemPrompt	() => string	返回 Agent 系统提示词的函数（支持动态生成）
source	'built-in'	固定为 'built-in'
model	string	'sonnet'/'opus'/'haiku'/'inherit'

2.2 注册到 Agent 列表

编辑 src/tools/AgentTool/builtInAgents.ts：

// 1) 添加 import
import { MY_AGENT } from './built-in/myAgent.js'

// 2) 添加到 agents 数组
const agents: AgentDefinition[] = [
  GENERAL_PURPOSE_AGENT,
  STATUSLINE_SETUP_AGENT,
  MY_AGENT,              // ← 加在这里
]

2.3 验证

# 验证 Agent 能被加载
bun -e "
const { getBuiltInAgents } = require('./src/tools/AgentTool/builtInAgents.ts');
const agents = getBuiltInAgents();
console.log(agents.find(a => a.agentType === 'my-agent'));
"

示例：test-writer Agent

文件: src/tools/AgentTool/built-in/testWriterAgent.ts

import type { BuiltInAgentDefinition } from '../loadAgentsDir.js'

function getSystemPrompt(): string {
  return `You are a test writing specialist.

Your job is to write comprehensive tests for code changes.

Rules:
- Write unit tests using the project's existing test framework
- Cover edge cases and error paths
- Mock external dependencies
- Aim for >80% coverage on modified code
- Follow existing test patterns in the codebase`
}

export const TEST_WRITER_AGENT: BuiltInAgentDefinition = {
  agentType: 'test-writer',
  whenToUse: 'Write unit tests, integration tests, or test coverage for code changes',
  tools: ['*'],
  source: 'built-in',
  baseDir: 'built-in',
  getSystemPrompt,
}

---

方式 3：JSON Agent（settings.json）

配置位置

用户级: ~/.claude/settings.json 项目级: .claude/settings.local.json

格式

{
  "agents": {
    "my-agent": {
      "description": "简短描述用途",
      "prompt": "Agent 系统提示词全文",
      "model": "sonnet",
      "tools": ["GlobTool", "GrepTool", "FileReadTool"],
      "background": false,
      "permissionMode": "plan"
    }
  }
}

支持字段：

字段	必需	说明
description	✅	when-to-use 描述
prompt	✅	系统提示词（全文）
model	❌	sonnet/opus/haiku/inherit
tools	❌	允许的工具列表
disallowedTools	❌	禁止的工具
background	❌	默认后台运行
permissionMode	❌	plan / accept / bypass
maxTurns	❌	最大 turn 数
effort	❌	投入度

示例

{
  "agents": {
    "issue-responder": {
      "description": "Respond to GitHub issues with triage and suggested solutions",
      "prompt": "You are a GitHub issue triage agent.\n\nWhen given an issue:\n1. Analyze the problem description\n2. Search the codebase for relevant code\n3. Suggest a solution approach\n4. If possible, implement the fix\n\nAlways be polite and thorough.",
      "model": "sonnet",
      "tools": ["GlobTool", "GrepTool", "FileReadTool", "FileEditTool", "BashTool"]
    }
  }
}

---

如何使用自定义 Agent

三种方式添加后，都通过 AgentTool 调用：

Agent  subagent_type: "my-agent"  prompt: "为我做这件事"

AgentTool 会自动发现所有可用 agent（built-in + markdown + JSON）， 在 subagent_type 参数中列出。调用时只需传入 agent 名称即可。

---

最佳实践

1. Markdown 方式首选：除非需要编译时确定性，否则 markdown agent 更灵活
2. 系统提示词要具体：告诉 Agent 它是什么、能力边界、工作流程
3. 工具权限最小化：只给 Agent 完成任务必需的工具
4. model 选择：简单 agent 用 haiku 省钱，复杂 agent 用 sonnet 保留质量
5. background: true：耗时任务（研究、分析）设后台运行
6. 验证 agent 注册：添加后运行 bun -e "..." 脚本确认能被发现

快速调试

# 查看所有已注册 agent
bun -e "
const { getBuiltInAgents } = require('./src/tools/AgentTool/builtInAgents.ts');
console.log(getBuiltInAgents().map(a => a.agentType));
"

# 查看特定 agent 详情
bun -e "
const { getBuiltInAgents } = require('./src/tools/AgentTool/builtInAgents.ts');
const a = getBuiltInAgents().find(a => a.agentType === 'my-agent');
console.log(a?.agentType, a?.source);
"