Doc to skill

Doc-to-Skill Converter

将官方技术文档（如 Docker、Kubernetes、PostgreSQL 等）转化为可复用的 Agent Skill，提取结构化知识而非生成摘要。

---

核心理念

提取结构，而非摘要。 一本 Skil l不是文档的读书报告，而是一个可重复使用的工具包：

• CLI 命令：精确的语法、参数、选项和用法示例
• API 接口：端点、请求/响应格式、认证方式、状态码
• 配置体系：配置文件结构、环境变量、设置项及其默认值
• 核心概念：架构设计、术语定义、设计哲学
• 最佳实践：生产级推荐配置、性能调优、安全加固
• 反模式：常见陷阱及其原因

保留原文档的精确性。 命令的每个参数、选项都有其存在的理由。"--force" 不等于 "忽略错误"，捕捉精确的语义。

层次化深度。 小工具（如 cli 工具） → 简单技能。大型框架（如 Kubernetes）→ 带引用文件和按需章节的技能。

---

输入类型

类型	说明	示例
文档目录（推荐）	自动发现目录下所有子页面，完整转换	/path/to/doc-content/
单 URL	转换单个页面（默认自动发现同域链接）	https://docs.docker.com/get-started/get-docker/
URL + 爬取深度	限制递归爬取深度	--depth 2 https://docs.docker.com/get-started/
sitemap URL	从 sitemap.xml 发现所有页面	--sitemap https://docs.docker.com/sitemap.xml
本地 HTML/MD 文件	读取本地文档文件	/path/to/docs/overview.md

---

操作模式

提供五种路径，根据用户请求选择：

0. 一键自动转换（推荐）⭐

触发条件：用户说"转换"、"/convert" 或给出了文档路径/URL 且无特殊说明 操作：自动运行 extract.py + generate.py 管道，完成 Steps 1–10 输出：完整技能，含 SKILL.md、sections/、glossary、quick-reference、cheatsheet 命令：

python3 scripts/extract.py <input> --doc-type <type> && \
python3 scripts/generate.py --workdir $DOC_SKILL_WORKDIR --name <skill-name> --doc-type <type>

1. 手动完整转换

触发条件：用户需要精细控制转换过程的每一步 操作：按 Steps 0–9 逐步执行 输出：完整技能

2. 仅分析

触发条件：用户说"分析""仅提取"或"先看结果再生成" 操作：执行步骤 0–3，生成结构化提取报告。停止，不生成技能文件 输出：分析报告供用户审阅

3. 基于已有分析生成

触发条件：用户已有分析笔记，或之前运行过仅分析模式 操作：跳过步骤 0–3，使用已有分析作为输入，执行步骤 4–9（可使用 generate.py 自动化） 输出：技能文件

4. 更新 / 合并（已有技能）

触发条件：用户提供新的文档 URL，并指明要更新已有技能 操作：执行「更新 / 合并工作流」 输出：更新后的已有技能文件

---

技能存放位置

该转换器可生成技能到多个位置。按顺序优先检查：

1. ~/.workbuddy/skills/ — WorkBuddy 用户级技能（默认）
2. {workspace}/.workbuddy/skills/ — 项目级技能

---

Step 0 — 范围检查

如果未提供任何参数，返回并提示：

"doc-to-skill requires a documentation URL, local HTML file, or sitemap URL. Usage: doc-to-skill <url-or-path>... [skill-name-slug]"

在整个工作流中：

• 识别输入路径和可选的技能 slug
• 如果最后一个参数看起来不像 URL 或文件路径，且符合技能 slug 格式（小写连字符），则视为 SKILL_NAME
• 其他参数均为 INPUT_PATHS
• 如果任何输入路径是已有技能目录（含 SKILL.md 和 sections/ 子文件夹），或 SKILL_NAME 匹配已有技能 slug，则标记为更新/合并操作（模式 4）

有效输入格式：

• 文档目录（推荐）：/path/to/doc-content/ — 自动发现并转换整个目录下的所有文档
• HTTP/HTTPS URL：https://docs.example.com/... — 默认自动爬取同域链接，完成完整转换
• --single-page：仅转换单个 URL，不爬取子页面
• --depth N：限制递归爬取深度（默认自动探测）
• --sitemap <url>：从 sitemap 发现文档结构

