skill-architect

技能架构师

从不依赖特定厂商的角度，设计可移植的高质量 Agent 技能。将此技能用作独立的规划、创建、审查、重构、比较、提炼、协调和教学层，适用于任何 Agent 技能仓库或运行时。

命令模式

当用户明确指定模式时，使用相应的命令模式。如果未指定模式，则根据请求推断最接近的模式，并说明这一假设。

模式	适用场景	主要参考资料	输出
skill-architect: plan	在编辑之前，设计技能、仓库标准、门禁、发布或迁移方案	可移植性评估标准、命名与打包	范围、受影响的文件、标准、验证路径、回滚说明
skill-architect: create	创建新的可移植技能或搭建技能文件夹	可移植性评估标准	SKILL.md，以及关联的参考资料／资源／脚本和仓库元数据计划
skill-architect: audit	根据评估标准审查现有技能或技能仓库	可移植性评估标准	附有源文件引用的问题清单表、机械检查门禁状态、补丁建议
skill-architect: fix	应用 validate_skill.py 可验证的范围明确、确定性修复	可移植性评估标准	试运行补丁清单或已应用的安全修复，然后提供验证输出
skill-architect: refactor	在不改变现有技能用途的前提下改进技能	可移植性评估标准、评测方法	触发条件重写、参考资料拆分、路由清理、验证更新
skill-architect: compare	比较上游的技能开发、编写或创建者评估标准	比较研究	证据矩阵、可复用规则、采纳／拒绝决定
skill-architect: distill	审查一次会话、会话 ID／路径或一组会话，以提炼出可复用的技能	评测方法、可移植性评估标准	会话证据映射、可复用工作流、技能提案或草稿、评测计划
skill-architect: reconcile	更新过时的技能计划、审计结果、从会话提炼的提案或受阻的技能待办项	评测方法、可移植性评估标准	更新后的状态、偏差处理决定、已撤销／重新打开的事项、下一步可执行计划
skill-architect: teach	讲解技能编写标准或指导用户／Agent	可移植性评估标准、厂商适配器	简明课程、示例，以及后续练习或检查清单

模式规则

• Plan：在进行复杂的多文件更改、添加新的门禁、开展发布工作或更改跨厂商适配器之前，先制定计划。
• Create：从具体用例入手，然后先起草可移植的核心内容，再添加厂商元数据。
• Audit：默认只读；提供审查结果并等待后续指示，除非用户也要求修补。
• Fix：先试运行，再进行确定性修复；仅对安全的机械性编辑应用 fix_skill.py --write，然后运行 validate_skill.py。
• Refactor：保留原意；未经说明，不要超出请求范围重命名、拆分或更改行为。
• Compare：必须引用已检查的源资料，并将源资料中的事实与采纳决定区分开来。
• Distill：必须将会话特有事件与可复用模式区分开来，引用会话来源，并且仅在行为反复出现或价值较高时提出技能方案。
• Reconcile：必须验证先前的计划、审查结果和提案是否仍符合当前情境；对于已修复或已拒绝的事项，应予以撤销，而不是再次报告。
• Teach：应讲解最精简且有用的规则，然后给出一个具体示例，而不是直接罗列全部评估标准。

运行模式

从当前工作上下文入手，而不是先看上游规范。先检查当前工作目录、项目文件、已安装的技能位置或仓库约定。使用 Agent Skills 规范作为可移植的基础语法；外部规范用于指导内容质量，而本地规则决定可接受的 frontmatter 字段、清单、锁定文件、CI 和发布门槛。除非目标运行时和仓库架构都接受并强制执行，否则不要添加实验性的 allowed-tools。

按以下顺序进行：

