實戰指南：如何用 Skill Chunk MD 格式建立 GraphRAG 知識庫？

如果你正在建立個人技能圖譜（Skill Graph）或是實作 GraphRAG（檢索增強生成）系統，你一定會面臨一個問題：「如何把平鋪直敘的 Markdown 筆記，轉換成 AI 與圖資料庫能精準讀懂的結構？」

為了解決這個痛點，我們定義了一套標準化的格式——Skill Chunk MD (CtxFST 文件規範)。這套格式的核心目標只有一個：讓文件同時支援**「Chunk 片段檢索」（為了提供詳細上下文）與「Entity 實體檢索」**（為了知識導航與圖譜擴展）。

這篇文章將帶你完整解構這套 YAML 格式規範，看看我們該如何標準化定義 Entity（專業名詞）與 Chunk（內容區塊）。

核心設計理念：Chunk 作為載體，Entity 作為索引

在 Skill Chunk MD 格式中，我們嚴格區分了兩者的職責：

Chunks（內容區塊）：負責回答「我們要檢索出哪段具體文字？」。它是知識的載體，用來給出精準的答案。
Entities（實體名詞）：負責回答「這段文字屬於哪個知識概念？」。它是建立知識圖譜節點（Nodes）的索引，用來帶路與作圖。

💡 Tags（標籤） vs Entities（實體）

Tags 用於粗粒度的分類與文件過濾（例如：Backend, Tutorial）。

Entities 則是有嚴格身分的圖譜節點，用來做概念連線、相似度計算與圖譜尋路（例如：entity:fastapi）。

一、標準文件結構預覽

一份符合 Skill Chunk MD 規範的 Markdown 文件，包含三個核心部分：

頂層 YAML 管理的 entities 清單。
頂層 YAML 管理的 chunks 屬性與關聯。
內文中使用 <Chunk id="..."> 包裝的實際內容。

---
title: "Document Title"
entities:
  # 1. 宣告這份文件涉及的圖譜實體
  - id: entity:python
    name: Python
    type: skill
    aliases: [python3]
  - id: entity:fastapi
    name: FastAPI
    type: framework
    aliases: []
chunks:
  # 2. 定義區塊屬性，並將區塊連向實體
  - id: skill:python-api
    tags: [Python, Backend, API]
    entities: [entity:python, entity:fastapi]
    context: "Python backend work focused on APIs built with FastAPI"
---

<Chunk id="skill:python-api">
## Python API Work
I use Python and FastAPI to build REST APIs...
</Chunk>

二、如何標準化定義 Entity？

Entity 是圖譜的靈魂，它必須被宣告在 YAML frontmatter 的 entities: 陣列中。在整份文件裡，一個 Entity 只需要定義一次。

1. 怎麼挑選 Entity？

並非所有名詞都有資格成為 Entity。提取前請先問自己：「這個詞值得成為技能圖譜上的一個獨立節點嗎？」

✅ 推薦成為 Entity 的對象：硬技能（Python）、工具（Docker）、框架（React）、資料庫（PostgreSQL）、架構（Event-Driven）、通訊協定（JWT）。
❌ 不該做成 Entity 的詞彙：經驗（experience）、工具（tool）、專案方案（project）、特色（feature）、電腦（computer）等過於籠統、無法跨文章重複使用的字眼。

2. Entity 的 YAML 欄位規範

每個 Entity 都是一個 YAML 物件，必須包含以下關鍵資訊：

欄位	必填	說明與規範
`id`	✅	唯一識別碼（寫給機器看的代號）。格式必須是 `entity:` 前綴＋小寫 `kebab-case`。 ✅ 正確示範：`entity:event-driven-architecture` ❌ 錯誤示範（不可大寫或空格）：`entity:Event Driven`
`name`	✅	對外正式顯示名稱（寫給人看的）。高可讀性，可保留大小寫、空格與符號（例如 `FastAPI`, `CI/CD`）。
`type`	✅	概念類型。必須從標準分類清單中選擇。
`aliases`	否	別名/縮寫字串陣列。例如 `[K8s, k8s]`，用來應對文中的不同寫法，防止系統誤判建立重複的節點。

3. 可選擇的 Type 清單

