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: ```bash 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: ```bash 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 的脚本生成稳定骨架： ```bash 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 按风险执行验证，至少运行： ```bash 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/guide.md) - [references/skill-contract.md](references/skill-contract.md) - [references/generation-checklist.md](references/generation-checklist.md)