Skill Generation Workbench

skill生成器 / Skill Generator

Overview

将模糊的“帮我做一个 Skill”请求整理成可执行的 Skill 蓝图，并生成一个可验证、可维护、不会默认安装或发布的 Skill 包。写入文件前先查找可复用能力，避免重复造 Skill。保持 Skill 是能力与工作流，不把人格、身份或专家灵魂写进 SKILL.md。

Operating Modes

识别用户要做的模式：

• create：从想法、流程、文档、截图或外部专家卡片创建新 Skill。
• upgrade：分析并改进已有 Skill 的触发条件、流程、资源或验证。
• convert：把已有 agent、prompt 或专家卡片转成 Skill；剥离 persona，只保留能力和工作流。
• review：只审查 Skill 的触发、结构、重复能力、安全和验证，不修改文件，除非用户要求修复。

Intake

当需求已经包含目标能力、触发方式、输入输出和目标位置时，直接进入设计；不要为了形式重复提问。信息不足且会影响实现时，一次只问最少的阻塞问题：

1. 这个 Skill 解决什么任务，用户会用哪些自然语言请求触发它？至少收集 2 个真实例句。
2. 它接收哪些输入，应该产出什么结果或文件？哪些结果算完成？
3. 目标位置是当前仓库、某个项目，还是用户的 Skill 目录？是否只生成仓库包，不安装？
4. 是否会执行提交、推送、安装、删除、部署或其他外部副作用？没有明确授权时一律只生成和验证。

保留用户的原始术语和约束。不要凭空补充组织规则、私有 API、凭据、远程地址或“自动发布”行为。

Workflow

0. Capability Discovery Before Writing (MANDATORY)

For create, upgrade, and convert modes, complete this discovery phase before creating, editing, or scaffolding any package file. Review-only mode may skip it when no files will be written. The order is mandatory: find-skills first, then SkillHub.

1. Build a focused query from the domain, user task, stack, inputs, outputs, and risk terms. Keep it short enough to search, for example react form validation, harmonyos app release, or api contract testing.

2. Use the find-skills discovery workflow first:

   npx --yes skills find "<domain> <task> <stack>"
   

   Read the candidate name, repository, skills.sh URL, install count, and source. This is search only; do not run npx skills add or install a candidate.

3. Query SkillHub second, using the local CLI when available:

   skillhub --skip-self-upgrade search "<domain> <task> <stack>" --json --search-limit 20
   

   The CLI searches https://skillhub.cn/. If the CLI is unavailable, read the public search API at https://api.skillhub.cn/api/v1/search with q and limit; do not infer results from the home page.

4. Compare both result sets with the repository registries and installed local roots. For every serious candidate, inspect its visible SKILL.md or package metadata when reachable, and record name, source, capability overlap, input/output compatibility, version or install evidence, and verification status. Search metadata alone is not proof that a Skill is usable.

5. Make one explicit decision before writing:

   • reuse an existing local or verified external capability when it already owns the task;
   • upgrade the existing package when the request is an extension of its scope;
   • convert an external package when the user supplied a visible expert/prompt package;
   • create a new package only when no verified candidate owns the required workflow or the boundary is materially different.

6. Record the query, both source results, rejected candidates, and the reuse/upgrade/convert/create decision in the blueprint. A failed or unavailable search must be reported as an evidence gap, not silently treated as “no matching Skill”.

1. Inspect

先完成第 0 阶段的能力发现，再确认当前工作区和目标目录，检查是否存在同名或功能重叠的 Skill：

• 查看 git status --short --branch -uall，不要覆盖用户已有改动。
• 用 rg 搜索现有 SKILL.md 的 name、描述和触发词；在 tiny-agents 中优先查看 indexes/skill-registry.md，若要看本地扫描库存再看 indexes/agent-skill-index.md。
• 将第 0 阶段的 find-skills 和 SkillHub 结果与本地 registry 一起比较，不因远端搜索结果存在就覆盖本地 Skill。
• 若输入来自截图或外部专家卡片，只把可见的名称、摘要、标签和流程当作来源；缺失的隐藏 prompt 不得臆造。
• 选择短的、动词导向的 hyphen-case 名称；已存在相同能力时优先升级或复用，而不是创建重复包。

