skill-creator

技能创建器

创建、改进和审计 AI Agent 技能。每项技能都遵循 14 种经过验证的结构模式。

**范围：**仅限技能。不得用于创建 Agent（请使用 agent-conventions）、构建 MCP 服务（/mcp-creator）或运行现有技能。本仓库使用原始 SKILL.md 格式，并直接提交到 skills/。

分派

$ARGUMENTS	操作	示例
create <name> / new <name>	开发（新建）	/skill-creator create my-analyzer
create <name> --from <source>	开发（基于范例新建）	/skill-creator create my-analyzer --from wargame
improve <name> / improve <path>	开发（现有技能）	/skill-creator improve design
plan <name> / plan <path>	规划（现有技能）	/skill-creator plan review
plan --all / plan repo	规划（整个仓库）	/skill-creator plan --all
audit <name>	审计	/skill-creator audit review
audit <name> --security	安全审计	/skill-creator audit review --security
audit --all	全部审计	/skill-creator audit --all
eval <name>	评估	/skill-creator eval review
benchmark <name>	基准测试	/skill-creator benchmark review
compare <old> <new>	比较	/skill-creator compare review-v1 review-v2
optimize-description <name>	优化描述	/skill-creator optimize-description review
dashboard	仪表板	/skill-creator dashboard
package <name> / package --all	打包	/skill-creator package wargame
example-blocks <name>	示例区块	/skill-creator example-blocks review
自然语言描述技能构想	自动：开发（新建）	"tool that audits Python type safety"
技能名称 + 修改动词	自动：开发（现有技能）	"refactor the wargame skill"
SKILL.md 文件路径	自动：开发（现有技能）	skills/wargame/SKILL.md
"MCP server" / "agent" / "run"	拒绝并引导	—
空	技能库	/skill-creator

自动检测启发式规则

如果未提供明确的模式关键词：

1. 以 SKILL.md 结尾的路径或 skills/ 下的目录 → 开发（现有技能）
2. 现有技能名称 + 修改动词（improve、refactor、enhance、update、fix、rewrite、optimize、polish、revise、change）→ 开发（现有技能）
3. 参数中包含 --from <source> → 开发（基于范例新建）
4. 包含 "benchmark"、"A/B"、"with skill"、"without skill"、"old skill"、"new skill" → 基准测试或比较
5. 包含 "trigger"、"false positive"、"false negative"、"description fires" → 优化描述
6. 包含 "security"、"supply chain"、"malicious"、"unsafe"、"permission"、"hook" → 安全审计
7. 新能力描述（"I want to build..."、"tool that..."、"skill for..."）→ 开发（新建）——推导名称，并在搭建初始结构前确认
8. 包含 "MCP server"、"agent"、"run" → 礼貌拒绝并引导
9. 含义不明确 → 询问用户希望使用哪种模式

快速开始

uv run python skills/skill-creator/scripts/scaffold_skill.py <name>  # Scaffold from template
uv run python scripts/check.py                                        # Validate from skill directory
uv run python skills/skill-creator/scripts/audit.py skills/<name>/    # Score quality
uv run python skills/skill-creator/scripts/package.py skills/<name>/ --dry-run  # Portability check

技能开发

用于创建新技能和改进现有技能的统一流程。加载 references/workflow.md 查看完整流程。

步骤	新技能	现有技能
1. 理解	定义使用场景、范围和模式	审查并理解用户意图
2. 规划	结构、描述、frontmatter	差距分析 + 改进计划（审批关卡）
3. 搭建	scaffold_skill.py <name>	跳过
4. 构建	编写/编辑正文、参考资料、脚本、模板和评估项	相同
5. 验证	scripts/check.py + audit.py	相同
6. 迭代	测试、识别问题、返回第 4 步	相同

扩展策略

采用经过验证的最大独立性，而非最多的 Agent 数量。加载 references/orchestration-graph.md 查看完整的图契约。

范围	策略	并行度
小型	单技能编辑：内联顺序编辑 + 验证	仅负责人
中型	单技能多层面编辑：先稳定正文契约，再按文件分配参考资料/评估项/脚本	2-5 条互不重叠的工作线
大型	技能集群或全仓库计划：盘点、排序、按技能或层面拆分，并增加评审工作线	每个分配的分片对应一个工作者
大型	公开工作流/架构/工具变更：先使用 OpenSpec，再让工作者按明确的依赖关系开展工作	规范、实现、验证、文档维护工作线
大型	行为评估/基准测试计划：先设置静态关卡，再启用评估运行器/报告工作线	触发、输出、安全、报告、评审工作线

派发前，每条工作线都必须明确输入、负责的路径、输出产物、验证命令和核算状态。除非存在明确的锁定/仲裁协议，否则同文件编辑、生成的文档、钩子、打包语义和架构决策都必须串行处理。

全仓库 / 多技能规划

使用 plan <name> 制定现有技能的改进计划（不进行编辑）；使用 plan --all 或 plan repo 执行全仓库排序规划。

规划输出必须包含：

