把任何 JSONL 格式的 RAG 源文件，轉換為結構完整、可驗證、可分享的 Claude Code Skill。
100% 完成度 — 每個 JSONL entity 都有對應 reference，每個斷言都有 RAG 錨點，無 AI 編造。
cp -r rag-to-skill ~/.claude/skills/rag-to-skill安裝後，在 Claude Code 中輸入 /rag-to-skill 即可觸發。
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ 1.SCAN │ → │ 2.PLAN │ → │ 3.SCAFFOLD│ → │ 4.BUILD │
│ JSONL分析 │ │ 架構規劃 │ │ 骨架生成 │ │ 內容填充 │
└──────────┘ └──────────┘ └──────────┘ └──────────┘
│
┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ 7.SHIP │ ← │ 6.AUDIT │ ← │ 5.ANCHOR │ ←───────┘
│ 交付/提交 │ │ 驗證稽核 │ │ 錨點標注 │
└──────────┘ └──────────┘ └──────────┘
| 階段 | 產出 | 完成條件 |
|---|---|---|
| 1. SCAN | schema 報告、entity 清單 | 知道有幾個 item、主要章節 |
| 2. PLAN | ref 檔分組方案 | 每個 entity 都有歸屬 ref 檔 |
| 3. SCAFFOLD | 空的 skill.md + references/ | 目錄結構存在，frontmatter 完整 |
| 4. BUILD | 每個 ref 檔填滿 RAG 原文 | 所有 entity 都有完整內容 |
| 5. ANCHOR | 每個斷言都有 > 來源:... 標注 |
錨點密度 ≥ 15/1000 行 |
| 6. AUDIT | validate.py 全綠 | 無 SEVERE 問題 |
| 7. SHIP | 安裝到 ~/.claude/skills/ |
skill 可被觸發使用 |
- 「把 paidRag/大耕老師/紫微攻略.jsonl 做成 skill」
- 「幫我從這本書建立一個 skill，100% 完成度」
- 「這個 skill 還沒完整，幫我對齊 RAG」
- 「這個 skill 要給同事用，準備提交」
| 檔案 | 何時讀 |
|---|---|
references/01-quickstart.md |
已熟悉流程，想快速開始 |
references/02-jsonl-scan.md |
拿到 JSONL 的第一件事 |
references/03-skill-scaffold.md |
建立 skill 目錄結構時 |
references/04-content-build.md |
填充 reference 內容時 |
references/05-anchor-protocol.md |
在 ref 檔中加入來源標注時 |
references/06-validation-scripts.md |
執行品質驗證前（含 validate.py v1.2） |
references/07-completion-checklist.md |
準備提交或分享 skill 前 |
references/08-case-example.md |
第一次用本 skill、想看完整案例 |
從 references/06-validation-scripts.md 一鍵提取：
python3 << 'EXTRACT'
import re, os, sys
path = os.path.expanduser('~/.claude/skills/rag-to-skill/references/06-validation-scripts.md')
content = open(path, encoding='utf-8').read()
m = re.search(r'```python\n(.*?)```', content, re.DOTALL)
if not m:
sys.exit('ERROR: 無法找到 python code block')
open('validate.py', 'w', encoding='utf-8').write(m.group(1))
print(f'validate.py 已提取（{len(m.group(1).splitlines())} 行）')
EXTRACT
python3 validate.py <skill-dir>
python3 validate.py <skill-dir> <path/to/source.jsonl> # 含 JSONL 覆蓋率validate.py 執行 5 項自動檢查：frontmatter 完整性、空骨架、內部連結、RAG 錨點密度、佔位符殘留。
python3（標準函式庫即可，無需額外安裝）- JSONL 格式的 RAG 源文件（每行一個 JSON 物件）
- Claude Code CLI
透過 markitdown 支援幾乎所有格式：
pip install markitdown
python3 any_to_jsonl.py 你的書.pdf # PDF
python3 any_to_jsonl.py 你的書.epub # EPUB
python3 any_to_jsonl.py 你的書.docx # Word
python3 any_to_jsonl.py 你的書.pptx # PowerPoint
python3 any_to_jsonl.py 你的書.html # HTML
python3 any_to_jsonl.py 你的書.pdf --chunk-size 800
python3 any_to_jsonl.py 你的書.pdf --heading-level 2 # 手動指定 H2 分章| 功能 | 說明 |
|---|---|
| 自動偵測章節 | 從 H1 往下找，第一個出現 ≥ 2 次的標題層級即為章節邊界 |
| Markdown 清理 | 移除語法符號、程式碼區塊、圖片語法，保留純文字 |
| 無標題 fallback | 整份文件作為單一 item 切塊 |
pip install pymupdf
python3 pdf_to_jsonl.py 紫微攻略.pdf
python3 pdf_to_jsonl.py 紫微攻略.pdf ~/paidRag/紫微攻略.jsonl
python3 pdf_to_jsonl.py 紫微攻略.pdf --chunk-size 800
python3 pdf_to_jsonl.py 紫微攻略.pdf --no-toc # TOC 不完整時，每頁一個 item| 功能 | 說明 |
|---|---|
| TOC 書籤 | 自動用 PDF 書籤分章，書籤第一章前的頁面歸入「前言 / 版權頁」 |
| Header/Footer 偵測 | 分析前 30 頁，過濾重複出現的頁首/頁尾（書名行、頁碼） |
| 無書籤 fallback | 自動改為每頁一個 item |
對純圖像 PDF（如手機拍攝、掃描書籍）使用 Claude 視覺模型逐頁 OCR：
pip install pymupdf anthropic
export ANTHROPIC_API_KEY=sk-ant-...
# 先估算費用（不執行）
python3 pdf_ocr_to_jsonl.py 你的書.pdf --dry-run
# 正式執行
python3 pdf_ocr_to_jsonl.py 你的書.pdf
python3 pdf_ocr_to_jsonl.py 你的書.pdf 輸出路徑.jsonl
python3 pdf_ocr_to_jsonl.py 你的書.pdf --dpi 100 # 提高解析度（更準確但較貴）
python3 pdf_ocr_to_jsonl.py 你的書.pdf --pages 1-10 # 先測試前 10 頁
python3 pdf_ocr_to_jsonl.py 你的書.pdf --resume # 從中斷點繼續
python3 pdf_ocr_to_jsonl.py 你的書.pdf --model claude-sonnet-4-6 # 更高品質| 功能 | 說明 |
|---|---|
| 費用估算 | --dry-run 預先估算 API 費用，再決定是否執行 |
| 斷點續跑 | --resume 從中斷點繼續，進度自動存入 .progress.json |
| 空白頁跳過 | 自動偵測並跳過封面/空白頁，節省 API 費用 |
| 章節偵測 | 模型辨識章節標題頁，自動分 item |
| 費用追蹤 | 每頁顯示累計費用（使用 API 回傳的實際 token 數） |
費用參考（419 頁掃描書，claude-haiku-4-5，72 DPI）：
| DPI | 圖片尺寸 | 估算總費用 |
|---|---|---|
| 72 DPI | 612×792px | ≈ USD $3–5 |
| 100 DPI | 850×1100px | ≈ USD $6–10 |
實際費用視頁面複雜度與文字量而定；
--dry-run可先估算。
EPUB 電子書可用 epub_to_jsonl.py 直接轉成相容格式：
# 安裝依賴
pip install ebooklib beautifulsoup4
# 轉換
python3 epub_to_jsonl.py 紫微攻略.epub
# → 輸出 紫微攻略.jsonl
# 指定輸出路徑
python3 epub_to_jsonl.py 紫微攻略.epub ~/paidRag/紫微攻略.jsonl
# 調整 chunk 大小（預設 500 字元）
python3 epub_to_jsonl.py 紫微攻略.epub --chunk-size 800輸出格式：
{"loc": {"item_index": 0, "chunk_index": 0}, "chapter": "第一章：命宮", "text": "..."}
{"loc": {"item_index": 0, "chunk_index": 1}, "chapter": "第一章：命宮", "text": "..."}
{"loc": {"item_index": 1, "chunk_index": 0}, "chapter": "第二章：財帛宮", "text": "..."}轉換完成後，直接用 rag-to-skill 建立 skill：在 Claude Code 輸入「把 xxx.jsonl 做成 skill」即可。
pdf_ocr_to_jsonl.py 需要另外呼叫 Anthropic API（有費用）。若想用 Claude Code CLI 本身的視覺能力 做 OCR（消耗 session token，無額外費用），可安裝 /pdf-ocr skill：
cp -r pdf-ocr-skill ~/.claude/skills/pdf-ocr安裝後在 Claude Code 輸入：
/pdf-ocr /path/to/掃描書.pdf
| 功能 | 說明 |
|---|---|
| 無額外費用 | 使用 Claude Code session token，非獨立 API 呼叫 |
| 分批處理 | 每次 30 頁，避免 context 超限 |
| 斷點續跑 | /pdf-ocr <pdf> --resume 從中斷點繼續 |
| 章節偵測 | Claude 自動辨識章節標題頁，分 item |
兩種方案比較：
pdf_ocr_to_jsonl.py |
/pdf-ocr skill |
|
|---|---|---|
| 費用 | 額外 API 費（≈ $3–10 / 書） | 無額外費用 |
| 速度 | 快（平行可跑） | 較慢（逐頁讀取） |
| 適合 | 批次處理、自動化 | 單書 OCR、省錢 |
MIT