---

Step 0.5 — 大型文档站点的子领域拆分策略（方案 B）⭐

当评估发现文档规模超过 50 个文件或 ~50K tokens 时，必须执行此拆分策略。

不要试图将整个文档站转换成一个技能。大型文档（如 Docker、Kubernetes、PostgreSQL）必须按子领域拆分为多个独立的 skill，每个 skill 保持单一职责。

拆分规则

原始文档站
├── 顶级目录 1/          → skill-name-1-docs
├── 顶级目录 2/          → skill-name-2-docs
└── 顶级目录 3/          → skill-name-3-docs

拆分边界确定原则：

条件	处理方式
文档有清晰的一级目录结构	每个一级目录独立为一个 skill
文档按产品/组件分册（如 Docker Desktop vs Engine）	每个产品分册独立
单一目录 > 100 个文件	拆分为二级子目录级别
引用/API 参考类文档	如果超过 50 个页面，独立为 skill
教程/指南类文档	合并为 skill-name-guides

示例：Docker 文档拆分方案

Docker 官方文档 ≈ 1,043 个文件 / ~1,327K tokens → 拆分为：

Skill 名称	覆盖范围	文件数	DOC_TYPE
docker-get-started-docs	get-started/	37	mixed
docker-cli-reference	reference/cli/	~124	cli
docker-engine-docs	manuals/engine/	大型	mixed
docker-compose-docs	manuals/compose/	中型	mixed
docker-desktop-docs	manuals/desktop/	中型	mixed
docker-build-docs	manuals/build/	中型	mixed
docker-hub-docs	manuals/docker-hub/	中型	mixed
docker-scout-docs	manuals/scout/	小型	mixed
docker-guides	guides/	98	mixed
docker-api-reference	reference/api/	小型	api

执行流程

1. 对文档站进行目录结构扫描（识别一级/二级目录及其文件数）
2. 根据上述拆分规则确定拆分边界
3. 向用户提出拆分方案并获得确认
4. 逐个生成每个子领域的 skill（遵循完整的步骤 0-9）

命名规范

{tool-name}-{subdomain}-docs 或 {tool-name}-{subdomain}-reference

• docker-engine-docs — Docker Engine 手册
• kubectl-cli-reference — kubectl 命令参考
• postgresql-config-guide — PostgreSQL 配置指南

验证至少有一个有效输入：

• URL 以 http:// 或 https:// 开头
• 本地文件以 .html、.htm、.md、.markdown 结尾
• 本地目录存在

对目录和 glob 进行展开，找到所有支持的本地文件。 对 URL 进行连通性检查（HEAD 请求）。

如果无有效输入，返回明确的错误信息。

---

Step 1.5 — 识别文档类型

在提取前，询问用户：

"这些文档属于什么类型？这帮助我选择最佳提取方法。

1. API 参考 — 大量端点定义、参数表、状态码、请求/响应示例（如 REST API、gRPC API 文档）
2. CLI 工具 — 命令语法、子命令、选项、标志、用法示例（如 docker、kubectl、git）
3. 配置/运维指南 — 配置文件、环境变量、部署拓扑、架构图（如 nginx.conf、Docker Compose）
4. 混合/通用 — 综合文档，包含以上多种内容（默认）
5. 不确定 — 我将使用通用方法"

存储答案为 DOC_TYPE：

• 选项 1 → DOC_TYPE=api
• 选项 2 → DOC_TYPE=cli
• 选项 3 → DOC_TYPE=config
• 选项 4 → DOC_TYPE=mixed（默认）
• 选项 5 → DOC_TYPE=mixed

根据 DOC_TYPE 调整输出重点：

• api → 章节模板强调端点、参数、请求/响应、错误码
• cli → 章节模板强调命令语法、子命令、选项、示例
• config → 章节模板强调配置选项、默认值、环境变量
• mixed → 完整模板，均衡覆盖

---

Step 2 — 从文档源提取内容

2a — 解析输入

识别输入中的 URL 和本地路径：

