集成指南 · aibuddy Docs

概述和编写指南面向 Skill 作者。本页只讨论一件事：如果你在自己的 agent 系统里支持 Agent Skills，harness 需要实现哪些能力。

Agent Skills 规范定义的是文件格式，不定义完整运行时。也就是说，规范会告诉你 SKILL.md、frontmatter、references/、assets/、scripts/ 应该长什么样；但“什么时候把 Skill 给模型看、怎么读取资源、脚本能不能执行、权限怎么处理、加载记录怎么审计”，都属于 harness 的职责。

集成边界

先把三类责任分开：

层级	负责什么	不负责什么
Skill 文件	描述能力、触发条件、执行步骤、参考资料、模板和脚本	不授予工具权限，不决定运行时安全策略
Agent 模型	根据任务判断是否需要 Skill，并按说明完成任务	不管理全局缓存、路径隔离、权限审批
Harness	发现、校验、加载、授权、记录、压缩和隔离 Skill	不把所有 Skill 永久塞进系统提示词

这个边界很重要。Skill 是能力包，不是权限包；模型可以决定“我要不要读它”，但 harness 必须决定“它能读到什么、能执行什么、执行后如何记录”。

最小集成模型

一个可用的 Skill runtime 至少需要六个动作。

1. 发现和校验

harness 扫描一组受控目录，找到每个 Skill 的 SKILL.md，解析 YAML frontmatter，并在进入 registry 前校验格式。

最低校验项：

name 存在，符合规范命名，并与目录名一致。
description 存在，非空，不超过规范限制。
frontmatter 能被解析，正文能被读取。
引用文件路径不能越过 Skill 根目录。
可执行文件和脚本按来源信任级处理。

无效 Skill 不应进入 L1 列表。对 agent 来说，“看不到一个不可用 Skill”通常比“激活后才失败”更稳定。

2. 暴露 L1 metadata

L1 是每个 Skill 的 name 和 description。它的作用是让 agent 知道“有哪些能力可用”。

常见做法有两种：

做法	适合场景	取舍
每轮注入可用 Skill 的 metadata	Skill 数量少到中等，通用 agent	简单、模型可自主判断，但占用基线上下文
先注入分组索引，再按需查询	Skill 很多，平台型产品	基线更小，但需要额外 registry 查询能力

不要把所有 SKILL.md 正文直接拼进系统提示词。这样会失去 progressive disclosure 的主要价值，也会让不同 Skill 的规则互相干扰。

3. 按需加载 L2

当 agent 或 harness 判断某个 Skill 相关时，再加载它的 SKILL.md 正文。

两种实现都合理：

Tool 形态：给 agent 一个类似 view_skill(name) 的工具，由模型在需要时调用。
Router 形态：harness 在 prompt 装配前匹配 Skill，并把命中的正文注入上下文。

Tool 形态更透明，便于记录“模型为什么激活了这个 Skill”；Router 形态更可控，适合弱模型或高度结构化场景。不要把某一种实现说成规范要求。

4. 按需读取 L3 资源

L3 是 references/、assets/、scripts/ 等资源。规范建议按需加载，而不是在 Skill 激活时一次性读完。

harness 至少要处理：

路径必须限制在 Skill 根目录内。
reference 和 asset 读取要有大小上限。
脚本执行要走单独权限和沙箱策略。
资源读取失败要返回可理解的错误，而不是静默吞掉。

如果你的系统已经有通用 read_file 工具，也可以复用；关键是把路径范围限制在被激活 Skill 的目录内。

5. 映射工具权限

Agent Skills 规范里有可选的 allowed-tools 字段，用来声明 Skill 可能使用的预批准工具；该字段仍是 experimental，具体支持方式会因运行时不同而不同。

harness 处理它时应遵守三条原则：

它不能扩大 agent 原本没有的工具集。
它只能在当前用户、当前环境、当前权限策略允许的范围内生效。
如果字段里的工具不存在或不允许，harness 应在发现阶段过滤，或在加载时给出明确错误。

对不可信来源的 Skill，不要因为它声明了 allowed-tools 就跳过用户确认。声明是请求，不是授权。

6. 管理上下文生命周期

Skill 加载后会占用上下文。长会话里，harness 需要知道哪些 Skill 仍然活跃，哪些可以降级。

常见策略：

刚激活时保留完整 SKILL.md。
对话压缩时，把已加载 Skill 降级为 L1 metadata 加短摘要。
再次需要细节时重新读取 Skill 或对应 reference。
不把 Skill 正文混进不可追踪的对话摘要里。

这部分属于 harness 的上下文管理，不需要暴露 unload_skill 之类工具让模型自己管理。

来源和信任

不同产品可以有不同来源模型。不要一开始就设计开放市场级别的完整信任矩阵。

常见来源足够分成三类：

来源	例子	默认处理
项目级	仓库里的 `.agents/skills/`	随代码 review，适合团队共享
用户级	用户目录里的个人 Skills	用户自用，权限随当前用户
外部级	插件、市场、上传、订阅	默认不可信，先校验，再隔离，再授权

如果系统只支持项目级 Skills，就不要提前引入 marketplace、上传审核、自动进化、信任分层等复杂机制。等外部 Skill 真的进入产品边界，再扩展来源模型。

可观测性

每次 Skill 被发现、加载、读取资源或执行脚本，都应留下结构化记录。最小字段包括：

skill_name
source
version 或文件 hash
triggered_by：用户显式、模型调用、router 匹配
loaded_files
tool_or_script_calls
error
timestamp

这些记录不是为了做复杂面板，而是为了回答三个工程问题：为什么这个 Skill 被激活、它实际读了什么、出问题时能不能回放。

最小实现清单

上线前至少确认：

registry 只收合法 SKILL.md。
L1 只暴露 name 和 description，不拼接全部正文。
L2 只在相关任务中加载。
L3 文件读取有路径边界和大小边界。
scripts/ 执行有权限策略，不能默认直通 shell。
allowed-tools 只在运行时已有权限内生效。
加载失败、资源缺失、工具不可用都能被 agent 看见。
长会话压缩时能把 Skill 正文降级，而不是永久占满上下文。
加载、资源读取、脚本执行都有日志。

如果这些都没有，先不要做自动进化、市场上传、健康分、A/B 分流、复杂路由。这些属于规模化后的产品能力，不是 Agent Skills 集成的前提。

常见反模式

静态拼接所有 Skill 正文：失去按需加载，也让规则互相污染。
把 Skill 当权限声明：Skill 可以请求工具，但不能授予工具。
激活后才发现工具缺失：应在发现阶段过滤，或加载时明确报错。
资源路径不隔离：references/../secret 这类路径必须被拒绝。
脚本默认可信：scripts/ 是执行面，不能和普通 reference 同等处理。
把平台路线图写进规范页：自动进化、健康分、市场治理、SOC 保留期都应放到产品实现或运营文档里。