Agent能力体系Skill建设通用方法论

Agent能力体系（Skill）建设通用方法论

> 编号: 33

> 作者: 明察（产品总监 明察）

> 日期: 2026-06-13

> 版本: V1.0

> 定位: AI原生创业方法论体系第33篇

> 关联: 第31篇《AI时代的帝王之术——从恋爱到帝国的AI原生创业五步法》

一、为什么需要Skill方法论

1.1 痛点

AI原生创业到"结婚"阶段，创业者创建了第一个AI联合创始人Agent。但很快发现：

• 能力膨胀：Agent功能越来越多，启动越来越慢
• 一损俱损：一个功能超时，整个Agent瘫痪
• 重复建设：多个Agent各实现一套相同能力
• 无法扩展：新增能力需要改Agent代码、重启进程
• 难以管理：能力越来越多，不知道有哪些、怎么用

1.2 本质

这些问题的根源是：Agent和能力没有分离。

就像一个人把所有技能都写在自己脑子里——学新技能要重写大脑，一个技能出问题整个人瘫痪，两个人学同样的技能各学一遍。

解决方案：把能力从Agent中剥离出来，封装为独立的Skill。

1.3 一句话定义

Skill = Agent的独立能力单元，按需加载、独立熔断、可复用、可热插拔。

思想源流：从微内核到Skill生态

Skill方法论的工程源流与实战校准：

• 微内核架构传统：操作系统插件化、浏览器扩展机制——"核心保持精简，能力按需挂载"是被验证了数十年的工程智慧。Agent的微内核+Skill体系是同一思想在AI时代的落地。
• 微服务治理模式：熔断器、降级、独立超时来自微服务治理的成熟模式。本方法论把"服务级容错"细化到"Skill级熔断"，故障爆炸半径从整个Agent缩小到单个能力单元。
• MCP开放标准：能力对外暴露走MCP协议（鉴权+限流+审计），让Agent的能力既能内部复用，也能对外服务——成熟度模型L4的依据。
• AHUB全量迁移实战：78个Skill迁移完成（L4水平），查询/生成分离、独立熔断、热注册每一条都经过量产验证。

一句话：Skill化的本质是"能力与身份分离"——Agent是指挥官，Skill是可插拔的专业执行者。

二、Skill的核心原则

2.1 原则一：查询/生成分离

这是最重要的原则。

为什么必须分离？

如果查询和生成混在一起，生成超时会把查询也拖死。就像一个人同时做两件事——一件需要思考（生成），一件只需要翻笔记本（查询），思考卡住了连翻笔记本也被阻塞。

实操规则：

• 查询类Skill：只读数据，不调LLM，毫秒级响应
• 生成类Skill：调用LLM生成内容，秒级响应，必须设超时和熔断
• 混合Skill必须拆分：一个查询Skill + 一个生成Skill

2.2 原则二：独立熔断

每个Skill独立熔断，故障不传染。

熔断器工作原理：

正常 → 失败次数达阈值 → 熔断打开 → 拒绝请求 → 60秒后半开 → 尝试一次 → 成功恢复/失败继续熔断

关键：Skill A超时，只影响Skill A。Skill B正常执行，不受影响。

故障爆炸半径：从"整个Agent"缩小到"单个Skill"。

2.3 原则三：按需加载

Agent启动时不加载所有Skill，用到时才加载。

好处：Agent启动快、内存占用低、LLM prompt精简。

2.4 原则四：可复用

跨Agent共享Skill，避免重复建设。

识别共享Skill的标准：

• 多个Agent都需要的能力（如健康检查、日报生成）
• 行为一致、逻辑统一的能力
• 修改一处全局生效的能力

实操：创建shared类Skill，由需要的Agent共同调用。

2.5 原则五：热插拔

新增Skill不需要重启Agent，热注册即可。

传统方式：改Agent代码 → 改路由 → 改API → 重启进程

Skill方式：创建Skill目录 → 编写SKILL.md + skill.py → 热注册

开发效率：从"改5个文件+重启"变为"加1个目录+热注册"。

三、Skill建设五步法

第一步：能力盘点

目标：搞清楚Agent当前有哪些能力，哪些该保留、哪些该拆分、哪些该共享。

操作：

1. 列出Agent所有能力入口（API、handler、方法）
2. 按功能分类（查询/生成/检查/管理/扫描...）
3. 标记每个能力是否调用LLM
4. 识别跨Agent重复的能力

产出：能力清单表

第二步：能力拆分

目标：把混合能力拆成查询+生成，把重复能力合并为共享。

拆分规则：

• 查询+生成混合 → 拆成查询Skill + 生成Skill
• 多Agent重复 → 合并为shared Skill
• 粒度过粗 → 按功能拆细
• 粒度过细 → 按场景合并

命名规范：

{agent}-{function}-{type}

agent: agent名称（mingcha/fengming/xuanji/tianshu/shared）
function: 功能描述（kebab-case）
type: query | generate | check | manage | scan | file | register | apply | ...

示例：
- mingcha-requirement-query（明察需求查询）
- fengming-content-generate（凤鸣内容生成）
- xuanji-patent-file（璇玑专利申请）
- shared-health-check（共享健康检查）

第三步：Skill封装

目标：每个Skill封装为独立单元，包含元数据、指令、执行代码。

Skill目录结构：

skills/
  mingcha-requirement-query/
    SKILL.md          # 元数据 + 执行指令
    skill.py          # 执行代码（继承BaseSkill）
    references/       # 参考文档（可选）

SKILL.md规范：