• 文档目录（推荐） → 递归发现所有支持的文档文件（.md、.html），批量处理
• URL（默认完整转换） → 抓取页面后，自动发现同域下的所有文档链接并批量爬取（除非指定 --single-page）
• 本地文件 → 读取并解析
• 目录 → 递归查找支持的文档文件

2b — 执行提取

SCRIPT_PATH=""
for candidate in \
  "$HOME/.workbuddy/skills/doc-to-skill/scripts/extract.py" \
  "{workspace}/.workbuddy/skills/doc-to-skill/scripts/extract.py"
do
  if [ -f "$candidate" ]; then
    SCRIPT_PATH="$candidate"
    break
  fi
done

if [ -z "$SCRIPT_PATH" ]; then
  echo "Could not find scripts/extract.py for doc-to-skill" >&2
  exit 1
fi

PYTHON_BIN="python3"
if ! command -v "$PYTHON_BIN" >/dev/null 2>&1; then
  PYTHON_BIN="python"
fi

# 完整转换：处理目录或自动爬取
"$PYTHON_BIN" "$SCRIPT_PATH" $INPUT_PATHS --doc-type <DOC_TYPE> [--single-page] [--depth <N>]

# 大文档子领域拆分（方案B）：
# 对每个子目录分别执行提取
for subdir in $SUB_DIRECTORIES; do
  "$PYTHON_BIN" "$SCRIPT_PATH" "$subdir" --doc-type <DOC_TYPE>
done

提取过程：

1. 抓取每个 URL 的 HTML 内容
2. 将 HTML 转换为 Markdown（清理导航、页脚、广告等无关元素）
3. 如果指定了 --depth > 1，递归发现并抓取子页面（限同域名）
4. 如果指定了 --sitemap，解析 sitemap.xml 发现所有页面
5. 合并所有页面内容，按文档层次结构组织

输出在临时目录：

• <tempdir>/doc_skill_work/full_text.md — 合并后的 Markdown 文本，带清晰的页面边界标记
• <tempdir>/doc_skill_work/metadata.json — 元数据（页面数、字数、token 数、页面列表）
• <tempdir>/doc_skill_work/pages/ — 每个页面单独的 Markdown 文件

2c — 预检环境

运行 "$PYTHON_BIN" "$SCRIPT_PATH" --check 检查依赖是否安装，不处理任何文件。

---

Step 2.3 — 一键自动生成管道（推荐）⭐

提取完成后，直接执行 generate.py 完成 Steps 3–10 的全自动化：

# 定位 generate.py
GEN_SCRIPT=""
for candidate in \
  "$HOME/.workbuddy/skills/doc-to-skill/scripts/generate.py" \
  "{workspace}/.workbuddy/skills/doc-to-skill/scripts/generate.py"
do
  if [ -f "$candidate" ]; then
    GEN_SCRIPT="$candidate"
    break
  fi
done

# 自动生成完整 skill
"$PYTHON_BIN" "$GEN_SCRIPT" \
  --workdir "<DOC_SKILL_WORKDIR>" \
  --name "<skill-name>" \
  --doc-type "<DOC_TYPE>" \
  --register

generate.py 自动完成的内容：

步骤	传统方式（手动）	自动化方式（generate.py）
Step 3	Agent 手动读取 full_text.md 分析标题结构	自动解析 Markdown 标题层级，检测章节
Step 6	手动 mkdir 创建目录结构	自动创建 sections/ 目录
Step 7	Agent 逐章编写 section 文件	自动按章节拆分，使用对应模板填充
Step 8	手动编写 glossary/quick-reference/cheatsheet	自动提取术语、命令、生成骨架
Step 9	手动编写 SKILL.md	自动生成 SKILL.md + 章节索引 + 主题索引
Step 10	手动清理	由调用者处理

生成器的能力边界

generate.py 是辅助生成而非完全替代 Agent：

能力	自动化程度	说明
章节拆分	✅ 完全自动	基于 H1/H2 标题层级
术语提取	✅ 基本自动	提取 **Term** — definition 模式
命令提取	✅ 基本自动	从代码块中提取 CLI 命令
SKILL.md 骨架	✅ 完全自动	模板填充 + 索引生成
章节内容质量	⚠️ 需 Agent 审核	模板内容是占位符，需人工精化
最佳实践提取	⚠️ 需 Agent 审核	当前为占位符
决策规则提取	⚠️ 需 Agent 审核	当前为占位符

