create-skill

创建技能

先用一份小巧、可观察的契约搭建技能，然后将其符号链接到 .claude/skills/，以便 Claude Code 发现 它。将不变的工作流指导保留在 SKILL.md 中；将确定性的操作细节和条件性内容移至脚本和 参考资料中。

模型优化

针对 GPT-5.6 和 Claude Fable 5 优化每项新技能及其内容。以下摘要仅作提醒，不能替代实时指南。在设计或编写复杂、长时间运行、多工具或编排密集型技能之前，请阅读两份指南，因为其中的建议可能会更新。

• GPT-5.6 提示指导：优先使用精简、以结果为先的提示，明确目标、成功和停止条件、约束、证据、权限边界、工具路由、输出形式和验证方式。移除冗余的脚手架，并在具有代表性的任务上评估更改。
• Claude Fable 5 提示指导： 使用简洁的指令说明意图和边界；避免过度规定和范围蔓延；审慎调整投入程度；确保进度声明有工具证据支撑；并在需要时明确说明长期运行任务的验证方式和脚手架。

参数

• skill-name（必填）：kebab-case 格式的名称（例如，my-skill）。如果缺失或无效，则停止。

拒绝 --global、显式目标路径及其他范围覆盖选项。调用时的工作目录是唯一受支持的范围。

解析路径

将 <scope> 设为调用技能时所在的工作目录。在 <scope>/.agents/skills/<name>/ 下创建源文件，并在 <scope>/.claude/skills/<name> 创建 Claude Code 符号链接。从嵌套项目或工作区中调用时，不要将范围重定向到仓库根目录。切勿在 ~/.agents、~/.claude、~/.codex 或其他全局安装目录下创建或修改技能。

符号链接目标始终是相对路径 ../../.agents/skills/<name>。

技能布局

<name>/
├── SKILL.md       # Required: frontmatter + lean workflow (aim for <500 lines)
├── agents/
│   └── openai.yaml # Required: Codex metadata; disables implicit invocation
├── scripts/       # Optional: helper code (prefer TypeScript via bun run; Python via uv)
├── references/    # Optional: long-form docs loaded on demand
└── assets/        # Optional: templates / fonts / images used in OUTPUT (never loaded into context)

Agent 通过渐进式披露分三个阶段加载技能：

1. 发现——启动时仅显示 name 和 description。在 description 中优先写明触发条件。
2. 激活——任务匹配后，读取完整的 SKILL.md 正文。
3. 执行——运行 scripts/ 时不会将其读入上下文；只有在 SKILL.md 中明确链接的 references/ 才会被读取。

让 SKILL.md 聚焦于工作流。将大量内容移至 scripts/（确定性逻辑）或 references/（文档）。

编写契约

选择布局之前，先将内容分为：

• 不变量：每次有效执行都必须遵守的内容。
• 首选默认值：明确的用户意图或仓库证据可以覆盖的内容。
• 条件示例和参考资料：仅在对应分支启用时加载的内容。

定义预期结果、权限边界、停止条件和完成证据。如果有多种安全路径都能满足同一契约，不要规定完全相同的执行路径。对于面向用户的工作流，还要定义哪些启动、进度、决策、阻塞和完成事件需要发送消息，以及每种消息最精简且有用的形式。

何时拆分内容

在以下情况下使用 scripts/

• 每次调用时都需要重写相同的代码（例如，旋转 PDF、转换 JSON、封装 curl）。
• 确定性比灵活性更重要（解析、验证、代码生成、幂等设置）。
• Shell 管道超过约 5 行，或需要真正的错误处理。
• 长段 here-doc 反复出现在 SKILL.md 中。

脚本可以节省令牌：Agent 调用脚本时无需读取脚本内容。在 SKILL.md 中记录 CLI 签名，并将实现放在 scripts/ 中。

