Codex Skills 创建、打包与安装实战指南

导言

本文面向中级读者，系统讲解 Codex skills 的设计思路、目录组织、SKILL.md 编写规范、打包与安装流程，并给出可运行的 Python 示例，帮助你把一段可复用的工作流沉淀为可分发的技能包。

背景知识（可选）

在 Codex 中，skill 是一组“本地可执行的指令与资产”，核心入口是 SKILL.md。它定义了使用场景、步骤、引用资源与可选脚本。你可以把它理解为“面向特定任务的迷你操作手册 + 资产集合”，再辅以安装方式（本地拷贝、GitHub 仓库、curated 列表）实现分发。

核心内容

概念解释

1. Skill 的最小结构

一个最小可用 skill 只有一个 SKILL.md 文件：

my-skill/
  SKILL.md

但在实际项目中，建议按职责拆分：

my-skill/
  SKILL.md
  references/
    api.md
    troubleshooting.md
  scripts/
    package.py
  assets/
    cover.svg

• SKILL.md：必须。描述何时触发、执行流程与产出格式。
• references/：可选。放细节材料，避免 SKILL.md 过长。
• scripts/：可选。自动化脚本，减少重复劳动。
• assets/：可选。模板、插图、示例配置等。

2. 触发逻辑

一般遵循两类触发：

• 用户显式点名（例如“使用 tech-blog-writer”）。
• 需求与技能描述高度匹配（例如“写技术博客/教程”）。

因此，技能描述要精准且可检索：覆盖典型动词与产出类型，避免空泛。

3. 设计原则

• 最小必要：让使用者能在 3 分钟内理解流程。
• 渐进披露：SKILL.md 中只保留关键决策点，细节下沉到 references/。
• 可操作性：每一步都有可执行的输入/输出说明。
• 可移植性：避免硬编码路径；必要时使用占位符或变量名。

实践示例

下面给出一个“技能模板 + Python 打包脚本”的完整示例。

1) SKILL.md 模板

---
name: my-skill
description: 针对 XX 任务提供标准流程与模板，输出 XX 结果。
---

# My Skill

## Overview
一句话说明用途与适用场景。

## Workflow
1. 确认需求与范围
2. 选择模板或参考资料
3. 生成输出并做简单校验

## Output
- 产物 1
- 产物 2

## Notes
- 适配条件
- 已知限制

2) 目录与资产约定

my-skill/
  SKILL.md
  references/
    style.md
  assets/
    template.md
  scripts/
    package.py

3) Python 打包脚本（可运行）

该脚本会检查必备文件、生成 zip 包，并打印包含文件列表：

# scripts/package.py
from pathlib import Path
import zipfile

ROOT = Path(__file__).resolve().parents[1]
ZIP_PATH = ROOT.parent / f"{ROOT.name}.zip"

required = [ROOT / "SKILL.md"]
missing = [p for p in required if not p.exists()]
if missing:
    raise SystemExit(f"Missing required files: {missing}")

with zipfile.ZipFile(ZIP_PATH, "w", compression=zipfile.ZIP_DEFLATED) as zf:
    for path in ROOT.rglob("*"):
        if path.is_file():
            zf.write(path, path.relative_to(ROOT))

print(f"Wrote {ZIP_PATH}")
print("Included files:")
for name in zipfile.ZipFile(ZIP_PATH).namelist():
    print(" -", name)

运行方式：

python scripts/package.py

进阶内容（可选）

1) 拆分 references 的策略

当 SKILL.md 长度超过 2-3 屏，建议拆分：

• 通用规则 → references/style.md
• 版本差异 → references/compat.md
• 常见坑 → references/troubleshooting.md

SKILL.md 中只保留链接路径与选择策略。

2) 通过脚本生成模板

如果输出结构固定，可以提供脚本自动生成骨架：

# scripts/bootstrap.py
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
output = ROOT / "output"
output.mkdir(exist_ok=True)

(output / "README.md").write_text("# Output\n\nGenerated by bootstrap.\n", encoding="utf-8")
print("Created output/README.md")

打包与安装

1) 本地安装（复制目录）

将技能目录复制到 $CODEX_HOME/skills 下，并确保 SKILL.md 在一级目录：

$CODEX_HOME/skills/
  my-skill/
    SKILL.md

如果你的环境通过 AGENTS.md 注册可用技能，请同步更新该文件中的技能列表（名称、描述与路径）。

2) GitHub 仓库分发

• 把 my-skill/ 作为仓库根目录提交。
• 保持 SKILL.md 在根目录。
• 版本化：建议 tag，例如 v1.0.0。

3) 通过技能安装器（如有）

若你的环境提供 skill-installer，可以直接安装 curated 技能或指定 repo 路径。使用时通常需要提供：

• 仓库 URL 或本地路径
• 安装目标目录
• 目标版本/分支（可选）

常见问题/注意事项

1) 技能不生效

• 检查 SKILL.md 是否在技能目录根部。
• 描述是否包含清晰的触发关键词。
• AGENTS.md 是否更新并指向正确路径。

2) 指令过长导致阅读成本高

• 把步骤拆解为 3-7 个关键阶段。
• 把细节移到 references/。

3) 脚本不可运行

• 确保脚本路径与 SKILL.md 引用一致。
• 明确依赖项（Python 版本、第三方库）。
• 用最小例子演示输出。

4) 打包缺文件

• 在脚本里加入“必需文件检查”。
• 用 zipfile.namelist() 打印并人工复查。

总结

• Skill 的核心是 SKILL.md，描述“何时用、怎么用、产出什么”。
• 通过 references/、scripts/、assets/ 组织复杂内容，保持入口简洁。
• 打包建议自动化校验必需文件，并输出 zip 方便分发。
• 安装方式可选本地复制、GitHub 仓库或技能安装器。

进一步阅读/学习

• SKILL.md 范例与模板库
• 真实案例仓库（可作为最佳实践）