skill-system-foundry

Skill System Foundry

用于构建和演进与 AI 无关的技能系统的元技能。

此技能负责创建和维护双层架构：技能（可包含可选能力）和角色。此系统生成的所有技能都遵循 Agent Skills 规范，并融入官方供应商指南中的编写最佳实践。角色契约符合工具集成指南，可在不同平台上无缝部署。

重要说明： 能力是父技能中的可选细粒度子技能。默认情况下不要创建能力。只有在集成方明确要求，或领域明显需要拆分（包含 3 个或更多触发上下文不同的操作）时，才引入能力。从独立技能开始；只有在有充分理由时，才演进为路由器 + 能力的模式。

架构概览

技能系统采用严格的双层架构——技能和角色。依赖关系严格自上而下，绝不反向。能力绝不能知道自己正受到编排。角色可以引用技能，但绝不能引用其他角色。

依赖方向约束的是层之间的引用关系，而不是从何处开始编排。存在两种有效的编排路径：

Path 1:  orchestration skill → roles → skills (with optional capabilities)
Path 2:  skill (standalone or router) → role(s) → skill's capabilities

• 路径 1——仅协调型技能。 精简的独立技能，负责跨领域串联角色，不包含领域逻辑。
• 路径 2——自包含技能。 领域技能加载一个或多个角色，以处理交互式工作流逻辑。技能拥有能力；角色则提供职责、权限和约束，以及交接规则、步骤顺序和交互模式。

有关每条路径的决策清单和约束，请参阅 references/architecture-patterns.md。

每一层都有明确的职责：

• 技能——规范的、与 AI 无关的知识和逻辑。遵循 Agent Skills 规范。技能直接处理任务（独立技能），或在复杂领域确有拆分必要时，选择性地路由到能力。
• 角色——规范的、与 AI 无关的编排契约。角色定义职责、权限和约束，以及交接规则和工作流步骤顺序，并组合多个技能/能力。

能力

根据任务路由到相应的能力：

能力	触发条件	路径
skill-design	创建技能、能力、角色或清单；确定架构；编写描述	capabilities/skill-design/capability.md
validation	根据规范验证技能；审计系统一致性	capabilities/validation/capability.md
migration	将扁平技能迁移到路由器 + 能力模式	capabilities/migration/capability.md
bundling	将技能打包为 zip 文件以供分发	capabilities/bundling/capability.md
deployment	部署到工具；设置包装器或符号链接；使用特定于工具的扩展	capabilities/deployment/capability.md

只阅读相关的能力文件。除非任务明确涉及多个能力，否则不要加载多个能力。

共享资源

共享资源位于技能根目录中，能力通过相对路径引用这些资源。每个能力末尾的 ## Key Resources 区块都会列出跨能力共享资源及其加载触发条件（何时阅读，而非包含什么）；特定操作所需的资源则以内联链接的形式，列在正文中对应的步骤处。路由器索引目录，能力索引文件。

references/ — 能力按需加载的指南

跨能力共享的参考资料。能力通过相对路径引用这些资料。

assets/ — 用于搭建新组件的模板

创建新组件时，复制并填写技能、能力、角色和清单模板。

scripts/ — 验证、脚手架、打包和度量工具

包含六个入口点（validate_skill.py、audit_skill_system.py、scaffold.py、bundle.py、stats.py、yaml_conformance_report.py）和共享库模块。所有入口点都支持使用 --json 输出机器可读结果。

stats.py 会报告两项基于字节数的指标，用于估算技能的上下文成本：discovery_bytes（SKILL.md 的 frontmatter 块）和 load_bytes（SKILL.md 加上所有传递可达的能力和参考文件，不包括 scripts/ 和 assets/）。字节数是确定性的磁盘信号，并不精确对应分词器结果——应关注编辑前后的趋势，而不要比较不同模型间的绝对数值。

核心原则

1. 符合 Agent Skills 规范