最佳实践：先用 generate.py 自动生成骨架，然后 Agent 逐章精化内容。相比完全手动编写，可节省约 70% 的工作量。

完整一键命令

# 一行命令完成提取 + 生成
DOC_SKILL_WORKDIR=$(mktemp -d) && \
export DOC_SKILL_WORKDIR && \
python3 $HOME/.workbuddy/skills/doc-to-skill/scripts/extract.py \
  "<input-path-or-url>" --doc-type "<DOC_TYPE>" && \
python3 $HOME/.workbuddy/skills/doc-to-skill/scripts/generate.py \
  --workdir "$DOC_SKILL_WORKDIR" --name "<skill-name>" \
  --doc-type "<DOC_TYPE>" --register && \
rm -rf "$DOC_SKILL_WORKDIR"

---

Step 2.5 — 预检成本估算

读取 <tempdir>/doc_skill_work/metadata.json，在生成前向用户展示估算：

📖 文档源检测：<N> 个页面
<list each page URL/path>

📄 页面：~<N> | 字数：~<N> | 总 tokens：~<N>K

💰 预估 token 成本（完整转换）：
   输入（读取 + 提示）：~<N>K tokens
   输出（技能文件生成）：~<N>K tokens
   总计：~<N>K tokens

⏱  预计耗时：~<N> 分钟

📁 将生成的文件：
   SKILL.md + section 文件 + glossary + quick-reference + cheatsheet

➡  是否继续完整转换？（或输入 "analyze only" 先预览）

估算方法：

• 输入 tokens ≈ estimated_tokens × 1.3（各章节处理的提示开销）
• 输出 tokens ≈ sections × 每个章节的预算 + 4,000（SKILL.md）+ 4,500（glossary + quick-reference + cheatsheet）
  • 每章节预算：cli/api ≈ 2,000，config ≈ 1,800，mixed ≈ 1,500

等待用户确认后再继续。如果用户说 "analyze only"，切换到模式 2。

---

Step 2.6 — 大型文档的 REPL 式访问

对于超过 50k tokens 的文档，优先使用 grep/sed 进行定向查询，而非全部加载：

# 检查大小
wc -w "$FULL_TEXT_PATH"

# 查找页面/章节边界
grep -n -E "^##+\s+" "$FULL_TEXT_PATH" | head -40

# 仅提取特定页面
sed -n '<start>,<end>p' "$FULL_TEXT_PATH"

# 验证某个命令/概念是否被提及
grep -c -i "docker compose\|docker-compose" "$FULL_TEXT_PATH"

# 定向读取特定章节
# Read(file_path=full_text.md, offset=<line>, limit=<lines>)

50k tokens 以下的文档可以一次性 Read。

---

Step 3 — 分析文档结构（可自动）

读取提取的 full_text.md 的前 8000 个字符，识别：

• 文档标题和版本（通常在 <title> 标签或 H1 中）
• 页面/章节层级结构（基于 Markdown 标题层级）
• 核心主题域（CLI 命令、API 端点、配置项等）
• 页面总数和层次深度

然后读取整个文档的标题结构来映射所有章节。

自动化分析

也可以用 generate.py 自动完成结构分析：

python3 scripts/generate.py --workdir <workdir> --name <skill-name> --doc-type <type> --sections-only

这会自动读取 full_text.md，基于 Markdown 标题解析章节结构，在 sections/ 下生成带模板的章节文件。

如果模式是"仅分析"： 现在生成提取报告并停止。报告结构：

## 提取报告 — <文档标题> v<版本>

### 页面结构
| 层级 | 页面 | 主题 |
|------|------|------|
| 1 | getting-started | 安装、快速开始 |
| 2 | cli/run | docker run 命令参考 |
| 2 | cli/build | docker build 命令参考 |

### 核心命令/API
- **<命令/端点>**：<简要说明>

### 关键配置项
- **<配置>**：<默认值、说明>