1. 对请求分类——先选择 plan、create、audit、fix、refactor、compare、distill、reconcile 或 teach，再决定文件或检查项。完成标准：明确命名一种模式，或说明推断出的模式是假设。
2. 阅读本地标准——编辑前，找到当前工作目录、项目或仓库的编写标准、Agent 指令、检查命令和目标技能。完成标准：按路径列出适用标准和检查命令，或说明它们不存在。
3. 选择审查视角——结构、质量／评测、供应商兼容性、分发治理或可预测性。完成标准：明确列出涉及的每个视角。
4. 进行可预测性检查——在提出编辑建议前，检查调用是否匹配、分支是否唯一、信息层级、完成标准、起始措辞、重复内容、累积沉淀、内容膨胀、无效行以及过早完成风险。完成标准：每项检查都根据 file:line 证据给出保留或修补的决定。
5. 规划产物——决定可移植核心、参考资料、可选资源／脚本、供应商元数据和验证路径。完成标准：列出每个要新增或修改的文件，以及用于验证它的命令。
6. 精简修补——避免只为改写而改写；仅改进请求涉及的部分以及直接相关的标准违规项。完成标准：差异仅涉及计划中的文件，或明确指出每个额外文件。
7. 机械验证——交付前运行仓库检查，或最接近的本地替代检查。完成标准：使用准确命令，将每项检查报告为通过、失败或跳过。

技能架构工作流

1. 收集具体用例

只收集决定结构所需的信息：

• 应触发该技能的确切请求措辞
• 表明该技能适用的文件路径、工具、API 或错误消息
• 重复出现的任务形态：速查、工作流、路由器、审查标准或确定性辅助工具
• 目标运行时能力：检查所需工具、权限和指令加载情况；当主机专属的执行或打包细节很重要时，使用 vendor-adapters.md
• 技能是否需要参考资料、资源、示例或辅助脚本

如果结构选择存在歧义，提出一个聚焦的问题。否则根据当前工作目录、项目或仓库的模式推断，并说明这一假设。

2. 将可移植核心与适配器分开

可移植核心位于 SKILL.md 和链接的参考资料中。供应商专属细节则放在适配器部分或元数据文件中。

层级	包含内容	避免
可移植核心	触发意图、工作流、检查项、参考资料、脚本／资源	将某个供应商的 CLI 假设当作普遍事实
本地约定	必需的 frontmatter、版本、哈希、安全文件、README／插件注册表更新或平台约定	会导致本地检查失败的上游默认值
供应商适配器	OpenAI YAML、Claude 插件说明、Antigravity／Azure 约定、安装限制	为适配某一个 Agent 而更改可移植工作流
质量测试框架	评测提示词、基线对比、审查材料包、压力测试	仅凭文字审查就宣称质量有保证

3. 采用渐进式披露进行起草

让 SKILL.md 专注于路由和即时行为。将冗长的对比、高级示例、供应商矩阵和评估详情移至 references/。

最小可移植技能形态：

skills/<skill-name>/
├── SKILL.md
├── LICENSE
└── references/          # only when detail would bloat SKILL.md

仅当 assets/ 或辅助脚本能实质性提升可重复性时才添加。除非本地项目或运行时明确允许使用可执行辅助工具，否则应将脚本视为惰性技能资源；如有本地惯例，应遵循这些惯例对其进行记录、链接、哈希校验和安全扫描。

4. 打补丁前先审查

进行重要编辑前，先准备一份简洁的审计材料：

检查项	证据	决策
触发描述具体明确	SKILL.md 的 frontmatter 行	保留 / 修补
调用方式契合需求且有理据	描述、预期调用方、上下文 / 认知负荷权衡	保留模型调用 / 改为用户调用 / 添加路由器
分支各不相同	描述、命令表、模式规则	保留 / 合并仅同义词不同的触发分支
信息层级清晰	章节清单	保留在 SKILL.md 中 / 移至参考资料 / 拆分序列
完成标准可核查	每个有序步骤或命令工作流	保留 / 明确 / 补充完成标准
前置词承载重复概念	重复的行为术语和触发词	保留文字说明 / 精简为前置词
清理检查未发现残留内容	重复、过时、无效或冗长的行	保留 / 删除 / 说明
SKILL.md 足够精简	字数	保留 / 拆分
参考资料已链接	链接检查	保留 / 修补
厂商假设已隔离	相关章节 / 文件	保留 / 修补
可用机械化检查关卡	仓库脚本、CI、评测或测试夹具	运行 / 注明跳过

在评判风格或修补内容前，先执行可预测性与精简检查：

