Skill Forge

Codex Skill 开发工坊

一站式 Skill 开发指南：从创意到发布的完整工作流。

工作流

1. 需求分析

与用户确认 Skill 的核心定位：

## Skill 定义卡
- **名称**：skill-name（小写连字符，≤64字符）
- **一句话描述**：做什么 + 何时触发（写入 description 字段）
- **目标用户**：谁会用这个 Skill
- **核心价值**：没有这个 Skill，用户需要重复做什么
- **触发场景**：用户说什么话时应该激活

description 写作要点（这是触发匹配的关键）：

• 包含「做什么」和「何时用」两个维度
• 列出具体的触发关键词和场景
• 避免过于宽泛导致误触发
• 示例对比：
  • ❌ "帮助用户处理代码" — 太宽泛
  • ✅ "为 Python/FastAPI 项目自动生成 OpenAPI 文档和客户端 SDK。当用户需要从 FastAPI 路由生成 API 文档、创建 TypeScript/Python 客户端、或配置 Swagger UI 时触发。"

2. 结构设计

确定 Skill 的文件结构：

## Skill 目录规划

skill-name/
├── SKILL.md              # 必须：核心指令
├── agents/
│   └── openai.yaml       # 推荐：UI 元数据
├── scripts/              # 可选：可执行脚本
│   └── helper.py
├── references/           # 可选：参考文档
│   └── api-docs.md
└── assets/               # 可选：模板/资源
    └── template.html

何时添加额外目录：

• scripts/：同一段代码被反复重写时（如 PDF 处理、文件转换）
• references/：领域知识超过 500 行、需按需加载时
• assets/：输出物需要模板文件时（HTML 骨架、PPT 模板）

3. 编写 SKILL.md

Frontmatter（YAML 头部）

---
name: my-skill-name
description: 精确的触发描述，包含做什么和何时用。
---

只放 name 和 description，不要加其他字段。

Body（Markdown 正文）

遵循以下结构：

# Skill 标题

## 工作流
1. 第一步（具体命令或操作）
2. 第二步
3. ...

## 输出格式
期望的输出结构描述。

## 边界情况
- 特殊情况 A 的处理方式
- 特殊情况 B 的处理方式

写作原则：

4. 质量验证清单

编写完成后逐项检查：

## 质量检查清单

### Frontmatter
- [ ] name 只含小写字母、数字、连字符
- [ ] name ≤ 64 字符
- [ ] description 同时包含「功能」和「触发条件」
- [ ] description ≤ 200 字符

### Body
- [ ] 使用祈使句/不定式
- [ ] ≤ 500 行
- [ ] 有可执行的命令或代码示例
- [ ] 没有重复 model 已知的常识
- [ ] 引用的 references/ 文件确实存在
- [ ] 引用的 scripts/ 文件确实存在且可执行

### 触发设计
- [ ] description 不会导致误触发常见任务
- [ ] 模拟 3 个用户请求，预期都能正确匹配
- [ ] 模拟 3 个无关请求，预期不会误触发

### 渐进式加载
- [ ] SKILL.md 核心流程 < 500 行
- [ ] 大段参考资料拆分到 references/
- [ ] 重复代码封装到 scripts/
- [ ] 每个引用文件都有明确的「何时加载」说明

5. 发布准备

agents/openai.yaml（UI 元数据）

display_name: "Skill 显示名称"
short_description: "一句话说明（UI 展示用，≤50 字）"
default_prompt: "用户首次使用的默认提示词"

发布到 awesome-codex-skills

## 发布步骤
1. 确保 Skill 目录结构完整
2. 在 Skill 根目录添加 README.md（仅用于 GitHub 展示，不参与 Skill 加载）
3. README 包含：功能说明、安装方式、使用示例、截图（可选）
4. Fork awesome-codex-skills 仓库
5. 在对应分类下添加条目：
   - 名称 + 链接
   - 一句话描述
   - 安装命令：codex skill install <owner>/<repo>/<skill-path>
6. 提交 PR，等待 review

README.md 模板（发布用，不放入 Skill 目录）

# skill-name

> 一句话描述

## 安装
codex skill install <owner>/<repo>/skill-name

## 功能
- 功能点 1
- 功能点 2

## 使用示例
用户："触发示例 prompt"
Codex：预期行为描述

## License
MIT

输出格式

根据用户所处阶段输出：

• 需求分析阶段：Skill 定义卡 + 目录结构建议
• 编写阶段：完整的 SKILL.md 文件 + 可选的 scripts/references/assets
• 验证阶段：质量检查报告 + 修复建议
• 发布阶段：openai.yaml + README.md + PR 准备清单

边界情况

• 已有 Skill 需要优化：先读取现有 SKILL.md，识别问题后定向改进，不重写
• 用户不确定功能范围：用「最小可用 Skill」策略，先做核心功能，后续迭代
• 需要脚本的 Skill：脚本必须实际执行测试通过，不能只写伪代码