### 建议的技能名称
`{tool-name}-docs` — 例如 `docker-docs`、`kubectl-docs`

### 检测到的章节
| # | 章节 | 子页面数 | 核心主题 |

---

Step 4 — 询问用途（仅完整转换）

生成前，询问用户：

"这个技能应该帮你做什么？（可多选）

1. 在工作中快速查阅命令和 API
2. 学习文档中的架构和设计理念
3. 作为配置和部署的参考手册
4. 以上所有"

根据答案权重调整 SKILL.md Core 部分的内容重点。

推导 DEPTH：

• 答案仅包含选项 1 或 3（参考用途）→ DEPTH=reference — 精简、快速查阅的章节
• 答案包含选项 2 或 4 → DEPTH=study — 更深入的章节，含更多示例和解释

DEPTH 和 DOC_TYPE 共同决定 Step 7 中的每章节 token 预算。

---

Step 5 — 确定技能名称

5a — 单文档集命名

如果提供了 SKILL_NAME，直接使用。 否则，提出两个选项让用户选择：

• 按工具名：{tool-name}-docs（如 docker-docs、kubernetes-docs）
• 按文档集名称：{docset-abbreviation}（如 docker-engine、kube-api）

默认使用工具名格式。

5b — 子领域拆分命名（方案B）

当执行方案 B 拆分时，命名规则：

{tool-name}-{subdomain}-{suffix}

文档内容	命名	示例
入门/安装指南	{tool}-getting-started	docker-getting-started-docs
CLI 命令参考	{tool}-cli-reference	docker-cli-reference
产品分册	{tool}-{product}-docs	docker-engine-docs
API 参考	{tool}-api-reference	docker-api-reference
配置指南	{tool}-config-guide	nginx-config-guide
场景化指南	{tool}-guides	docker-guides

5c — 存放位置

• 默认：~/.workbuddy/skills/
• 如果用户要求项目级：{workspace}/.workbuddy/skills/

检查 $SKILLS_HOME/<skill_name>/ 是否已存在。如果存在，引导用户选择：

1. 更新 / 合并（模式 4）
2. 覆盖 — 删除并重新生成
3. 重命名 — 添加 -2 或使用不同的 slug

---

Step 6 — 创建技能目录结构

mkdir -p "$SKILLS_HOME/<skill_name>/sections"

自动化：generate.py --workdir <workdir> --name <name> 会自动创建此结构。

---

Step 7 — 生成章节文件（可自动自动）

推荐使用自动化：generate.py 会自动完成章节拆分和模板填充。 手动操作仅当需要对每个章节精细控制内容时使用。

TOKEN 预算规则（自适应的）：

每章节预算根据 DOC_TYPE 和 DEPTH 调整：

	DEPTH=reference	DEPTH=study
DOC_TYPE=cli	1,200–1,800 tokens	2,000–3,000 tokens
DOC_TYPE=api	1,500–2,000 tokens	2,500–3,500 tokens
DOC_TYPE=config	1,000–1,500 tokens	1,800–2,500 tokens
DOC_TYPE=mixed	1,000–1,500 tokens	1,500–2,500 tokens

对 Step 3 中识别的每个顶级章节：

读取 full_text.md 中对应章节的内容（使用 grep 定位页面边界）。

创建 $SKILLS_HOME/<skill_name>/sections/sec<NN>-<slug>.md，使用以下模板并根据 DOC_TYPE 调整结构：

CLI 工具章节模板（DOC_TYPE=cli）

# sec<NN>: <命令名> 命令参考

## 概述
<1–2 句：这个命令做什么>

## 语法
```bash
<command> [options] [arguments]

子命令

子命令	说明
<sub>	<简要说明>

主要选项 / 标志

标志	类型	默认值	说明
--<flag>	<type>	<default>	<说明>
-<short>			<短标志说明>

使用示例

# <示例说明>
<command> <args>

<示例 2 说明>

<command> <args>

常用组合模式

• <场景>：<command> <flags> <args>
• <场景>：<command> <flags> <args>

注意事项

• <重要提示 1>
• <常见错误 2>

关联章节

• sec<NN>：<为什么相关>

### API 参考章节模板（`DOC_TYPE=api`）

```markdown
# sec<NN>: <资源名> API

