Communitygithub.com

aetox-skills/create-agent

优先明确范围的智能体设计技能——在创建智能体之前,先确保范围清晰。

create-agent 是什么?

此技能旨在推动一种「范围优先」的智能体设计方法。在编写任何提示词、配置或工具绑定之前,必须通过一次结构化的范围访谈,其深度取决于所设计智能体的复杂度。它并非提示词编写技能,而是范围验证技能;最终产出通过验证的智能体规范——一份蓝图,可供其他AI或人类正确构建智能体。每个智能体规范定义了8个维度:原型 → 人格 → 能力 → 输入/输出 → 生态系统 → 记忆 → 生命周期 → 风险/指标。技能内置了严格规则和分层深度系统(快速、标准、深层、关键),默认从轻量级快速层开始,仅在出现显式信号时升级。它支持多种平台(如Claude Code),并强烈建议优先推断、搜索代码库以最小化来回沟通,从而高效地设计出强大且安全的AI智能体。

兼容平台✓Claude Code~Codex CLI~Cursor✓OpenCode
npx skills add aetox-skills/create-agent

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

创建智能体

目的

以范围优先的准则设计AI智能体。在编写任何提示词、配置或工具绑定之前,你必须通过一次结构化的范围访谈。访谈的深度取决于所设计智能体的复杂度。

这不是一个提示词编写技能。它是一个范围验证技能。输出是一份通过验证的智能体规范——一份蓝图,可供其他AI或人类用来正确构建该智能体。

每个智能体规范定义了8个维度:

原型 → 人格 → 能力 → 输入/输出 → 生态系统 → 记忆 → 生命周期 → 风险/指标

铁则

  1. 先确定范围,再开始构建 — 在范围通过验证之前,不编写任何代码、提示词或工具配置。绝无例外。

    更正权限: 仅适用于 草稿/规范假设 —— 直接修正用户在规范中遗漏的假设(如缺失依赖、矛盾、安全风险),无需事先询问,只需告知调整了什么以及为什么。 严禁未经批准修改实际的代码文件、配置、工具或工作流。 如果需要更换新工具或修改现有工作流才能正确解决,必须先获得批准 —— 但如果用常识就能修正规范,那就直接处理。

  2. 最小足够深度 — 默认为快速层。仅在出现显式信号时才升级到标准/深层/关键层。不要一开始就使用标准层。

  3. 先推断,后提问 — 在提问之前,尝试从上下文、代码库、现有智能体以及用户已经说过的话中推断答案。只问那些仍然真正不确定的问题。

  4. 代码库优先 — 如果问题的答案存在于配置、文档或现有智能体中——去找出来。不要问。
    绿地例外: 如果不存在代码库(没有 index.md、AGENTS.md、opencode.jsonc 或现有智能体),则跳过代码库扫描,直接进入访谈。

  5. 最小化往返次数 — 推断规范 → 呈现草稿 → 让用户标注修改。仅针对草稿无法解决的真实空白点逐一提问。永远不要一次性抛出10个问题。

  6. 提供建议,而非开放式提问 — 每个问题必须包含一个推荐答案。给用户一些可以回应的内容。

  7. 规范必须获得批准 — 在智能体规范被明确批准之前,永远不要开始构建。对于快速层,用户对推断出的规范的确认即视为批准。将其记录为 状态: 通过快速层批准。

  8. 收到信号即停止 — 当用户说“够了”或“停止”时——立即停止。不要争辩,不要催促更多。

  9. 输出一份智能体规范 — 每次对话都必须产出一份通过验证的规范,即使在快速层也是如此。


智能体原型系统

智能体根据其原型遵循模式。使用此表格选择正确的原型,并理解应重点关注或跳过哪些访谈领域。

原型目录

#原型核心用途默认人格典型工具建议分层
🛠️系统自动化、配置、维护务实、简洁、直接CLI、文件系统、Docker、git快速 → 标准
🎨创意设计、视觉、动效富有表现力、注重细节Tailwind、GSAP、图像API快速 → 标准
💻开发者编码、架构、调试技术性、精确、彻底MCP、linter、测试运行器快速 → 深层
📝记录者文档、写作、组织清晰、结构化、耐心Obsidian、markdown、搜索快速
🔬专家单一深层领域权威、细致领域特定的CLI/MCP快速 → 深层
🎯编排者协调、委派、管理系统性、流程驱动智能体列表、交接协议快速 → 关键
🔍研究者搜索、分析、综合好奇、分析、彻底Exa、Firecrawl、网络工具快速
🎮游戏游戏特定行为好玩、适应性强游戏API、机器人框架快速 → 深层

原型最小化列表

不是“跳过”,而是说明哪些领域应该简短或在显而易见时可以跳过。

共有3个级别:

  • 深入探讨 — 全面提问
  • 简短 — 只问1-2个问题,然后总结
  • 显而易见则跳过 — 如果常识可以判断,则不提问(例如记录者 → 记忆 = 仅限会话)
