技能檔結構拆解

先講清楚：skill 檔是「給 AI 助手看的指令」

Graphify 作為一個 Claude Code / OpenCode / Cursor 的 skill，它的「本體」其實是一份 SKILL.md——一份寫給 AI 代理看的操作手冊。當你在助手裡輸入 /graphify .，助手讀這份檔案，照著裡面的 ## What You Must Do When Invoked 和 Step 0–9 一步步執行。

這份檔案的設計重點：

• 輕量核心 + 按需載入的 references：SKILL.md 本身只講流程，細節（query 怎麼走、extraction prompt 長什麼樣）放在 references/ 側車，需要時才載入。
• Fast path：如果 graphify-out/graph.json 已存在且使用者問的是自然語言問題，直接跳過建圖、立刻跑 graphify query。
• Interpreter guard：所有 subcommand 用 $(cat graphify-out/.graphify_python) 指定 Python 直譯器，避免用錯環境。
• Honesty Rules：最後一段規定助手必須誠實（不誇大、標註不確定）。

Frontmatter：兩個欄位決定一切

---
name: graphify
description: "Use for any question about a codebase, its architecture, file relationships, or project content — especially when graphify-out/ exists, where the question should be treated as a graphify query first. …"
---

這兩個欄位就是 skill 的「名片」——name 決定安裝資料夾名稱，description 決定助手何時認為該用這個 skill。Graphify 的 description 刻意很寬：任何程式碼庫問題都可能觸發。skillgen 的 platforms.toml 規定 description「PRESERVED VERBATIM per platform」——各平台保留同樣的 description。

SKILL.md 的主體：Step 0–9

核心流程是「What You Must Do When Invoked」之後的九個步驟（每個平台版本大同小異）：

檔案後段還有幾個「分流入口」：## For --update and --cluster-only、## For /graphify query、## For /graphify add and --watch、## For the commit hook …——依照使用者的指令類型跳到對應章節。最後是 ## Honesty Rules。

**Fast path — existing graph:** Before doing anything else, check whether
`graphify-out/graph.json` exists. The expected location is
`graphify-out/graph.json` relative to the **current working directory**. If it
exists AND the user's request is a natural-language question about the
codebase (e.g. "How does X work?", "What calls Y?") AND NOT an explicit rebuild
command (`--update`, `--cluster-only`, or a bare path/URL): **skip Steps 1–5
entirely and jump straight to `## For /graphify query`.** Run
`graphify query ""` immediately. Do not run detect. Do not check
corpus size. Do not ask the user to narrow. The graph is already built — use it.

references/ 側車：8 篇參考檔（以 opencode 為例）

每個平台都有 graphify/skills/<platform>/references/，同一組 8 篇（部分平台內容因 hook 機制略異）。SKILL.md 裡 Load this when… 就是載入入口：

有趣的事實：query.md（13KB）是最大的一篇，extraction-spec.md（8KB）其次——這兩篇裝載了「怎麼查圖」與「怎麼抽取」的核心邏輯。

平台差異：以 OpenCode 為例

各平台的 skill 檔幾乎相同，差異在「always-on 機制」與「安裝位置」：

從 install.py 的 PLATFORMS 表可看到對應關係（如 opencode: skill_file: skill-opencode.md, skill_dst: .config/opencode/skills/graphify/SKILL.md）。

這些檔是「生出來的」

SKILL.md 與 references/ 都是 generated artifacts——真正的 source of truth 是 tools/skillgen/fragments/。人在 fragments 編輯，python -m tools.skillgen 重新渲染成各平台成品，--check 檢查有沒有 drift、--bless 更新 baseline。