1. 基线审计摘要
2. 价值最高的发现
3. 明确的目标文件
4. 预期分数影响
5. 编辑前的审批关卡

进行全仓库规划时，生成排序后的队列，并为每个纳入计划的技能或技能集群分别制定独立的改进计划。用户批准计划前，不得编辑任何技能。

生成独立改进计划材料时，加载 references/refinement-plan.md。

审计

使用确定性分析 + AI 审查为技能评分。加载 references/audit-guide.md。

安全审计

将技能作为可执行的供应链资产进行审计。加载 references/security-governance.md。

必须输出：

1. 安全攻击面清单
2. 来源/接收端威胁模型
3. 权限状况
4. 钩子/脚本/模板/参考资料发现
5. 对抗性评估建议
6. 风险级别：low、medium、high 或 blocked

安全审计为只读。不得安装第三方技能、运行不可信脚本或修改受审计的技能。

审计全部

对仓库中的所有技能进行比较排名。加载 references/audit-guide.md § Audit All。

评估 / 基准测试 / 比较 / 优化描述

行为验证可补充静态审计评分。加载 references/evidence-and-benchmarking.md。

模式	用途
评估	审查或编写触发、输出、回归、安全性和可移植性评估用例
基准测试	规划或运行可选的技能启用与未启用状态测量
比较	规划或运行可选的改进前后技能测量
优化描述	测试触发查询和相近但不匹配的负向查询，再根据证据修改描述

除非用户明确批准执行实时评估并指定目标工作区，否则默认只读规划。将行为运行产物存储在已提交的 skills/ 源文件之外。

仪表板

呈现可视化创作流程监视器或审计质量仪表板。加载 references/audit-guide.md § Dashboard。

根据数据自动检测模式：phases 字段 → 流程监视器；skills 数组 → 审计概览。

图库（空参数）

展示技能清单、评分和可用操作。 运行 uv run python scripts/audit.py --all --format table，显示结果并提供模式菜单。

打包

将技能打包成便于导入 Claude Code Desktop 的可移植 ZIP 文件。加载 references/packaging-guide.md，了解 ZIP 结构、清单架构、可移植性检查和跨 Agent 兼容性。

uv run python skills/skill-creator/scripts/package.py skills/<name>/ --dry-run  # Check before emitting a ZIP
uv run python skills/skill-creator/scripts/package.py skills/<name>/            # Single skill → <name>-v<version>.skill.zip

示例区块生成器

根据现有调度表生成空示例 / 帮助图库示例条目。

uv run python skills/skill-creator/scripts/generate_example_blocks.py <name>           # Preview block
uv run python skills/skill-creator/scripts/generate_example_blocks.py <name> --apply # Append when missing

在调度表稳定后、发布技能前使用此模式。请勿追加重复的 ## Example Blocks 区段。

运行时钩子投影

此可移植技能源文件不嵌入技能范围内的 hooks frontmatter。仓库管理的钩子策略位于 config/hook-registry.json 中，并通过仓库同步 / 渲染工作流投影到受支持的运行环境设置中。

对此技能进行运行时投影的钩子强制机制应保留以下行为：