原型简短显而易见则跳过深入探讨
系统身份、输入/输出记忆能力、生态系统
创意风险/指标、生命周期记忆身份、输入/输出、人格
开发者生命周期身份能力、生态系统、输入/输出
记录者生态系统风险/指标、记忆身份、输入/输出
专家输入/输出、生命周期—能力、风险/指标
编排者——所有领域
研究者生命周期、人格记忆能力、输入/输出、身份
游戏生态系统风险/指标能力、输入/输出、人格

开发者 + 身份: 简短不是跳过——身份(frontmatter)仍然需要,因为它决定了智能体何时被调用,只是让它简短(1-2句话)。

原型选择

在访谈时,根据智能体的目的推荐一个原型。如果多个原型都符合,选择主导原型并注明次要原型。

示例: "这听起来像是一个开发者原型,带有一些专家原型的重叠。
        根据最小化列表:生命周期=简短,身份=简短(仅frontmatter),
        重点关注能力和生态系统的深入探讨。"

深度分层系统

并非每个智能体都需要相同的深度。此技能定义了4个层级。 默认为快速层。 从轻量级开始,仅在信号要求时升级。

层级 1 — 快速      (推断 → 确认 → 构建,不确定时再问)
                       │                        ← 默认
层级 2 — 标准      (呈现草稿 → 用户标注 → 批准)
                       │
层级 3 — 深层      (标准 + 生态系统映射 + 依赖追踪)
                       │
层级 4 — 关键      (深层 + 风险模型 + 成本模型 + 安全门)

层级选择

信号快速标准深层关键
智能体是新的或修改的(1-2个能力),范围清晰✅———
现有智能体,小改动✅———
新智能体,单一用途,无依赖—✅——
新智能体,1-2个外部集成—✅✅—
多智能体生态系统中的智能体——✅✅
处理支付/认证/PII———✅
部署到生产环境———✅
单次调用token成本高———✅
安全或合规影响———✅
原型 = 编排者———✅
原型 = 专家——✅—

默认为快速层。 仅在出现显式信号时升级。

升级规则: 如果在较低层级的访谈中发现需要更高层级的信号,则显式升级:

升级说明:
  触发点: [你发现了什么]
  证据: [你在哪里发现的]
  维持现状的风险: [为什么较低层级不安全]

层级 1 — 快速

适用于简单的智能体和小改动。从上下文中推断出规范,与用户确认,然后构建。无需完整访谈,无需单独的批准关口。

不要过度思考这个层级。如果不确定,仍然从这里开始——复杂性会在推断过程中显现出来。如果出现信号,则升级。

进入条件

  • 智能体是新的(1-2个能力)或现有的但有小的修改。
  • 没有超出已存在的范围的外部集成。
  • 没有多智能体协调。
  • 没有安全、成本或合规风险。
  • 需求足够清晰,以至于进行8个领域的访谈会显得过度设计。

流程

1. 从上下文推断规范    ← 从用户所说 + 代码库 + 现有智能体中读取
2. 呈现迷你规范          ← 使用下方固定格式
3. 用户标注              ← "哪里需要修改请告知"
   如果标注是琐碎的(1-2个词,轻微修改名称/格式)
     → 可以直接构建
   如果标注是结构性的(增加能力、更换工具、修改边界)
     → 先呈现修订后的迷你规范 → 用户确认 → 然后构建
4. 构建

迷你规范格式(固定)

## 快速规范:[名称]

任务:[一句话 — "做什么,为谁,得到什么"]
能力:
  - [动作 1]
  - [动作 2]
边界:
  - [禁止做什么]
权限:[只读 / 建议 / 在范围内修改 / 执行 / 自主]
工具:[工具 / MCP / 无需]
批准:[已通过快速层确认 / 已修订并确认]

使用文件 templates/quick-spec.md 作为实际模板。 不得缩减或跳过这些字段——如果某个字段很明显,则写 "—"(无需询问用户)。 如果修改现有智能体 → 使用相同格式,但只显示变化的字段。

示例

用户: "想要一个能帮我总结邮件的智能体"

推断:
  原型: 记录者
  能力: 读取邮件 → 生成要点摘要
  工具: Gmail MCP (已存在)
  生态系统: 由steward管理

呈现迷你规范:
  ## 快速规范:mail-summarizer

  任务:每天早上读取Gmail → 为Mike生成要点摘要
  能力:
    - 从Gmail MCP读取邮件 → 总结为要点
    - 按发件人/主题分类
  边界:
    - 禁止回复邮件,禁止删除邮件
  权限:只读(仅读取)
  工具:Gmail MCP(已存在)
  批准:—

  "用中文还是英文?所有邮件还是特定主题?"

用户: "中文,所有邮件,无需记录日志"
  (琐碎标注——请求构建)