## 概述
<1–2 句：这个端点做什么>

## 端点

<METHOD> /api/v<version>/<resource>[/<id>]

## 请求参数
### 路径参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `<param>` | `<type>` | 是/否 | <说明> |

### 查询参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|

### 请求头
| 头 | 值 | 必填 | 说明 |
|----|-----|------|------|

### 请求体 (JSON)
```json
{
  "<field>": "<type>",
  "<field>": "<type>"
}

响应

成功响应 (200/201)

{
  "<field>": "<type>"
}

错误响应

状态码	说明	典型场景
400	<Bad Request>	<场景>
404	<Not Found>	<场景>

使用示例

curl -X <METHOD> <url> \
  -H "Authorization: Bearer <token>" \
  -d '{"<key>": "<value>"}'

速率限制

• <限制策略>

关联章节

• sec<NN>：<为什么相关>

### 配置/指南章节模板（`DOC_TYPE=config`）

```markdown
# sec<NN>: <配置项/功能名>

## 概述
<1–2 句>

## 配置选项
| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `<key>` | `<type>` | `<default>` | <说明> |

## 环境变量
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `<VAR>` | `<default>` | <说明> |

## 配置文件示例
```<language>
# <说明>
<config_key>: <value>

最佳实践

• <实践 1>：<说明>
• <实践 2>：<说明>

安全注意事项

• <安全提示 1>
• <安全提示 2>

关联章节

• sec<NN>：<为什么相关>

### 通用 / 混合章节模板（`DOC_TYPE=mixed`）

```markdown
# sec<NN>: <章节标题>

## 概述
<1–2 句：本节核心内容>

## 核心概念
<!-- 本节最重要的概念和术语 -->
- **<Term>**：<精确的定义>

## 关键操作
| 操作 | 说明 | 适用场景 |
|------|------|----------|
| <操作> | <说明> | <场景> |

## 配置要点
| 配置 | 默认值 | 推荐值 | 说明 |
|------|--------|--------|------|

## 使用示例

<示例代码或命令>

## 最佳实践
- **<实践>**：<说明>
- **<实践>**：<说明>

## 注意事项 / 常见陷阱
- **<陷阱>**：<原因> → <解决方案>

## 关联章节
- **sec<NN>**：<为什么相关>

通用章节质量规则

1. 精确性优先：命令参数、API 字段、配置键名必须与官方文档完全一致
2. 密度优于完整性：一个 1,000 token 的精准参考胜过 10,000 token 的原文摘抄
3. 实操者视角：写 "使用 --flag 当 X"，不写 "文档中说..."
4. 代码/命令示例必须可复现：提供完整的上下文，而非片段
5. 反模式明确标出：标注 "⚠️ 避免" 并说明原因

---

Step 8 — 生成辅助文件（可自动化）

推荐使用自动化：generate.py 会自动提取术语生成 glossary，提取命令生成 quick-reference。 手动操作仅当需要对内容精细控制时使用。

自动化方式

python3 scripts/generate.py --workdir <workdir> --name <name> --doc-type <type>

这会自动生成：

• glossary.md — 从文档中自动提取 **Term** — definition 模式
• quick-reference.md — 从代码块中提取 CLI 命令并整理为表格
• cheatsheet.md — 根据 doc-type 生成对应的决策指南骨架

glossary.md

自动化策略：正则匹配 **Term** — definition 和 - **Term**: definition 模式 最大 1,500 tokens 自动填充到 glossary.md，Agent 需审核准确性和补充缺失项

glossary.md

创建 $SKILLS_HOME/<skill_name>/glossary.md：

• 所有关键术语，按字母/拼音排序
• 格式：**Term** — 定义 (sec NN)
• 最大 1,500 tokens

quick-reference.md

创建 $SKILLS_HOME/<skill_name>/quick-reference.md：

• 最常用的 20+ 命令/API/配置项的速查表
• 格式：紧凑表格，适合快速扫视
• 最大 1,500 tokens

cheatsheet.md

创建 $SKILLS_HOME/<skill_name>/cheatsheet.md：

