# Skill Forge

> Codex Skill 开发工坊，帮助用户从零创建、优化和发布自己的 Codex Skills。当用户想开发新 Skill、需要 SKILL.md 模板、要了解 Skill 最佳实践、或准备发布 Skill 到社区时触发。提供完整的工作流：需求分析 → 结构设计 → 编写实现 → 质量验证 → 发布准备。

- Skill: `xut82429-glitch/skill-forge` (Agent Skill)
- Install (CLI): `npx skillmds@latest add xut82429-glitch/skill-forge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xut82429-glitch/skill-forge/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: xut82429-glitch (https://skillmd.com/u/xut82429-glitch)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/xut82429-glitch/skill-forge

---


# Codex Skill 开发工坊

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

## 工作流

### 1. 需求分析

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

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

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

### 2. 结构设计

确定 Skill 的文件结构：

```markdown
## 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 头部）

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

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

#### Body（Markdown 正文）

遵循以下结构：

```markdown
# Skill 标题

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

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

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

**写作原则**：

| 原则 | 做 | 不做 |
|------|-----|------|
| 语言 | 祈使句（"执行 X"） | 解释性叙述（"这个功能是用来..."） |
| 长度 | ≤500 行 | 超长文档全塞进去 |
| 内容 | Codex 不知道的程序性知识 | 常识或模型已知的知识 |
| 示例 | 可复制执行的命令/代码 | 纯文字描述 |
| 分层 | SKILL.md 放核心流程，details 放 references/ | 全部平铺 |

### 4. 质量验证清单

编写完成后逐项检查：

```markdown
## 质量检查清单

### 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 元数据）

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

#### 发布到 awesome-codex-skills

```markdown
## 发布步骤
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 目录）

```markdown
# 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**：脚本必须实际执行测试通过，不能只写伪代码