跳到主要内容

能力目录与治理

核对日期：2026-08-26。

1. 定义与边界​

能力目录（capability catalog）是组织里所有可被 Agent 发现的 Skill、MCP Server、内部 Tool、Sub-agent 的登记与生命周期系统。它回答：现在有什么、谁拥有、什么版本在跑、对谁可见、何时退役。

它不是应用商店首页，也不是再写一份工具 schema。MCP 的 tools/list 只覆盖当前连接的 Server；目录还要覆盖未连接的能力、权限范围和评测状态。

不适用：

  • 把 GitHub / Cursor marketplace 的安装量当生产就绪证明。
  • 让终端用户任意安装第三方 Skill 而不经 allowlist。
  • 用目录代替运行时策略引擎。

2. 为什么重要​

没有目录时，能力会以三种方式腐烂：

  • 影子能力：某同学本地 .cursor/skills/ 能跑，CI 和同事没有。
  • 权限膨胀：新 Skill 间接依赖了高风险 MCP tool，评审只看了 Markdown。
  • 无法回滚：线上 trace 写着 review-design-fidelity，不知道是哪一版正文。

治理的目标是让能力变更像代码变更：有所有者、版本、评测门禁、退役日期。

3. 核心机制​

发布单元建议是「Skill 版本 + 它所声明的 MCP Server 版本约束」，而不是只发 Markdown。

4. 架构模式​

4.1 目录条目最小字段​

interface CapabilityEntry {
  id: string;
  kind: "tool" | "mcp-server" | "skill" | "sub-agent";
  name: string;
  version: string;
  owner: string;
  description: string;
  riskLevel: "low" | "medium" | "high";
  allowedRoles: readonly string[];
  requiredMcpServers?: readonly string[];
  evalStatus: "untested" | "passing" | "failing";
  autoInvoke: boolean;
  deprecatedAt?: string;
}

autoInvoke 对应「发现层是否自动匹配」。Cursor 的 disable-model-invocation 是 Host 扩展：高风险或外部来源默认关闭自动触发。这不是 Anthropic SKILL.md 必填字段。

4.2 分层可见性​

范围典型位置谁能改默认自动触发
个人~/.cursor/skills/本人仅个人实验
项目仓库 .cursor/skills/PR 评审低风险任务可以
组织内部 registry / marketplace 镜像平台组默认关，allowlist 开
公共外部 marketplace供应商禁止默认开

禁止把项目 Skill 写进 ~/.cursor/skills-cursor/（Cursor 内置目录）。也不要把个人 Skill 当团队交付。

4.3 退役​

能力下线需要：

  1. 目录标记 deprecatedAt 与替代 id。
  2. 发现层仍返回名称，但 description 标明已退役，避免模型继续选。
  3. 运行时对已加载旧版本打警告 span；超过宽限期拒绝加载。
  4. 评测集保留「不应再触发旧 Skill」的负例。

直接删文件会导致旧 trace 无法解释。

5. 工程实现​

5.1 版本​

Skill 正文是提示词，建议 SemVer：

  • patch：措辞、链接、错别字。
  • minor：新增可选步骤或参考文件。
  • major：完成定义、工具顺序、权限声明变化。

Host 加载时把 name@version 写入 span。没有 version 时用 git SHA，禁止只记 latest。

5.2 权限合成​

effective_tools = intersection(
  user.role_allowlist,
  mcp.server_allowlist,
  skill.declared_tools,   // 工程扩展，须网关强制
  runtime.session_grants
)

Skill 声明的工具集只能缩小权限，不能扩大。若 Markdown 写了 allowed-tools: [deploy_prod] 而角色没有该权限，调用必须失败。

5.3 评审清单​

合并 Skill / 接入 MCP 前至少检查：

5.4 marketplace 的正确用法​

Marketplace 适合分发经过签名的包。生产 Host 应：

  • 只订阅内部镜像或已审计来源。
  • 安装后进入「未启用」状态，由项目显式打开。
  • 校验校验和与发布者身份，变更要重新评审（MCP 第三方 Server 同样）。

把「一键安装 50 个 Skill」当平台能力，等于放弃目录。

6. 生产实践​

实践说明
项目 Skill 进仓库与代码同 PR，CI 能跑触发评测
所有者 on-callowner 必须是团队，不是「Agent」
环境隔离staging 可开实验 Skill；prod 只加载 evalStatus=passing
与观测对齐回放页展示加载了哪个 Skill 版本，见 ../18-Agent前端与交互/轨迹回放界面.md
文档站点边界能力目录元数据可公开；.mcp-cache、密钥、真实走查报告不可进站点

本仓库当前项目级条目：implement-from-design、review-design-fidelity，依赖 frontend-workspace MCP，风险为低（只读取证；改业务代码仍走仓库权限）。

7. 常见反模式​

反模式表现后果修正
目录等于 README只在文档里列能力运行时仍全量注入登记表驱动发现层
安装即启用marketplace 装完就进上下文投毒面瞬间扩大默认关闭自动触发
无版本只改文件不打 tag事故无法回滚name@version 进 trace
Skill 提权Markdown 写上未授权工具绕过角色模型网关求交
个人覆盖项目同名个人 Skill 抢触发团队行为不一致明确优先级：会话点名 > 项目 > 个人
公开文档泄内部工具把内网 MCP、真实项目写入主库信息泄露只写机制与本仓库已公开的 MCP 名

8. 评测方法​

指标说明
Catalog Coverage运行时实际可加载集合与目录登记是否一致
Version Trace Rate含 Skill 的 run 中记录了 version 的比例
Privilege Intersection Failures提权尝试被网关拒绝的比例（应为 100%）
Deprecated Invocation Rate宽限期后仍触发旧 Skill 的次数，目标趋近 0
Review SLASkill 变更从 PR 到 prod 的评审是否包含安全项

9. 安全与治理​

  • 外部 Skill 与外部 MCP 按不可信软件供应链管理。
  • Prompt injection 可通过 Skill 正文传播，评审按 ../12-安全与治理/Prompt-Injection.md。
  • 高风险 Skill 默认 autoInvoke=false，必须被用户或系统点名。
  • 目录服务本身要鉴权；不能让任意客户端枚举未授权的高风险能力 description（description 也会泄露内部流程）。

10. 权威资料​