---
skill_id: mingcha-requirement-query    # 全局唯一ID
name: 需求池查询                        # 中文显示名
version: 1.0.0                         # 语义化版本
author: mingcha                        # 归属Agent
category: product                      # 分类
tags: [需求, 查询, 产品]                # 搜索标签

triggers:
  task_types: [requirement_query]      # 匹配的task_type
  keywords: [需求, 需求池, 查询需求]     # 自然语言关键词

dependencies:
  llm: false                           # 是否需要LLM
  kb: true                             # 是否需要知识库
  db: true                             # 是否需要数据库
  db_access: readonly                  # 数据库访问权限

execution:
  timeout: 5                           # 超时（秒）
  retry: 1                             # 重试次数
  fallback: 返回空需求列表               # 降级策略

mcp:
  exposed: true                        # 是否通过MCP对外暴露
  description: 查询需求池中的需求        # MCP工具描述
---

## 执行步骤

1. 解析查询条件（优先级、状态、关键词）
2. 构建数据库查询语句
3. 执行查询，返回结果列表
4. 如果查询失败，返回空列表

## 输出格式

{

"success": true,

"data": [...],

"total": 10

}

skill.py规范：

from skills.base import BaseSkill

class RequirementQuerySkill(BaseSkill):
    skill_id = "mingcha-requirement-query"
    version = "1.0.0"

    async def execute(self, context: dict) -> dict:
        # 解析参数
        priority = context.get("priority")
        status = context.get("status")

        # 执行查询
        results = await self.db.query(...)

        return {"success": True, "data": results}

    async def fallback(self, context: dict) -> dict:
        # 降级：返回空结果
        return {"success": True, "data": [], "degraded": True}

    async def health_check(self) -> dict:
        # 健康检查
        return {"status": "healthy"}

第四步：注册与路由

目标：Skill注册到Registry，Agent通过路由匹配调用。

注册流程：

1. 扫描skills/目录，读取所有SKILL.md frontmatter
2. 构建路由索引（task_type → skill_id, keyword → skill_id）
3. Agent收到任务时，匹配路由，按需加载Skill
4. 调用Skill.execute()，注入context
5. 执行失败时调用Skill.fallback()

路由匹配优先级：

1. task_type精确匹配
2. 关键词匹配
3. 意图模式匹配

第五步：验收与迭代

目标：确保每个Skill真正可用，持续优化。

四层验收模型：

红线（任一项不通过则整体不通过）：

• LLM超时无熔断保护
• 返回假数据或编造数据
• 代码报错无法执行
• 服务启动失败
• 输出不可用（乱码、格式错误、内容缺失）

四、Skill体系与AI原生创业五步法的对应

五、常见误区与陷阱

陷阱1：查询和生成不分离

表现：一个Skill既查数据又生成内容，超时时查询也挂了。

解法：拆成两个Skill，查询类独立运行不受生成类影响。

陷阱2：Skill粒度过粗

表现：一个Skill做太多事，难以维护、难以熔断、难以复用。

解法：按单一职责拆分，一个Skill只做一件事。

陷阱3：Skill粒度过细

表现：一个功能拆成十几个Skill，调用链太长、延迟叠加。

解法：按用户场景合并，一个场景一个Skill。

陷阱4：没有降级策略

表现：Skill失败时直接报错，用户体验差。

解法：每个Skill实现fallback()，查询类返回缓存/空结果，生成类返回降级提示。

陷阱5：重复建设

表现：多个Agent各实现一套相同能力，行为不一致、维护成本高。

解法：识别共享Skill，统一实现，多Agent复用。

六、Skill体系成熟度模型

AHUB当前水平：L4（微内核+Skill化+MCP架构已落地，78个Skill全量迁移完成）

七、应用场景

场景1：创业者搭建第一个Agent

1. 能力盘点：列出Agent需要的核心能力
2. 查询/生成分离：确保基础能力稳定
3. 封装核心Skill：3-5个最关键的能力
4. 注册路由：Agent可以调用这些Skill
5. 验收：确保每个Skill真正可用

场景2：企业多Agent协作

1. 共享Skill识别：健康检查、日报、通知等
2. 专业Skill拆分：每个Agent专注自己的领域
3. 协作规则：天枢协调、消息队列、异步协作
4. 治理体系：熔断、降级、审计、热插拔

场景3：AI能力对外服务

1. MCP Gateway：鉴权+限流+审计
2. Skill过滤：只暴露安全的Skill
3. 只读保护：外部调用只读不写
4. 调用审计：记录所有外部调用

八、方法论关系（知识乐高）

• Agent技能与原子服务方法论（17）：Skill的原子化理论版——原子服务定义"最小能力单元"，Skill是它的工程封装
• 多Agent协作编排方法论（18）：Skill是被编排的最小执行单元——编排器调度Agent，Agent调用Skill干活
• Agent状态管理与容错方法论（25）：独立熔断的架构底座——熔断器三状态模型在Skill层的落地
• AI原生创业五步法（03）：五步法"生子"阶段批量复制Agent的能力引擎——复制Agent+增加专项Skill
• AI原生公司技术与解决方案全景方法论（36）：L1-L5成熟度模型对应的技术栈索引，见其第四章4.2技能体系建设

九、总结

Skill方法论的核心思想：

1. 分离：查询归查询，生成归生成，能力归Skill，身份归Agent
2. 独立：每个Skill独立熔断、独立超时、独立降级
3. 复用：共享Skill避免重复建设
4. 进化：热插拔、按需加载、持续迭代

一句话：把Agent从"全能超人"变成"专业指挥官"，让Skill当"专业执行者"。

文档版本历史