agents-skills

Agent Skills

创建或更新技能包，同时将可移植核心与运行时扩展分开。此技能提供本仓库的双运行时、目录、图谱和组合规则。通用脚手架搭建和评估机制请使用 Agent Skills 开放规范和标准的 skill-creator。

快速参考

任务	加载或运行
搭建技能脚手架	标准的 skill-creator，然后参阅 frontmatter-reference.md
修复技能列表被截断或遗漏的问题	skill-context-budgets.md
审核技能	python3 scripts/validate_skill.py <skill-dir> 和 maintenance-workflows.md
选择支持文件的边界	skill-patterns.md
添加特定运行时的元数据	frontmatter-reference.md
测试触发和导航行为	skill-validation.md
维护 Claude 特定行为	anthropic-skills-guide.md
跨运行时发布	dual-distribution.md
选择技能、Agent 或两者兼用	skill-vs-agent-decision.md

核心约定

可移植基线：

• 必须包含 skill-name/SKILL.md，并明确设置 name 和包含丰富触发条件的 description。
• 将 license、compatibility 和 metadata 视为可移植的可选字段。allowed-tools 属于开放规范，但运行时支持可能有所不同。
• 让正文聚焦于选择、工作流、完成标准和导航。将参考细节放入 references/，将确定性辅助工具放入 scripts/，将模板放入 assets/。
• 确保技能包单独复制后仍可使用。每个支持文件都必须从工作流或导航中链接。

运行时扩展：

• 复制运行时特定字段和替换内容前，请查阅当前官方文档进行核实。
• 如果技能依赖特定运行时的头部信息或调用行为，请在 compatibility 中注明目标运行时；删除未限定条件的可移植性声明。
• 将仅适用于 Anthropic 的机制放在 frontmatter-reference.md 和 anthropic-skills-guide.md 中，而不是可移植示例中。
• 将 agents/openai.yaml 视为面向 Codex 的附加元数据。SKILL.md 仍是规范文件，且必须能够独立通过验证；意图变更时，重新验证语义一致性。

工作流

1. 编写两到三个具体的用户任务，并包含一个不应触发此技能的相近案例。
2. 在创建任何内容之前，搜索图谱和现有 bundle。如果现有 owner 已涵盖该能力，就扩展该 owner。
3. 搭建可移植核心：文件夹、SKILL.md、name、description、最简工作流和完成标准。
4. 选择目标运行时，然后仅添加经过验证、限定于运行时的元数据。
5. 将较长的细节和可复用资源拆分到支持文件中；在需要它们的阶段链接到各文件。
6. 运行与编辑内容相匹配的静态检查，然后执行触发、非触发、导航和运行时专属评测。
7. 如果正文或路由发生变化，重新生成并验证仓库图谱和评测清单。
8. 检查差异，并在交接前修复由此次变更导致的问题。在仓库路由日志中记录观察到的路由行为。

对于每项完成声明，都要注明其证据级别：静态 bundle 验证、运行时实际加载、观察到的路由，或任务质量评估。通过 validate_skill.py 只能证明结构和本地链接正确；不能证明某个运行时已加载该技能、针对某个提示词选中了它，或生成了更好的答案。

关于创建、审计、运行时、路由器、状态和图谱的具体操作说明，请加载 maintenance-workflows.md。关于评测设计和负向对照，请加载 skill-validation.md。

设计规则

• 默认将共享技能写成客观、以结果为导向的参考资料。必要时，可将辅导式语气或更丰富的行为说明放入运行时专属层。
• 描述应足够具体，以便根据真实用户措辞选中该技能。除非运行时另有要求，否则应符合本目录的大致目标：120–180 个字符、25 个单词。
• 将路由器和组合工作流建模为明确阶段：候选来源、信息补充、附带原因的资格过滤、独立评分、选择、选择后验证，然后执行副作用。
• 信息补充不得悄然丢弃候选项或证据。应保留输入，或说明明确的过滤原因。
• 在从相邻候选项中进行选择之前，分别评估各候选项。
• 不要仅为适配发现列表而缩减有用的完整正文说明。使用特定宿主的目录控制和渐进式披露；生成的精简索引不会过滤原生启动发现。
• 除非某项模型质量或节省 token 的数据有可复现的对照、注明日期的证据，并披露其局限，否则不要发布此类数据。

完成约定

技能变更满足以下条件后，即视为完成：

• 可移植 frontmatter、本地链接、支持文件导航和源元数据均通过适用的静态检查；
• 运行时专属字段已限定适用范围并经过验证，而非被描述为可移植内容；
• 如果选择语义发生变化，已覆盖触发和非触发行为；
• 受影响时，图谱、目录和长技能清单等产物已同步；
• 答案中使用的已知错误、当前运行时行为和特定版本变通方案，均已对照当前一手来源进行核查；
• 任何剩余问题均已通过证据标明为既存问题或超出范围。

导航

仅加载当前决策所需的资源：

• skill-context-budgets.md — Codex 目录溢出、特定宿主的控制措施和验证
• maintenance-workflows.md — 仓库操作指南、验证命令、完成标准和常见陷阱
• frontmatter-reference.md — 可移植的和特定运行时的标头约定
• skill-patterns.md — 渐进式披露、脚本支持、有状态和可组合模式
• skill-validation.md — 静态、触发、非触发、导航和有效性声明评估
• anthropic-skills-guide.md — 仅适用于 Anthropic 的行为
• dual-distribution.md — 规范源和包装器漂移控制
• skill-vs-agent-decision.md — 放置位置和执行边界决策
• data/sources.json — 此技能使用的带日期来源

脚本：

• scripts/validate_skill.py — 单个技能包
• scripts/validate_catalog.py — 目录根目录
• scripts/audit_skill_metadata.py — 元数据、本地清单阈值和紧凑索引结构
• scripts/build_skill_graph.py — 本地技能图
• scripts/test_validate_skill.py — 验证器回归测试

相关技能：agents-subagents、agents-hooks 和 agents-mcp。

事实核查

• 根据一手来源核实当前外部事实、字段语义、运行时限制、打包行为、已知错误和特定版本的变通方案。
• 对可能发生变化的特定运行时指南，标注平台和验证日期。
• 如果无法进行当前验证，请说明这一限制，并将该声明标记为未经验证。

经验总结循环

如果过往决策或陷阱与当前情况相关，且存在 learnings.consolidated.md，请查阅该文件；仅在需要了解历史记录或该文件不可用时，才使用 learnings.md 作为备选。否则，两者都跳过。使用 agents-skills-feedback-loop/scripts/append_learning.py 添加可长期保留的新观察；不要将主要技能正文用作任务日志。