在个人电脑上创建 Codex Skill：编写、打包与分发全流程

本文面向个人电脑使用者，介绍如何在本机创建一个 Codex Skill，并完成打包与分发。内容覆盖技能结构、初始化、编辑要点、校验打包以及跨机器安装，适合想把常用工作流固化成技能的用户。

---

1. Skill 是什么

Skill 是 Codex 的“专用流程包”，用于把某类任务的步骤、规则、脚本和模板沉淀成可复用能力。一个 Skill 最少包含一个 SKILL.md 文件；也可以包含 scripts/、references/、assets/ 三类资源（可选）。

典型用途

• 工程实践：固定排查流程、运维脚本、标准交付规范
• 故障排查：常见错误的诊断顺序、关键日志定位
• 教程写作：固定写作风格、输出规则
• 架构设计：输出格式、决策约束、评审检查清单

---

2. Skill 的目录结构

一个最小 Skill 结构如下：

blogger-writer/
  SKILL.md

完整结构可扩展为：

blogger-writer/
  SKILL.md
  scripts/
  references/
  assets/

注意：除 SKILL.md 外，其他目录都是可选的。

---

3. 在本机初始化 Skill

推荐使用官方的 Skill 创建脚本来生成模板结构（已包含正确的 frontmatter 与基本框架）。

脚本路径（Windows 示例）

C:\Users\<你>\.codex\skills\.system\skill-creator\scripts\init_skill.py

初始化命令

python "C:\Users\<你>\.codex\skills\.system\skill-creator\scripts\init_skill.py" \
  blogger-writer \
  --path "C:\Users\<你>\.codex\skills"

执行后会生成：

C:\Users\<你>\.codex\skills\blogger-writer\SKILL.md

---

4. 编写 SKILL.md 的关键点

4.1 YAML frontmatter

SKILL.md 顶部必须包含 YAML frontmatter，且只允许 name 与 description。下面是完整示例（含正文），可直接作为参考：

完整示例：blogger-writer 的 SKILL.md

---
name: blogger-writer
description: 编写简体中文 IT 技术博客（工程实践、故障排查、教程、架构设计等），用于撰写或润色技术文章、在项目中创建新的 Markdown 文档，并根据文章主题生成配套的 SVG 封面。
---

# 技术博客写作

## 概述

编写严谨、内容详实的简体中文 IT 技术博客，并以 Markdown 形式交付，然后设计与主题一致的 SVG 封面。

## 工作流程

1) 澄清需求
- 确认主题、受众、范围与深度。
- 仅在必要时询问限制条件（长度、语气、发布平台）。

2) 收集事实与上下文
- 从对话中提取可验证的数据（命令、日志、配置）。
- 识别缺失信息；必要时明确标注假设。

3) 规划结构（不固定模板）
- 使用清晰的小节与简短段落。
- 故障排查优先“问题→排查→修复”的流程，教程采用可复现的步骤流。

4) Markdown 起草
- 使用准确语言、实操细节与可复现步骤。
- 原样呈现命令、日志或代码块。
- 在必要时强调注意事项、验证步骤与回滚说明。

5) 完成定稿
- 确保文章自洽且可操作。
- 需要时加入简洁结论或要点总结。

6) 生成主题封面（SVG）
- 在 Markdown 完成后生成 1600x900 的 SVG。
- 使用清晰排版与与主题匹配的视觉要素。
- 不依赖外部资源，保持 SVG 自包含。
- 标题已知时应体现于封面。

## 写作规范

- 使用简体中文，语气严谨。
- 以技术准确性为先，避免营销化表述。
- 避免模糊描述，使用上下文中的具体证据。
- 步骤描述需确定且可复现。
- 必要假设需明确标注。

## 输出规则

- 默认在当前项目路径新建 Markdown 文档，除非用户指定路径。
- 未明确要求时不得覆盖已有文件。
- Markdown 完成后生成配套 SVG 封面，并与文章保存在同一目录。

要求：

• name 与目录名一致
• description 必须清楚描述“什么时候触发该 skill”
• 建议用中文描述，同时保留必要关键词提升触发率

4.2 内容编写原则

• 内容要简洁但具操作性
• 避免大段通用叙述（Codex 已懂的内容无需重复）
• 写清流程步骤与输出规则
• 不需要固定模板就不要强加模板

---

5. Skill 校验与打包

Skill 打包本质是将目录压缩为 .skill 文件，但在打包前会先做结构校验。

打包脚本路径

C:\Users\<你>\.codex\skills\.system\skill-creator\scripts\package_skill.py

打包命令（推荐指定输出目录）

python "C:\Users\<你>\.codex\skills\.system\skill-creator\scripts\package_skill.py" \
  "C:\Users\<你>\.codex\skills\blogger-writer" \
  "C:\Users\<你>\.codex\skills\dist"

成功后生成：

C:\Users\<你>\.codex\skills\dist\blogger-writer.skill

注意：

• 打包会校验 SKILL.md YAML 格式、目录结构、描述完整性
• Windows 默认编码可能导致读取失败，可临时设置 PYTHONUTF8=1

---

6. Skill 分发与安装

.skill 文件本质是 zip 包。分发后，在目标机器上解压到 $CODEX_HOME/skills/<skill-name> 即可。

6.1 Windows 安装示例

$skill = "C:\path\to\blogger-writer.skill"
$dest  = "$env:USERPROFILE\.codex\skills\blogger-writer"
New-Item -ItemType Directory -Force -Path $dest | Out-Null
Expand-Archive -Path $skill -DestinationPath $dest -Force

完成后重启 Codex，即可生效。

---

7. 最小流程回顾

1. init_skill.py 初始化
2. 编辑 SKILL.md 完成描述
3. package_skill.py 打包生成 .skill
4. 分发并解压到目标机器的 $CODEX_HOME/skills

---

8. 常见问题

Q1：必须写英文吗？
不需要，SKILL.md 可用中文，只要 YAML frontmatter 合规。

Q2：没有 scripts/references/assets 可以打包吗？
可以，最小技能只需 SKILL.md。

Q3：如何确认已生效？
重启 Codex 后，用与 description 匹配的请求测试触发。

---

9. 结语

把重复的工作沉淀为 Skill，可以显著减少沟通成本和重复指令。建议优先将高频、流程固定、可复用的任务整理为 Skill，再逐步沉淀脚本与模板，形成高效的个人工作流体系。