所有技能都必须符合 Agent Skills 规范（agentskills.io）。每个已注册的技能目录都包含一个带有有效 YAML frontmatter 的 SKILL.md。name 字段与父目录名称一致，且只能使用小写字母和连字符，最长 64 个字符。description 字段最长 1024 个字符，并同时说明技能的作用和触发时机。使用第三人称是 Foundry 的惯例，并非规范要求。

注意：能力是仅供发现机制使用的子技能。其入口文件为 capability.md。能力的 frontmatter 为可选项（如果将来可能需要移植或提升为独立技能，则使用它）。

各个层级均遵循渐进式披露：

• 第 1 级：元数据（约 100 个 token）——名称和描述，始终处于上下文中
• 第 2 级：指令（少于 5000 个 token／建议最多 500 行）——触发时加载
• 第 3 级：资源（不限）——脚本、参考资料、资源文件，按需加载

2. Token 经济性

发现阶段的 token 始终存在，成本也很高。执行阶段的 token 仅在激活时消耗。每个领域注册一个技能，而不是每项能力注册一个技能。保持路由器 SKILL.md 文件精简。将详细内容放入能力或参考资料中。在领域确实需要能力之前，优先使用独立技能。

3. 简洁

模型本身已经很智能。只添加它尚不了解的上下文。逐条审视信息：“模型真的需要这个解释吗？”详细指南请参阅 references/authoring-principles.md。

4. 自由度

根据任务的脆弱性调整具体程度。灵活的任务应给予较高自由度，脆弱的操作则应给予较低自由度。请参阅 references/authoring-principles.md。

5. 一次编写，随处适配

领域知识只在规范层（技能和角色）编写一次。领域知识变更时，只需修改一个文件。工具专用的部署指针（如有需要）属于可选的用户管理自定义项。默认使用符号链接——无需维护、单一事实来源，并符合这一原则。只有当团队中有未启用 Developer Mode 或 git 配置中未设置 core.symlinks=true 的 Windows 贡献者，或者工具要求指针进行工具专用适配时，才改用包装文件。决策指南请参阅 references/tool-integration.md。

常见陷阱

使用这个元技能时最常见的失误。之所以在此列出，是因为等你想到要加载 references/anti-patterns.md 时，通常已经遇到这些问题了。每条都链接到详细说明。

• 过早拆分能力。 能力是可选的。默认采用独立形式。只有在存在 3 个或更多触发条件互斥的不同操作时才拆分。参见 anti-patterns.md#premature-capability-creation。
• 引用同级能力。 能力彼此独立——绝不要引用同级能力。跨能力编排是角色的职责。参见 anti-patterns.md#capability-aware-capabilities。
• 嵌套过深。 最多两层（路由器 → 能力）。需要子路由器？拆分为独立的顶层技能。参见 anti-patterns.md#deep-nesting。
• 混用文件引用约定。 Markdown 链接相对于包含它们的文件解析——这是标准 Markdown 语义，并非 Foundry 特有规则。从能力入口文件（capability.md）出发，能力本地引用使用 references/<file>；引用共享的技能根目录资源则使用 ../../<dir>/<file>。从嵌套的能力引用文件（capabilities/<name>/references/foo.md）出发，偏移路径会相应变化。参见 path-resolution.md。
• 将描述写成文档，而非触发条件。 description 字段是主要的发现机制。撰写时要面向需要在 100 多个技能中进行选择的模型，而不是把它当作 README 摘要。内容要具体，使用第三人称，并包含触发短语。参见 authoring-principles.md#writing-descriptions。
• 未核实团队操作系统就使用符号链接。 符号链接是默认的部署指针机制，但在 Windows 检出环境中，如果缺少开发者模式（操作系统级符号链接权限）或 Git 配置中的 core.symlinks=true（控制 Git 在检出时是否创建符号链接，可通过 git config core.symlinks true 设置），符号链接就会悄无声息地失效。采用默认方案前，先确认团队使用的操作系统；如果无法保证这两个前提中的任意一个，就改用包装文件。参见 anti-patterns.md#symlinks-without-team-platform-verification。