这是技能最具区分度的层 — 将其视为决策辅助工具，而非关键词列表。捕获的是使用该工具的判断力：

按顺序优先：

1. 决策规则 — "当 X 时，做 Y，因为 Z"
2. 决策树 / 流程图（嵌套列表或表格）— 两个以上分支的选择
3. 对比矩阵 — 竞争选项在关键维度上的评分
4. 阈值与默认值 — 具体的数字、比率或经验法则
5. 排查线索 — 快速识别问题的启发式方法

• 格式：紧凑表格和决策规则
• 最大 1,200 tokens

---

Step 9 — 生成主 SKILL.md（可自动化）

推荐使用自动化：generate.py 会自动生成 SKILL.md 骨架（含章节索引、主题索引）。 手动操作仅当需要精细定制 Core Quick Reference 内容时使用。

自动化方式

generate.py 会自动：

1. 根据 metadata 生成 YAML frontmatter（name/description）
2. 基于已生成的章节文件构建章节索引表
3. 从章节标题自动生成主题索引
4. 使用 doc-type 模板填充 Core Quick Reference 占位符

python3 scripts/generate.py --workdir <workdir> --name <name> --doc-type <type> --register

手动精化（推荐）

自动生成的 SKILL.md 是骨架，Agent 应重点精化：

1. Core Quick Reference 部分（~2,000 tokens）：这是技能的核心价值
2. 主题索引：确保所有关键术语都被索引
3. Related Skills 交叉引用：关联其他相关 skill

关键 TOKEN 预算：SKILL.md 正文保持 4,000 tokens 以内。 压缩从尾部截断 — 最核心的内容放在最前面。

创建 $SKILLS_HOME/<skill_name>/SKILL.md：

---
name: <skill_name>
description: "Official documentation reference for <Tool Name>. Use when working with <tool> — commands, APIs, configuration, best practices."
---

# <Tool Name> 文档参考
**版本**：<version> | **章节**：<N> | **生成日期**：<YYYY-MM-DD>

## 使用方式

- **无参数** — 加载核心概念和快速参考
- **命令/API** — Ask: `docker run`, `kubectl apply`, `CreateContainer`
- **话题** — 询问 `网络配置`、`存储卷`、`安全策略`
- **章节** — 要求 `sec03` 加载特定章节

当询问 Core Quick Reference 未覆盖的话题时，我会先读取相关章节文件再回答。

---

## Core Quick Reference
<!-- ~2,000 tokens：最核心的命令、概念和模式。决策规则、常用组合、典型工作流 -->

<生成最关键的 2,000 tokens 参考内容>

---

## 章节索引

| # | 章节 | 核心主题 |
|---|------|----------|
| [sec01](sections/sec01-<slug>.md) | <标题> | <主题 1>, <主题 2> |
| [sec02](sections/sec02-<slug>.md) | <标题> | <主题 1>, <主题 2> |
...

## 主题索引

<!-- 按字母/拼音排序。主要术语/命令 → 章节 -->
- **<命令/术语>** → sec<N>[, sec<N>]
- **<命令/术语>** → sec<N>

## 辅助文件

- [glossary.md](glossary.md) — 所有关键术语定义
- [quick-reference.md](quick-reference.md) — 常用命令/API 速查表
- [cheatsheet.md](cheatsheet.md) — 决策表和快速参考指南

---

## 范围与限制

本技能覆盖官方 <Tool> 文档内容。对于代码库中的具体实现，请结合项目工具。超出本文档范围的话题，请查阅相关技能或直接询问 Agent。

---

Step 10 — 清理与报告

PYTHON_BIN="python3"
if ! command -v "$PYTHON_BIN" >/dev/null 2>&1; then
  PYTHON_BIN="python"
fi

"$PYTHON_BIN" - <<'PY'
import os
import shutil
import tempfile
from pathlib import Path
shutil.rmtree(
    os.environ.get("DOC_SKILL_WORKDIR", Path(tempfile.gettempdir()) / "doc_skill_work"),
    ignore_errors=True,
)
PY

然后向用户报告：

✅ 技能创建完成：<SKILLS_HOME>/<skill_name>/