1. **调用方式是否契合：**判断该技能应由模型调用还是由用户调用。只有在确实需要自主 Agent 调用范围或跨技能调用范围时，才承担上下文负荷；多个用户调用技能造成认知负荷时，建议使用路由器技能。
2. **描述分支：**每个真实分支保留一个触发条件，删除仅因同义词不同而重复的触发条件，并将有力的前置词放在开头；这些前置词也应出现在提示词、文档或代码中。
3. **信息层级：**将每个主要区块归类为步骤、技能内参考资料或已说明的外部参考资料。将每个分支都需要的内容内联；将仅特定分支需要的细节移至上下文指针后。
4. **完成标准：**每个有序步骤都应以可核查的完成条件结尾。拆分序列前，先明确含糊的标准。
5. **过早完成风险：**如果可见的后续步骤会让注意力提前转移，且当前标准已无法进一步明确，则建议进行真正的上下文边界拆分。
6. **前置词：**只有在能提升执行或调用的可预测性时，才用精简的预训练概念替代重复的解释性文字。
7. **精简：**逐句检查相关性和无效内容；删除重复、残留和冗长内容，而不是润色无用文字。

对于会塑造行为的技能，至少添加一个前向测试或提示词场景。对于任何随附的 CI、shell 或代码——例如辅助脚本、代码片段或工作流示例——都应在测试夹具上执行，而不是只通过阅读来保证正确；阅读和安全扫描无法发现正则表达式错误等逻辑缺陷。只有当每项内嵌代码发现或通过项都包含测试夹具命令及观察到的输出，或明确注明跳过风险时，审计才算完整。

运行范围受限的可执行内容分流，并使用审查量表校准评测、适配器和薄弱描述相关发现；算法正确性、可利用性、性能和大型重构则应交由专门的代码审查技能处理。

**仅供评估 Skill Architect 本身的作者 / 审查者使用：**使用 Skill Architect 执行其他任务时，请跳过此目录。模式场景目录为全部九种模式提供独立的测试夹具文件、隔离说明、评分标准和仅依据描述的路由提示词。创建一个全新的案例目录，并向执行者隐去评分信息；该目录是测试输入，并不能证明这些模式已通过测试。

关于测试向量、测试框架设置、枚举一致性和严重性校准，请使用 评测方法 和 便携式量表，而不是扩充 SKILL.md。

5. 让交接内容可执行

为其他 Agent 或未来会话编写计划、提案、审计材料包或提炼后的技能规范时，应以能力最弱但仍合理的执行者为对象。引用可访问的权威资料，并提供准确路径或 URL；仅在执行者确有需要时附上关键摘录。保留本地惯例、范围边界、附带预期结果的验证命令、偏差检查和 STOP 条件。对于有依赖关系的任务，使用 交接计划评估标准说明所使用和产出的接口，以及需求覆盖情况。

用一句话说明未采纳的发现或模式及其理由，避免它们在下一次审计或对账时再次出现。

6. 验证并交接

针对当前工作上下文运行范围最小且有实际意义的检查。优先使用已有的文档化验证命令、CI 门禁、评估、夹具测试、哈希检查和安全扫描。在 skills4sh 中，运行 打包检查清单。

如果新文件包含脚本、Shell 示例、凭据使用指南、网络示例或其他安全敏感模式，请运行有针对性的安全扫描，或完整安全扫描。

准确报告通过、失败或跳过的项目。不要声称运行了实际未执行的评估、扫描或夹具测试。

辅助脚本

可选辅助脚本位于 assets/scripts/ 下，因此会作为惰性的技能资源一同打包：

脚本	用途
assets/scripts/inspect_skill.py	汇总技能文件夹的信息：文件、frontmatter、正文词数、链接的参考资料，以及明显缺失的内容
assets/scripts/validate_skill.py	对单个技能文件夹执行本地便携式技能验证，并提供仅作警告的渐进式披露提示
assets/scripts/fix_skill.py	对 SKILL.md 进行试运行或应用保守、确定性的修复，然后重新运行验证
assets/scripts/scaffold_skill.py	创建技能文件夹初始结构；--author 用于设置 metadata.author（否则省略），--openai-yaml 会添加 Codex agents/openai.yaml
assets/scripts/run_uv.py	移除继承的 UV_* 主机配置后启动 uv