优先使用 scripts/*.ts，并通过 bun run scripts/<name>.ts 运行，除非有充分理由认为 TypeScript 不适合该辅助工具。Python 也是处理数据、文本和文件的好选择；运行 Python 辅助工具时请使用 uv run scripts/<name>.py，不要直接使用 python 或 python3。

在以下情况下使用 references/

• 某个主题的说明、示例或架构超过约 100 行。
• 内容只在特定条件下相关（取决于变体、框架或领域）——拆分文件可以避免无关上下文。
• 详细的 API 接口、数据库架构、策略或大型模板会占据 SKILL.md 的大部分篇幅。
• 只有在某个分支中才需要长篇说明。

经验法则：

• 只分一层——从 SKILL.md 直接链接到 references/placeholder.md，不要在参考文件之间互相引用。
• 文件超过 100 行：在顶部添加目录。
• 文件超过 10k 个单词：在 SKILL.md 中记录 grep 模式，让 Agent 无需通读全文就能定位章节。
• 不重复——每项事实只放在 SKILL.md 或某个参考文件中，不能两处都有。让各项技能保持自包含，不要在独立安装的技能之间共享参考文件。
• 对于每份参考文件，都要在 SKILL.md 中用一行说明_何时_阅读该文件。

参考文件的组织模式

模式 A — 高层指南 + 主题参考文件

SKILL.md
references/
├── forms.md
├── api.md
└── examples.md

SKILL.md 讲解推荐流程；参考文件包含深入内容。

模式 B — 按领域或变体拆分

SKILL.md           # workflow + selection logic
references/
├── aws.md
├── gcp.md
└── azure.md

Agent 只读取用户选择的变体——无关的提供商不会进入上下文。

模式 C — 条件性细节

在 SKILL.md 中写入基本情况，并链接到包含边缘情况的进阶文件（tracked-changes.md、ooxml.md 等）。

不要添加到技能中

• README.md、INSTALLATION.md、CHANGELOG.md、QUICK_REFERENCE.md——这些都无关。
• 关于技能编写方式的说明、测试日志、临时文件。
• Agent 在运行时不会用到的任何内容。

工作流

1. 获取 Agent Skills 文档

编写 frontmatter 或内容前，务必先获取最新规范：

• https://agentskills.io

使用 WebFetch 确认当前的 frontmatter 架构、命名规则和渐进式披露约定。不要猜测——规范会不断演进。

2. 验证

• 拒绝不符合 kebab-case 命名规则或与解析后的路径中现有技能冲突的名称。
• 确认 <scope> 是调用时的工作目录，且不是用户主目录级或全局技能目录。
• 如果 <scope>/.agents/skills/<name>/ 或 <scope>/.claude/skills/<name> 已存在，则停止。

3. 阅读编写指南并定义约定和布局

在选择约定或布局前，先阅读 references/writing-great-skills.md。该指南定义了可预测性的调节手段，以及采用散文还是代码或架构的判断标准。

然后定义可观察结果、不变量、首选默认值、权威来源、路由、停止条件和完成证据。确定各部分的归属：

• 工作流会调用辅助代码吗？→ 优先使用通过 bun run 运行的 scripts/<name>.ts；如果 Python 更合适，则通过 uv run 使用 scripts/<name>.py。
• 供机器使用且有实际验证器的架构？→ 将两者一并打包，并说明验证方式。
• 仅供参考的架构文档、较长示例、变体指南或领域知识？→ references/<topic>.md
• 技能会写入用户输出的模板或文件？→ assets/
• 以上都不是？→ 只提交 SKILL.md。

先草拟目录树，再只创建布局实际需要的子目录。

4. 创建技能

mkdir -p "<scope>/.agents/skills/<name>/agents"
# Add only the subdirectories the layout calls for:
# mkdir -p "<scope>/.agents/skills/<name>/scripts"
# mkdir -p "<scope>/.agents/skills/<name>/references"

编写 <scope>/.agents/skills/<name>/SKILL.md，其中包含：

• 按字母顺序排列的 Frontmatter，并将 description 放在最后。发现阶段只能看到 description，因此应在其中优先写明触发短语，而不是放在正文中。
• 简短的 # Title。
• 用一句话概述技能的作用。
• 设置 disable-model-invocation 和 user-invocable 字段以控制 Claude 的行为。只有在有意依赖 Claude 默认值时才省略：disable-model-invocation: false、user-invocable: true。
• ## Arguments（如果有）和精简的命令式工作流。只有顺序重要时才使用固定步骤；否则说明约定，并让仓库证据指导执行。
• 明确链接到工作流可能需要的每个 references/ 文件，并用一句话说明何时阅读。
• 为任何打包的脚本提供 CLI 签名，包括运行时命令（bun run scripts/<name>.ts 或 uv run scripts/<name>.py），以便 Agent 无需阅读脚本即可调用。

尽量将 SKILL.md 控制在 500 行以内。如果某个部分超过约 50 行且不属于核心工作流，请将其移至 references/ 并添加链接。

编写 <scope>/.agents/skills/<name>/agents/openai.yaml，其中包含：

policy:
  allow_implicit_invocation: true

将 allow_implicit_invocation 设为 SKILL.md 中 disable-model-invocation 的相反值。如果之后添加 Codex UI 元数据或 MCP/工具依赖项，请将其合并到同一文件中，并保持策略不变。

5. 创建 Claude Code 符号链接

始终创建相对符号链接，以便 Claude Code 能从自身的发现路径找到该技能：

mkdir -p "<scope>/.claude/skills"
ln -s "../../.agents/skills/<name>" "<scope>/.claude/skills/<name>"

6. 验证

• 补丁工具会以 0644 模式创建文件。首次运行验证前，对 scripts/ 和 tests/ 下的每个可执行文件执行 chmod 755（脚手架生成的测试首次运行时若因 Permission denied (os error 13) 而失败，原因就在于此）。
• test -f "<scope>/.agents/skills/<name>/SKILL.md"
• test -f "<scope>/.agents/skills/<name>/agents/openai.yaml"
• readlink "<scope>/.claude/skills/<name>" 应解析到源目录。
• 对 scripts/* 和 tests/* 中的每个可执行文件运行 test -x，确保遗漏 chmod 时立即报错，而不是之后才出现权限错误。
• 最后输出 ### 🧩 Skill created: <name>、已创建路径的目录树，以及包含精确检查项的 ### ✅ Verified。链接到绝对源路径和符号链接路径。
• 主动提出提交新技能。如果宿主项目的长期说明要求提交提示词，则无需再次询问，直接提交。

注意事项

• Frontmatter 规则：按字母顺序排列字段，但始终将 description 放在最后。
• Codex 会在加载技能前将 SKILL.md frontmatter 解析为 YAML。避免在标量值中使用未加引号的冒号加空格，例如在 description 中写 Triggers: "foo"；可以省略标签，或将整个值加引号。
• “适用时机”信息应放在 description 中（发现阶段），而非正文中（仅激活阶段）。
• SKILL.md 全文使用祈使式／不定式。
• SKILL.md 中的所有路径（例如 references/placeholder.md、scripts/example.sh）均相对于技能目录。
• 每项新技能都必须包含 agents/openai.yaml，其中的 policy.allow_implicit_invocation 应根据 SKILL.md 推导，不能反过来。
• 优先使用通过 bun run 运行的 TypeScript 辅助脚本；使用 Python 时通过 uv run，切勿直接运行 python 或 python3。
• 技能中的 Bash 脚本必须兼容 Bash 3.2（/bin/bash），因为 Codex 默认使用内置 Bash。
• 除非技能自身的输出约定另有要求，否则辅助脚本的标准输出、命令、路径、frontmatter 和生成的技能内容都应保持原样，不添加装饰。