用途
custom-agent 是一个面向 Claude Code 的技能，用于管理自定义智能体文件（通常位于 .claude/agents/{name}.md）。其目标包括：创建新的自定义智能体、审计已有智能体的质量，以及增强智能体定义，使每个智能体都有效、遵循最小权限原则、结构完整，并可安全地委派任务。
三种模式
技能根据请求内容自动判断模式：
- 创建（Create）：请求描述一个新智能体时触发。流程为澄清 → 检查已有智能体 → 生成骨架 → 编写系统提示 → 校验。澄清阶段会通过提问工具了解用途、只读还是读写、模型偏好、记忆需求等；然后搜索 .claude/agents/*.md 避免重复。
- 审计（Audit）：请求提及 verify、audit、review、check、quality 等时触发。流程为发现 → 完整读取并解析 → 校验 → 报告 → 修复已确认的错误。检查前必须先读完整 YAML 头和正文，页头预览仅用于发现。
- 增强（Enhance）：请求提及 refactor、enhance、improve、optimize 等时触发。流程为读取 → 分析 → 给出建议 → 应用已确认的改动。
智能体文件结构
智能体文件由 YAML 头与作为系统提示的 Markdown 正文组成。系统提示推荐结构为：## Role → ## Workflow → ## Key Rules → ## Output。智能体不继承 Claude Code 系统提示，因此必须写完整指令。
YAML 头字段包括：
- 必填：name（仅小写字母与连字符）、description（Claude 据此决定何时委派）。
- 可选工具：tools（允许列表，省略则继承全部）、disallowedTools（拒绝列表）、Task(agent1, agent2) 限制可派生的子智能体。
- 可选模型：model，取 inherit、sonnet、opus、haiku。
- 可选权限：permissionMode，取 default、acceptEdits、dontAsk、bypassPermissions、plan。
- 可选技能与 MCP：skills（启动时注入内容）、mcpServers。
- 可选钩子：hooks，作用域限于该智能体。
- 可选记忆：memory，取 user、project、local，MEMORY.md 会自动注入，并自动添加读写编辑工具。
- 可选执行：background（始终后台运行）、isolation（在临时 git worktree 中运行）。
工具限制与模型选择
技能给出按角色推荐的工具组合：探索/调查类用 Read、Grep、Glob、Bash；只读审查类用 Read、Grep、Glob；写入实现类用 Read、Write、Edit、Grep、Glob、Bash；研究类增加 WebFetch、WebSearch；编排类用 Read、Grep、Glob、Task(子智能体)。模型选择属于路由启发式而非实测质量排名：haiku 适合快速只读扫描，sonnet 适合代码审查、调试与分析，opus 可作为高风险架构或复杂实现的候选，inherit 为默认并匹配父级模型。
描述撰写与反模式
描述应包含“Use this agent when...”式具体触发场景，可加“use proactively”鼓励自动调用。常见反模式包括：不限制工具、描述含糊、系统提示过于庞大（细节交给技能）、递归子智能体（限制 Task）、Windows 下超长提示（改用文件式智能体而非 --agents 命令行参数）。
上下文传递
智能体只接收自身系统提示与任务提示，不接收父级对话；父级只收到智能体的最终结果，不收到中间工具调用。这种隔离是上下文管理的主要收益。
审计清单与评分
审计检查项包括：YAML 头是否存在（错误）、名称是否合法（错误）、描述是否非空且超过 20 字符（错误）、名称是否唯一（错误）、描述质量（警告）、工具是否最小化（警告）、提示结构是否含 Role 与 Workflow（警告）、模型是否设置（提示）。质量评分：有效 YAML 头 20 分 + 描述超过 50 字符 20 分 + 工具受限 15 分 + Role 段 15 分 + Workflow 段 10 分 + 设置模型 10 分，满分 90；80 分以上为优秀，60–79 良好，40–59 需改进，40 以下较差。
文件优先级
从高到低：--agents 命令行参数（仅当前会话）、项目 .claude/agents/.md、用户 ~/.claude/agents/.md、插件 agents/ 目录。同名时高优先级生效，可用 claude agents 命令列出全部。
适用场景与限制
适用于为 Claude Code 设计化智能体、批量审查现有智能体定义、改进权限与提示结构。需要注意：技能中包含 Codex 兼容性说明，涉及将外部工具名映射到宿主能力；模型选择仅为启发式建议，具体效果与兼容性暂未提供；提示超长等平台限制需按说明规避。