name: "skill_creator"
description: "Create or update a workspace skill: its description, structure, instructions, and supporting files."
metadata: { "includeInPrompt": true }

Skill Creator / 技能创建器

Purpose / 目的

Create or update a skill that is easy to trigger, concise to load, and backed by references or helper code only when they materially improve reliability.

创建或更新一个易于触发、加载精简的技能；只有当参考资料或辅助代码能实质提升可靠性时才引入它们。

Workflow / 工作流程

1. Clarify the capability, likely trigger phrases, and the target workspace skill path (~/workspace/skills/<name>/).
   明确能力本身、可能的触发短语，以及目标工作区技能路径（~/workspace/skills/<name>/）。
2. Choose a narrow scope. Prefer one clear job per skill. Split unrelated jobs into separate skills.
   选择窄范围。每个技能最好只做一件清晰的事。把不相关的工作拆成独立技能。
3. Plan the file layout before editing:
   编辑之前先规划文件布局：
   • Keep only the operational core in SKILL.md.
     SKILL.md 中只保留操作性核心内容。
   • Put bulky docs, examples, schemas, or tutorials in references/.
     把大篇幅文档、示例、模式（schema）或教程放进 references/。
   • Put templates or output assets in assets/ only when the final output uses them.
     只有当最终输出会用到模板或输出资产时，才把它们放进 assets/。
   • Prefer helper binaries or checked-in helpers in bin/ over prompt-side protocol or auth instructions.
     优先使用 bin/ 中的辅助二进制或入库的辅助工具，而不是在提示词侧编写协议或认证说明。
4. Draft or update frontmatter. Required: name, description.
   起草或更新 frontmatter。必填项：name、description。
5. Draft or update the body:
   起草或更新正文：
   • Tool-backed skills: Purpose, Tooling, Auth, Operating Rules
     工具支撑型技能：Purpose、Tooling、Auth、Operating Rules
   • Workflow-only skills: Purpose, Workflow, Output Contract, Operating Rules
     纯工作流技能：Purpose、Workflow、Output Contract、Operating Rules
   • Keep examples short and directly executable
     示例保持简短且可直接执行
6. Trim aggressively. Remove long API docs, schema dumps, and setup essays from SKILL.md. If a detail is useful but not needed on every trigger, move it to references/.
   大刀阔斧地精简。把冗长的 API 文档、模式倾倒和安装长文从 SKILL.md 中移除。某个细节有用但不是每次触发都需要时，移到 references/。
7. Sanity-check the result:
   对结果做合理性检查：
   • The description should say what the skill does and when it should trigger.
     description 应说明技能做什么、何时应触发。
   • The body should tell the model what to do next, not explain the whole domain.
     正文应告诉模型下一步做什么，而不是解释整个领域。
   • Commands, paths, and auth flows must match real repo/runtime behavior.
     命令、路径和认证流程必须与真实的仓库/运行时行为一致。

Connector Credentials / 连接器凭据

Collecting a provider's credential is credentials.request_api_access, not a file you write. It is a sequence with external dependencies, and the tool enforces the order and refuses the schemes Muse cannot express.

收集提供商凭据使用的是 credentials.request_api_access，而不是你自己写一个文件。它是一个带外部依赖的序列，工具会强制执行顺序，并拒绝 Muse 无法表达的方案。

Using that credential is authored here, but do not start from an empty file. Once the connector is connected, scaffold it:

使用该凭据的部分在这里编写，但不要从空文件起步。连接器连上之后，先用脚手架生成：

/opt/hatch/skills/skill-creator/bin/scaffold-connector-skill --provider <provider>

It reads the connector from authd and writes a SKILL.md whose Tooling and Auth sections already carry the credential mechanics: which helper to import, where the value goes, which hosts are allowed, and how to replace a credential that stops working. Write the CLIs into the bin/ it creates, and leave those two sections as generated.

它会从 authd 读取连接器并生成 SKILL.md，其 Tooling 和 Auth 两节已带有凭据机制：导入哪个辅助工具、值放在哪里、允许哪些主机，以及如何更换失效的凭据。把 CLI 写进它创建的 bin/ 中，这两节保持生成时的原样。

A 401 or 403 from the provider is a question about the request before it is a question about the key. Check that the credential was attached at all: a request built without the helper carries nothing, and that looks exactly like a wrong or under-scoped token.

提供商返回 401 或 403 时，先怀疑请求本身，再怀疑密钥。先检查凭据是否根本没有附上：不经辅助工具构建的请求什么都不会携带，其表现与错误或权限不足的令牌一模一样。

【评论】这条排障次序（先查请求是否携带凭据、再查令牌是否有效）针对的是模型容易把所有 401/403 都归因于密钥错误的误判倾向。

Operating Rules / 操作规则

1. Preserve working commands and repo conventions; do not invent binaries, paths, or auth flows.
   保留可用的命令和仓库约定；不要凭空编造二进制、路径或认证流程。
2. Prefer minimal frontmatter and on-demand loading. Only add metadata the skill actually needs.
   frontmatter 从简，按需加载。只添加技能真正需要的元数据。
3. Give auth its own section instead of burying it in operating rules.
   认证单独成节，而不要埋在操作规则里。
4. Use existing setup/auth helpers when they exist. Do not tell the model to hand-write config files if a bundled helper already owns that flow.
   已有的安装/认证辅助工具要优先使用。如果内置辅助工具已经负责某个流程，就不要让模型手写配置文件。
5. Create references/ only when it materially shortens SKILL.md; avoid duplicating the same guidance in both places.
   只有当它能显著缩短 SKILL.md 时才创建 references/；避免在两处重复同一指导。
6. If you create or edit Python CLIs, compile them with python3 -m py_compile ~/workspace/skills/<skill-name>/bin/*.py before reporting success.
   如果创建或修改了 Python CLI，先执行 python3 -m py_compile ~/workspace/skills/<skill-name>/bin/*.py 编译通过后再报告成功。

Reference Guide / 参考指南

For naming rules, resource-splitting heuristics, templates, and a review checklist, read references/authoring_guide.md.

命名规则、资源拆分经验法则、模板和审查清单，请阅读 references/authoring_guide.md。