2. Design The Blueprint

在写文件前形成一份内部蓝图，至少包含：

• name：不超过 64 个字符，只用小写字母、数字和连字符。
• description：明确能力和触发场景；把所有触发条件放在 frontmatter 中。
• inputs / outputs：输入材料、交付物、成功判定和不确定性处理。
• workflow：按顺序列出发现、执行、验证和交付步骤；为高风险操作设置确认点。
• resources：只有反复需要或适合确定性执行的内容才放入 scripts/、references/ 或 assets/。
• validation：列出结构校验、脚本测试、项目测试和安全扫描。

把长篇领域知识放入一层 references/ 文件，并在 SKILL.md 中说明何时读取。不要创建 README、安装指南、变更日志或仅用于叙述的附属文件。

3. Scaffold

创建新包时，使用本 Skill 的脚本生成稳定骨架：

python3 scripts/scaffold_skill.py <skill-name> \
  --path <parent-directory> \
  --description "<what it does and when to use it>" \
  --resources references

脚本会拒绝覆盖已有目录，并生成 SKILL.md、agents/openai.yaml、安全的 source.json 和请求的资源目录。它只生成骨架，不会替代具体能力内容；随后补全 SKILL.md，并删除未使用的资源目录。

更新已有 Skill 时直接编辑现有文件，保留有效的来源元数据和用户改动；不要重新初始化或整包覆盖。

4. Implement

把蓝图转成目标包：

• SKILL.md 只写另一个 Codex 实例执行任务所需的非显然规则，使用祈使式步骤和具体决策点。
• frontmatter 只包含允许的 name、description、metadata 等字段；默认不要增加工具依赖。
• agents/openai.yaml 的 display_name、short_description 和 default_prompt 必须与 Skill 一致，default_prompt 必须显式包含 $skill-name。
• 脚本必须使用参数而不是硬编码本机路径；任何写入、网络、安装、提交或推送动作都要有清晰的边界和失败处理。
• source.json 只能写公开的相对来源标识，例如 repo-local/generated 或 ~/.codex/...，不得写本机绝对路径、token、凭据或运行缓存。
• 如果是外部专家卡片转换，声明是卡片或可见资料派生；不要声称拥有未提供的内部专家详情。

5. Validate

按风险执行验证，至少运行：

python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_validate.py" <skill-directory>
python3 -m json.tool <skill-directory>/agents/openai.yaml
git diff --check

注意：agents/openai.yaml 是 YAML，不是 JSON；如果 json.tool 不适用，使用仓库已有 YAML 解析器或针对 YAML 的结构检查，并验证关键字段。脚本资源必须实际运行，新增 Python 测试必须纳入 python3 -m unittest。

发布前扫描本机路径和敏感信息，确认没有机器专属 home 路径、临时目录、私有运行目录、token、密钥或临时报告进入 Skill。检查 git status --short -uall，确认只有预期文件变化。

6. Deliver

交付时说明：生成或更新的绝对文件路径、Skill 名称、典型触发例句、资源文件、验证命令和结果。把未解决的假设与风险单独列出。

默认只生成并验证仓库 Skill 包。安装到 ~/.codex/skills、提交、推送、部署或删除旧 Skill 都必须等用户明确授权。

Output Contract

一个完成的生成任务至少交付：

1. 可触发的 SKILL.md，frontmatter 完整且没有 TODO 占位内容。
2. 与内容一致的 agents/openai.yaml。
3. 必要时提供引用文件或确定性脚本；没有实际用途的目录不保留。
4. 能力发现记录：查询词、find-skills 结果、SkillHub 结果、候选验证、拒绝原因和最终复用/升级/转换/新建决策。
5. 结构校验、安全扫描和相关测试的真实结果。

详细字段、蓝图和检查表见：

• references/guide.md
• references/skill-contract.md
• references/generation-checklist.md