• 编辑 SKILL.md 时触发 validate_skill.py
• 编辑 evals/*.json 时触发 validate_evals.py
• 编辑包含钩子的技能 / 设置时触发 validate_hooks.py
• Stop 钩子会在退出前验证已修改的技能定义、评估和钩子内容
• 如果钩子输入包含 stop_hook_active: true，Stop 钩子会立即退出，以避免递归循环

打包后的技能不得依赖 uv run python scripts/verify.py ... 等仓库根目录命令。请将可执行钩子命令保留在运行时专用配置中，而非可移植技能 frontmatter 中。

状态管理

创作进度保存在 ~/.{gemini|copilot|codex|claude}/skill-progress/<name>.json。通过 scripts/progress.py 读写。会在会话重启后保留。使用 --state-dir 覆盖默认位置。

参考文件索引

文件	内容	阅读时机
references/workflow.md	新建和现有技能的统一技能生命周期流程	开发（新建）、开发（现有）、评估、基准测试
references/refinement-plan.md	面向现有技能和整个仓库规划输出的独立优化计划规范	规划（现有）、规划（整个仓库）
references/audit-guide.md	审计流程、全部审计、仪表板渲染、图库、评级门槛	审计、全部审计、仪表板、图库
references/proven-patterns.md	14 种结构模式及仓库技能中的示例	第 4 步（构建）、差距分析
references/best-practices.md	Anthropic 指南 + superpowers 方法论 + 跨 Agent 意识	第 2 步（规划）、第 4 步（构建）、描述编写
references/frontmatter-spec.md	完整字段目录、调用矩阵、决策树	第 3 步（搭建）、frontmatter 配置
references/packaging-guide.md	ZIP 结构、清单架构、可移植性检查、导入说明	打包
references/evaluation-rubric.md	13 个加权评分维度（标准化为 100 分）、评级门槛、压力测试	审计（压力测试）、评分目标
references/evidence-and-benchmarking.md	生命周期资料包、行为评估、基准测试产物、触发器优化	评估、基准测试、比较、优化描述
references/security-governance.md	威胁模型、第三方接入、权限策略、钩子/脚本安全	安全审计、第 2 步（规划）、打包
references/runtime-compatibility.md	可移植和运行时专用字段、安装路径、优雅降级	第 3 步（搭建）、打包、安全审计
references/orchestration-graph.md	并行通道图、所有权、核算、锁、评审层	扩展策略、整个仓库的计划

请根据上方“阅读时机”列阅读参考文件。不要依赖记忆或先前对其内容的了解。

核心原则

简洁是尊重——上下文窗口由所有内容共享。每一行都会占用 Agent 的工作记忆。每一行都要物有所值，否则就删掉。

渐进式披露——Frontmatter 用于发现（约 100 个 token），正文用于调度（少于 5K 个 token），参考资料用于深入了解（按需），脚本/模板用于执行（绝不加载）。

自我示范——此技能遵循它所教授的每一种模式。如有疑问，请参考 skill-creator 的应用方式。

验证约定

在宣布变更完成前，从此技能目录运行：

uv run python scripts/check.py

完成标准：

1. uv run python scripts/check.py 以状态码 0 退出。
2. 此技能目录下不再存在可移植 CLI 违规项。

关键规则

1. 声明任何技能完成前，先在目标技能目录中运行 uv run python scripts/check.py
2. 更改评估项后、声明技能完成前，重新运行 uv run python scripts/check.py
3. 每次对 SKILL.md 进行重大更改后，运行 uv run python scripts/audit.py
4. 创建技能时必须包含分发表——它是路由契约
5. 创建分发表时必须包含空参数处理器——未路由的输入就是一个错误
6. 每个参考文件都必须出现在参考文件索引中——孤立的参考文件不可见
7. 每个已编入索引的参考文件都必须存在于磁盘上——虚构的参考文件会导致 Agent 出错
8. 正文必须少于 500 行（不含 frontmatter）——将详细内容移至参考文件
9. 描述必须包含“Use when”触发短语和“NOT for”排除项
10. 名称必须使用 kebab-case，长度为 2-64 个字符，不得包含连续连字符或保留词
11. 脚本使用 argparse + JSON 输出到 stdout——不得使用自定义输出格式
12. 模板必须是无外部依赖的独立 HTML
13. 不要直接调用特定于仓库的文档生成器——应委托给 docs-steward
14. 不要创建 Agent 或 MCP 服务——应妥善拒绝并引导用户采用其他方式
15. 改进现有技能时，必须先提出改进计划并获得用户批准，然后才能实施更改
16. Audit 模式为只读——绝不修改正在审计的技能
17. 分发行为或模式发生变化时，更新评估项——过时的评估项会造成隐蔽错误
18. plan <name> 和 plan --all 是只读规划模式——规划期间绝不编辑
19. 仓库范围或涉及多个技能的请求，必须先提供按优先级排序的计划和独立的改进计划输出，然后才能开始实施
20. 运行时投射的 Stop 钩子必须包含 stop_hook_active 守卫——递归钩子循环属于实现错误
21. 新技能必须以真实工作流证据为依据；从通用最佳实践生成的技能初始状态为 needs-evidence
22. 声称行为有所改善前，必须将有意义的更改与 without_skill 或 old_skill 进行基准测试
23. 即使静态质量评分为 A，安全治理方面的发现仍可阻止发布
24. 每个使用脚本、钩子、工具、网络、凭据或写入操作的技能，都必须明确选择权限策略
25. 更改公开评估模式、验证行为、钩子策略、打包语义或生成文档工作流前，使用 OpenSpec
26. 在 Plan、Audit 或 Security Audit 模式下，不得运行实时安装、实时行为评估、启动浏览器或注入命令文件

规范术语（全文必须严格使用以下术语）：

• 模式：“Develop (new)”、“Develop (existing)”、“Plan (existing)”、“Plan (repo-wide)”、“Audit”、“Security Audit”、“Audit All”、“Eval”、“Benchmark”、“Compare”、“Optimize Description”、“Dashboard”、“Package”、“Gallery”
• 步骤（开发）：“Understand”、“Plan”、“Scaffold”、“Build”、“Validate”、“Iterate”
• 评级标准：“A”（90-100）、“B”（75-89）、“C”（60-74）、“D”（40-59）、“F”（<40）
• 模式：“dispatch-table”、“reference-file-index”、“critical-rules”、“canonical-vocabulary”、“scope-boundaries”、“classification-gating”、“scaling-strategy”、“state-management”、“scripts”、“templates”、“hooks”、“progressive-disclosure”、“body-substitutions”、“stop-hooks”
• 审计维度：“frontmatter”、“description”、“dispatch-table”、“body-structure”、“pattern-coverage”、“reference-quality”、“critical-rules”、“script-quality”、“portability”、“conciseness”、“canonical-vocabulary”、“evaluation-coverage”、“validation-contract”、“security-governance”