為了圖譜的整整齊齊，請強制從以下清單選擇 type，絕對不要隨意發明新類別：

skill, tool, library, framework, platform, database, architecture, protocol, concept, domain, product。

(如果真的不知道該選哪個，就一律填 concept。)

三、如何標準化定義 Chunk？

定義完實體清單後，我們要在 YAML 的 chunks: 陣列中定義文件的內容區塊，並把這些區塊 「掛載」 到對應的實體上。

1. Chunk 的 YAML 欄位規範

欄位	必填	說明與規範
`id`	✅	區塊識別碼。用來與內文的 `<Chunk>` XML 標籤對應。推薦格式為 `{category}:{topic}`，類別如 `skill:`, `about:`, `project:`, `workflow:`。
`entities`	✅	關聯實體名單。一個陣列，內容必須是這份文件 `entities` 裡已經確確實實定義好的 `id`。建議每個 chunk 連接 1 到 6 個核心關聯實體即可，不要貪心全塞。
`context`	推	區塊上下文描述。見下述的撰寫技巧。
`tags`	否	粗粒度分類標籤（如 `[Python, Data]`）。
`dependencies`	否	Chunk 之間的前置依賴關係（例如：必須先讀過哪個區塊才能讀懂這個區塊）。

2. Context (區塊上下文) 該怎麼寫？

這是一個專門寫給 AI 檢索模型（Retriever）看的欄位。context 的好壞決定了檢索時會不會被誤判。

撰寫原點：說明這個 chunk 在這份文件裡扮演的角色，並確保關聯的實體名稱能自然融入句子中。

🟢 好的 Context："Python backend skills focused on REST APIs, async services, and FastAPI-based implementation." (具體、說明了範圍與情境)
🔴 差的 Context："This chunk talks about Python." (太過廢話，也沒有與其他的 Python 區段做出區別度)

四、實戰對比：Before & After 的轉生之路

讓我們看一個將一般 Markdown 轉換為 Skill Chunk MD 格式的實例。

❌ 轉換前（一般的平鋪直敘 Markdown）

一段難以讓機器抽出知識點的技術自介：

## 關於我
我是一名專精於 API 開發的後端工程師。

## Python 技能
我主要用 Python 寫服務。
- 使用 FastAPI 寫 Web API。
- 使用 Pandas 做資料清理。

✅ 轉換後（GraphRAG Ready!）

加上 YAML 頂層結構，並以 <Chunk> 標籤包裹內文：

---
title: "個人技能介紹"
entities:
  - id: entity:python
    name: Python
    type: skill
    aliases: [python3]
  - id: entity:fastapi
    name: FastAPI
    type: framework
    aliases: []
  - id: entity:pandas
    name: Pandas
    type: library
    aliases: []
chunks:
  - id: about:background
    tags: [About, Backend]
    entities: []
    context: "Professional background as a backend engineer working on APIs and distributed systems."
    priority: medium
  - id: skill:python
    tags: [Python]
    entities: [entity:python, entity:fastapi, entity:pandas]
    context: "Python skills for API development using FastAPI and data processing with Pandas."
    priority: high
---

<Chunk id="about:background">
## 關於我
我是一名專精於 API 開發的後端工程師。
</Chunk>

<Chunk id="skill:python">
## Python 技能
我主要用 Python 寫服務。
- 使用 FastAPI 寫 Web API。
- 使用 Pandas 做資料清理。
</Chunk>

結語：為了圖譜導航而生

透過 Skill Chunk MD 規範（CtxFST 格式）：

當一份文件進入你的 GraphRAG 系統（例如 LanceDB 向量庫或 HelixDB/Neo4j 圖資料庫）時，系統會：
- 將 entities 視為權威的知識圖譜節點（Nodes）。
- 將 chunks[].entities 的宣告視為從 Chunk 指向 Entity 的連線（Edges）。
- 將 dependencies 視為區塊之間的前置路徑。
這能避免系統在提取文件時，自動生成一堆如「電腦」、「工具」等沒有意義的垃圾節點（Entity Noise）。

建立這套嚴謹的格式看似一開始有點繁瑣，但這正是防堵 AI 幻覺實體、建立乾淨整潔的個人「技能樹」，並在未來實現精準 Graph Traversal（圖譜尋路）的關鍵基本功！