构建.
  ## 快速规范:mail-summarizer
  ...
  权限:只读
  批准:已通过快速层确认

层级 2 — 标准

适用于新智能体和重大修改。当快速层不足时升级到标准层(复杂集成、生态系统影响或范围不明确的情况)。

流程

1. 意图入口     → 重述、识别原型、用户+目标+约束
2. 代码库扫描   → 读取 index.md、opencode.jsonc、AGENTS.md、现有智能体
                   (如果没有 → 绿地:跳过,直接呈现草稿)
3. 原型匹配     → 选择原型,应用最小化列表
4. 呈现草稿     → 从已知上下文推断完整规范 → 呈现单页草稿
                   只询问不确定之处(不是逐条提问)
5. 用户标注     → 用户编辑/添加/删除草稿内容
6. 迭代(如果需要) → 如果有空白点 → 呈现修订后的草稿
7. 提出规范     → 完整智能体规范(参见 templates/agent-spec.md)
8. 批准关口     → 用户在构建前批准

范围访谈(8个领域)

对于快速层: 全部跳过——从一开始就推断并确认。

对于标准层及以上:

  1. 从已有上下文推断草稿规范 → 呈现单页草稿给用户
  2. 用户阅读后标注(修改/添加/删除)
  3. 使用下方的检查清单检查是否有遗漏——只询问草稿未涵盖的部分
  4. 应用原型最小化列表——根据原型设置简短/显而易见则跳过/深入探讨

严禁逐条按清单询问——先呈现草稿,只询问空白点。

领域 1:身份与目的

  • 名称 — 智能体叫什么?(如果未命名则提出建议)

  • 原型 — 根据目录属于哪个原型?

  • 角色 — 一句清晰的话:"此智能体为[用户Y]做[X],以便[Z]。"

  • 形象 —

    字段内容示例
    语气正式/随意/技术性/好玩/权威/温暖"技术但平易近人"
    示例短语智能体实际说出的语句"让我检查配置……找到了。问题在第42行。"

    始终推荐一个形象。

    "我建议采用一个技术但平易近人的语气——
     事实精确,对话轻松。"
    
  • 已知上下文 — 在工作之前它必须知道什么?

  • 最窄职责 — 其角色的最小有用定义是什么?

领域 2:能力与边界

  • 能力 — 核心行动,按优先级排序。 每个能力包括:

    • 描述(1句话)
    • 触发条件(如何调用此能力?)
    • 预期输出(成功是什么样子?)
    • 失败模式(如果不工作怎么办?)
  • 边界 — 明确指出它绝不能做什么的列表。 每个都以关键规则的形式编写,并包含场景描述:

    规则:禁止修改项目目录以外的文件。
    场景:用户要求“修复我的桌面设置”——智能体拥有文件系统访问权限。
    后果:礼貌地拒绝,并解释范围限制。
    
  • 工具映射 — 对于每个能力,确定需要什么工具。 在能力和边界明确之后再做这件事。

    能力:“搜索文档”
    ↓
    在代码库中搜索现有工具 → 找到 Exa MCP(网络搜索)
    ↓
    建议:“通过 Exa MCP(已配置)进行知识检索。
             如果 Exa 不可用,则通过 Firecrawl 进行网络搜索作为后备。”
    

    规则: 如果代码库中已存在特定工具,则建议使用该工具。 仅在没有现有工具符合要求时才建议一个类别。 但是: 如果现有工具与需求不匹配(例如需要本地文档搜索,但只有 Exa 网络搜索可用)——不要强行适配。标记为部分适配或存在空白,并建议更合适的类别。

    ✅ "使用 Exa MCP 进行网络搜索——已配置"
    ✅ "Exa MCP 可用于网络搜索,但工作日志搜索应使用
        Obsidian + grep 代替——对于外部搜索来说是部分适配"
    ✅ "未找到现有向量数据库。需要一个语义搜索工具,
       例如 Chroma 或 Qdrant。"
    ❌ "需要一个知识检索工具"(不够具体——Exa 存在,就使用它)
    ❌ "对所有场景都使用 Exa MCP"(强行适配——Exa 不适合本地搜索)
    

    工具类别(供空白点参考):

    知识检索         → 搜索、向量数据库、文档存储、网页抓取
    代码执行         → 沙箱、解释器、编译器、linter
    通讯             → 邮件、消息、通知、webhook
    系统操作         → 文件输入/输出、进程管理、网络、注册表
    数据处理         → ETL、转换、验证、存储
    视觉/创意        → 图像生成、布局引擎、动画
    监控             → 日志、指标、追踪、告警
    AI/大语言模型    → 模型API、嵌入、RAG流程、向量数据库
    测试             → 测试运行器、覆盖率、模拟、端到端浏览器
    
  • 技能 — 智能体可能需要哪些现有技能?

相关技能