📚 文档：<Tool Name> v<version>
📄 页面：~<N> | 章节：<N>

生成的文件：
  SKILL.md            — 核心参考 + 索引    (~X tokens)
  sections/           — <N> 章节文件       (~X tokens/个, ~X total)
  glossary.md         — 术语表            (~X tokens)
  quick-reference.md  — 速查表            (~X tokens)
  cheatsheet.md       — 决策指南           (~X tokens)
  ─────────────────────────────────────────────
  技能总大小：~X tokens（按需加载，非一次性）

💡 提示：查看实际 token 用量。

使用方式：
  要求 <skill_name>              → 加载核心参考
  询问 <skill_name> <命令/API>   → 查找并解释
  要求 <skill_name> sec<N>       → 深入特定章节

---

更新 / 合并工作流

当对已有技能 $SKILLS_HOME/<skill_name>/ 执行更新/合并操作时：

1. 读取已有技能结构

读取并解析已有技能文件：

• 读取 SKILL.md，解析章节索引、主题索引、元数据
• 列出 sections/ 下的文件，找到最大章节编号（如 sec12）
• 读取 glossary.md、quick-reference.md、cheatsheet.md 了解已有索引

2. 匹配内容，识别修订 vs 新增

分析新提取的文档内容，识别：

• 更新/修订已有章节：如果新内容更新了已有章节的主题，读取已有章节文件，合并新细节后重写
• 新增内容：如果引入新的页面/章节，创建新章节文件，从最大编号后开始编号（如 sec13-*.md）

3. 生成或更新章节文件

按照 Step 7 的模板格式进行。

4. 合并辅助文件

• 合并 glossary.md：读取已有文件，提取新术语，合并并按字母排序，更新引用
• 合并 quick-reference.md：读取已有文件，添加新条目
• 合并 cheatsheet.md：读取已有文件，整合新的决策规则

5. 重新生成主 SKILL.md

更新元数据、核心参考、章节索引、主题索引。

6. 清理并执行 Step 10

---

质量规则

1. 提取结构，而非摘要 — 捕获精确的命令语法、参数定义、API 端点；不重述简介段落
2. 保留原文档精确性 — --force ≠ --ignore-errors；保持精确语义
3. 密度优于完整性 — 1,000 token 的精确参考胜过 10,000 token 的原文摘抄
4. 实操者视角 — 写"使用 --flag 当 X"，不写"文档中说..."
5. 正向加载 SKILL.md — 压缩保留前 5,000 tokens；最重要的内容放在最前面
6. 章节文件按需加载 — 不计入技能预算，直到被实际读取
7. 绝不复制原文 — 始终综合、总结、提取信号
8. 主题索引至关重要 — 它是 Agent 导航到正确章节文件的路径
9. 示例必须可复现 — 提供完整的命令/请求/配置上下文，而非片段
10. 反模式明确标注 — 常见陷阱和错误配置必须标记为 ⚠️

---

示例场景

场景 1：完整转换 Docker 入门文档（目录模式）

用户：doc-to-skill /path/to/docker-content/get-started/ docker-getting-started-docs

场景 2：方案B - 拆分 Docker 全站文档

用户：doc-to-skill --split /path/to/docker-content/ docker-docs
分析：检测到 6 个一级目录，1,043 个文件
建议拆分为：
  - docker-getting-started-docs  ← get-started/ (37文件)
  - docker-cli-reference         ← reference/cli/ (124文件)
  - docker-engine-docs           ← manuals/engine/ (N文件)
  - docker-compose-docs          ← manuals/compose/ (N文件)
  - docker-desktop-docs          ← manuals/desktop/ (N文件)
  - docker-guides                ← guides/ (98文件)

场景 3：转换 Kubernetes API 参考

用户：doc-to-skill --sitemap https://kubernetes.io/docs/sitemap.xml --doc-type api k8s-api-reference

场景 4：分析 PostgreSQL 配置文档

用户：doc-to-skill -analyze https://www.postgresql.org/docs/current/config-setting.html

场景 5：更新已有技能

用户：doc-to-skill https://docs.docker.com/compose/release-notes/ docker-compose-docs --update