每次调用时，inspect_skill.py 和 validate_skill.py 都只接受一个技能文件夹。需要处理多个技能时，请分别对每个文件夹调用相应的辅助脚本；可重复使用同一个 Python 环境。

验证和检查需要 Python >=3.10，以及在隔离运行环境中使用带哈希固定的 Python 依赖文件：首先使用 run_uv.py，将临时虚拟环境作为备用方案，并通过 python -E -B 运行每个辅助脚本。切勿将验证依赖安装到全局 Python 环境中，也不要使用 python -I。有关准确的 uv、venv 和 PowerShell 命令，以及何时报告辅助脚本不可用，请参阅辅助脚本运行环境。

Scaffold 和 fix 辅助脚本只需要 Python。修复脚本接受位于列首的字面量映射键和简单的单行字面量名称；在进行任何编辑前，它会拒绝不受支持的键或名称语法。遇到这类情况时，请手动检查，然后再进行验证。

仅在任务需要确定性检查或搭建初始结构时，才读取或运行脚本。若有本地验证命令和 CI，它们仍是最终依据。

确定性检查与判断

技能工作分为四个层次——应将它们分开，并将每项检查交给能够作出判断的层次：

层次	负责内容	示例
可移植验证器（validate_skill.py）	仅在单个技能文件夹内成立的最少确定性检查，不依赖仓库元数据或网络	有效的 YAML 和带类型的非空字段；规范规定的长度限制 + name 与目录名称一致 + kebab-case；描述包含具体的触发细节；正文不超过硬性大小上限；references/*.md 已从 SKILL.md 链接；技能内相对 Markdown 链接目标有效；Markdown 标题锚点在同一文件或跨文件时均有效
可移植修复器（fix_skill.py）	无需品味或领域判断的安全机械式编辑；除非明确指定 --write，否则仅执行试运行	规范化 frontmatter 中的 name，并在 SKILL.md 中插入缺失的 references/*.md 链接
本地绑定门禁（项目 CI）	依赖仓库约定的确定性检查；具有约束力，且涵盖范围更广	文件哈希、skills-lock.json、安全清单、文档同步、语义化版本——在 skills4sh 中，即打包检查清单
此技能的评审标准（判断）	脚本无法判断的内容	触发条件的质量、可执行部分的分类、嵌入代码的正确性（评审 + 测试样例运行）、正文深度是否超过上限、供应商隔离、叙述冗长

判断准则：如果脚本能判断，就将其自动化；如果需要推理或品味，就保留在评审标准中。 如果存在本地绑定门禁，那么在任何重叠之处，它的优先级都高于可移植验证器。可移植验证器刻意保持狭窄：它只检查单个技能文件夹内可见的事实。将某条规则（例如数值大小范围）明确规定下来，意味着它从判断范畴转向验证器；这应视为目标，而非损失。

参考文件

文件	何时加载
references/comparative-study.md	比较 Anthropic、OpenAI、Matt Pocock、Obra、Azure、Antigravity 或其他技能开发、编写、创建模式时
references/house-rubric.md	创建或评审可移植的评审标准；检查可预测性、调用适配性、完成标准、精简、枚举一致性、可执行部分分类和严重性校准时
references/vendor-adapters.md	运行时安装根目录、指针文件，以及必须排除在可移植工作流之外的供应商元数据
references/eval-methodology.md	测试触发条件、构建测试向量目录、设置轻量测试框架、比较基线行为或规划压力测试时
references/helper-runtime.md	运行 inspect_skill.py 或 validate_skill.py：隔离的 uv/venv 命令、解释器标志和不可用情况报告
references/naming-and-packaging.md	避免 slug 冲突、确定名称、更新锁文件/安全清单，以及打包仓库更新时

不可妥协事项

• 不要将特定于某个供应商的技能原封不动地用作可移植评审标准。
• 未检查来源和冲突风险前，不要用上游 skill-creator 覆盖已有技能。
• 不要提交只有宽泛概述的描述；描述必须包含简洁的能力说明，以及具体的触发/使用条件。
• 不要添加未链接的参考文件。
• 除非能明确提升可重复性且有验证途径，否则不要添加辅助脚本。
• 不要把 skills.sh 的人气当作品质证明；应检查源代码、测试、安全状况和可移植性。