创建自定义 Agent

Elftia 支持两种方式创建自定义 Agent：通过应用 UI 界面创建，或直接编写 .claude/agents/*.md 配置文件。两种方式最终都会生成一个 Markdown 格式的 Agent 配置文件。

通过 UI 创建

步骤

打开 Agent 面板（侧边栏 Agent 图标）
切换到「我的 Agent」标签
点击 「创建 Agent」 按钮
填写以下配置项：

配置项	说明	示例
名称	Agent 的显示名称	`前端代码审查`
描述	一句话说明 Agent 的能力	`审查 React/TypeScript 代码质量`
系统提示	Agent 的核心指令（Markdown 格式）	详见下方示例
模型	使用的 LLM 模型或别名	`main`、`background`
工具列表	允许使用的工具（留空 = 继承全部）	`Read, Grep, Glob`
技能	自动加载的技能	`code-standards`
MCP 服务器	关联的 MCP 服务器	`github-mcp`
权限模式	工具执行安全级别	`default`

点击「保存」完成创建

存储位置选择

创建时可以选择保存位置：

项目级 — 保存到当前项目的 .claude/agents/ 目录，仅当前项目可用
个人级 — 保存到 ~/.claude/agents/ 目录，所有项目通用

通过文件创建

直接在 .claude/agents/ 目录下创建 Markdown 文件即可。文件名即为 Agent 的标识符。

文件格式

---
name: Agent 名称
description: Agent 描述
model: main
permissionMode: default
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - ListDir
  - WebSearch
  - WebFetch
skills:
  - code-standards
---

这里是系统提示的正文内容（Markdown 格式）。

Agent 会按照这里的指令来执行任务。

完整字段参考

字段	类型	默认值	说明
`name`	string	文件名	Agent 显示名称
`description`	string	空	Agent 描述信息
`model`	string	`main`	模型选择（支持别名）
`permissionMode`	string	`default`	权限模式
`tools`	string[]	全部继承	允许使用的工具白名单
`skills`	string[]	无	自动加载的技能列表

配置示例

示例 1：编程助手

专注于编码任务，拥有完整的文件系统和 Shell 访问权限。

---
name: 全栈编程助手
description: 全栈开发助手，擅长 TypeScript/React/Node.js
model: main
permissionMode: acceptEdits
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - ListDir
  - WebSearch
  - WebFetch
  - spawn_agent
skills:
  - code-standards
  - architecture-index
---

你是一个全栈开发助手，精通 TypeScript、React 和 Node.js。

## 工作流程

1. 先理解需求，必要时提问澄清
2. 使用 Glob/Grep 查找相关代码
3. 使用 Read 阅读关键文件
4. 制定实现方案
5. 使用 Write/Edit 编写代码
6. 使用 Bash 运行测试

## 编码规范

- 遵循项目的 ESLint 和 Prettier 配置
- 新文件不超过 400 行
- 使用 TypeScript 严格模式
- 为公共 API 添加 JSDoc 注释

示例 2：研究分析 Agent

只读模式，专注于信息收集和分析。

---
name: 研究分析师
description: 从代码库和网络收集信息，进行深度分析
model: main
permissionMode: plan
tools:
  - Read
  - Glob
  - Grep
  - ListDir
  - WebSearch
  - WebFetch
  - list_skills
  - read_skill
---

你是一个研究分析师，擅长从代码库和网络中收集信息进行分析。

## 工作方式

1. 仔细理解研究主题
2. 使用 Grep/Glob 在代码库中搜索相关信息
3. 使用 WebSearch 搜索外部资料
4. 使用 WebFetch 获取网页详细内容
5. 综合所有信息，给出结构化的分析报告

## 输出格式

使用 Markdown 格式输出报告，包含：
- 摘要
- 关键发现
- 详细分析
- 建议和结论

示例 3：任务自动化 Agent

使用后台子 Agent 并行处理多个子任务。

---
name: 任务编排器
description: 将复杂任务分解为子任务并行执行
model: main
permissionMode: acceptEdits
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - ListDir
  - spawn_agent
  - Notify
---

你是一个任务编排器，擅长将复杂任务分解为可并行执行的子任务。

## 工作流程

1. 分析任务，识别可并行的子任务
2. 使用 spawn_agent 启动子 Agent 处理各子任务
3. 收集子 Agent 的结果
4. 整合结果，检查一致性
5. 使用 Notify 通知任务完成

## 子 Agent 使用原则

- 每个子 Agent 负责一个明确的子任务
- 优先使用后台模式（background: true）实现并行
- 为子 Agent 配置最小必要的工具集
- 设置合理的 maxIterations 避免无限循环

工具白名单配置

tools 字段控制 Agent 可以使用哪些工具。

可用工具名称

工具名	说明	敏感度
`Read`	读取文件内容	安全
`Write`	写入文件	敏感
`Edit`	编辑文件（查找替换）	敏感
`ListDir`	列出目录内容	安全
`Glob`	文件名模式匹配	安全
`Grep`	内容搜索	安全
`Bash`	执行 Shell 命令	敏感
`WebSearch`	网页搜索	安全
`WebFetch`	抓取网页内容	安全
`spawn_agent`	启动子 Agent	敏感
`list_skills`	列出可用技能	安全
`read_skill`	读取技能内容	安全
`Notify`	发送桌面通知	安全
`SessionsYield`	结束 Agent 循环	安全

:::tip 留空继承全部工具如果不设置 tools 字段，Agent 会继承所有可用工具（包括 MCP 工具）。只有在需要限制工具范围时才设置白名单。 :::

模型别名详解

别名	行为
`main` / `inherit`	使用当前会话的主模型
`background`	使用用户在设置中配置的后台模型（通常是轻量级模型，如 Haiku）
`sonnet`	将父模型的系列名替换为 sonnet（如 `claude-3-opus` → `claude-3-sonnet`）
`opus`	将父模型的系列名替换为 opus
`haiku`	将父模型的系列名替换为 haiku

后台模型适合用于：

WebFetch 内容摘要
子 Agent 的简单辅助任务
不需要高推理能力的数据处理

技能关联

在 skills 字段中列出技能名称，Agent 启动时会自动将技能内容注入系统提示：

skills:
  - code-standards      # 项目编码规范
  - architecture-index  # 项目架构索引

技能的查找顺序：

项目目录 .claude/skills/<name>/SKILL.md
个人目录 ~/.claude/skills/<name>/SKILL.md
插件目录 ~/.elftia/plugins/skills/<name>/SKILL.md
内置技能

测试和调试

创建 Agent 后，建议进行以下测试：

基本对话 — 确认 Agent 理解自己的角色和能力
工具调用 — 验证工具白名单是否正确配置
权限确认 — 确认权限模式是否符合预期
技能加载 — 检查技能是否被正确注入系统提示
边界测试 — 尝试让 Agent 使用未授权的工具，验证是否被正确拒绝

常见问题

问题	原因	解决方案
Agent 不使用指定的工具	系统提示中未引导使用	在系统提示中明确说明何时使用什么工具
Agent 忽略了系统提示	用户消息覆盖了指令	使用更强语气的系统提示，添加「必须」等关键词
技能未生效	技能名称拼写错误	使用 `list_skills` 工具确认可用技能名称
文件保存位置错误	路径不正确	确认文件在 `.claude/agents/` 或 `~/.claude/agents/` 下
YAML frontmatter 解析失败	格式错误	确认使用 `---` 分隔符且 YAML 语法正确

通过 UI 创建​

步骤​

存储位置选择​

通过文件创建​

文件格式​

完整字段参考​

配置示例​

示例 1：编程助手​

示例 2：研究分析 Agent​

示例 3：任务自动化 Agent​

工具白名单配置​

可用工具名称​

模型别名详解​

技能关联​

测试和调试​

常见问题​

相关链接​