スキル Chunk MD

Markdownを、セマンティックな<Chunk>タグ、構造化されたフロントマター、明示的なエンティティレイヤーを持つCtxFSTドキュメントに変換します。

目標

このスキルを使用して、以下の両方をサポートするドキュメントを作成します。

チャンク検索：詳細なコンテキストのため
エンティティ検索：ナビゲーション、グラフ展開、関連概念の発見のため

テキストを分割するだけでなく、重要なドメインエンティティを抽出し、正規化し、各チャンクが実際に議論しているエンティティにリンクします。

レイアウトの選択

ソースがノート型かメモリー型かを早期に判断します。

ノート型（1つのプロファイル、1つのベンチマーク、1つのミーティングログ）：以下で説明する標準的な複数エンティティ/ファイルレイアウトを使用します。
メモリー型（時間とともに成長する知識ベース、エンティティごとの資料、エージェントメモリ）：エンティティ中心の規約を使用します（1エンティティにつき1ファイル、ファイル名はentity-<id-suffix>.ctxfst.md、entities:は正確に1つの所有者、すべてのチャンクがその所有者を参照）。相互参照はエンティティIDを使用し、他のファイルに解決します。

エンティティ中心は規約であり、スキーマの変更ではありません。同じフロントマタールールが適用されます。違いは、len(entities) == 1であり、ファイル名が所有者を示すことです。具体例についてはassets/examples/entity-centric/を参照し、python3 scripts/validate_chunks.py <path> --entity-centricで検証してください。

ターゲット形式

CtxFSTドキュメントには以下を含める必要があります。

YAMLフロントマター
ドキュメントレベルのentitiesカタログ
ドキュメントレベルのchunksカタログ
<Chunk>タグでラップされた本文コンテンツ

---
title: "ドキュメントタイトル"
entities:
  - id: entity:python
    name: Python
    type: skill
    aliases: [python3]
  - id: entity:fastapi
    name: FastAPI
    type: framework
    aliases: []
chunks:
  - id: skill:python-api
    tags: [Python, Backend, API]
    entities: [entity:python, entity:fastapi]
    context: "FastAPIを使用したAPI構築に焦点を当てたPythonバックエンド作業"
---

<Chunk id="skill:python-api">
## Python API作業
PythonとFastAPIを使用してREST APIを構築しています...
</Chunk>

基本原則

チャンクをコンテンツキャリアとして、エンティティをセマンティックインデックスとして使用します。

チャンクは「どの正確な箇所を取得すべきか？」に答えます。
エンティティは「この箇所はどの概念に属するか？」に答えます。

タグは大まかなフィルタリングに役立ちます。エンティティが標準的なグラフノードです。

コアワークフロー

ステップ1：文書構造の分析

ソースMarkdown内の意味的な境界を特定します。

新しいトピックを導入する見出し（##、###）
長いセクション内のテーマの移行
1つのまとまった概念を説明するリスト
一緒に残すべきコードブロックとその説明

ステップ2：チャンク境界の決定

各チャンクは以下の条件を満たす必要があります。

自己完結型：単独で取得されたときに理解可能
焦点が絞られている：1つのメイントピックまたは密接に関連するサブトピックに集中
取得可能：スタンドアロンの回答断片として有用

サイズのガイドライン：

最小：約100トークン
目標：300～800トークン
最大：約1500トークン

トピックが変わる場合は、サイズ超過のチャンクを分割します。単独で成り立たない場合は、サイズ不足のチャンクをマージします。

ステップ3：候補エンティティの抽出

フロントマターを記述する前に、ドキュメントからドメイン固有のエンティティを抽出します。

以下を探します。

ハードスキル
ツールとライブラリ
フレームワーク
プラットフォーム
データベース
プロトコルと標準
アーキテクチャとデザインパターン
名前付きの製品やシステム

すべての名詞をエンティティに昇格させないでください。ナレッジグラフのノードとして意味をなす用語を優先します。

ステップ4：エンティティの正規化と重複排除

生の言及を標準的なエンティティに変換します。

正規化ルール：

最も認識されやすい標準名を使用する：PostgreSQL、postgresではない
エイリアスを1つのエンティティにマージする：JS -> JavaScript、K8s -> Kubernetes
頭字語と完全名の両方が実際にエイリアスとして使用されている場合のみ保持する
system、project、tool、computer、workなどの汎用的な用語を削除する
検索にとって意味的に重要ではない付随的な言及を削除する

何かがエンティティかどうか不明な場合は、以下を自問します。

これは関連知識のナビゲーションに役立つか？
これはスキルグラフ内で独自のノードを持つに値するか？
この用語でチャンクを取得すると意味のある結果が得られるか？

答えが「いいえ」の場合は、エンティティリストから除外します。

ステップ5：エンティティIDの生成

entity:{canonical-name}の形式を使用します。

例：

entity:python
entity:fastapi
entity:postgresql
entity:event-driven-architecture

IDはプレフィックス以降は小文字のkebab-caseである必要があります。

ステップ6：チャンクIDの生成

{category}:{topic}[-{subtopic}]の形式を使用します。

カテゴリ	使用例	例
`skill:`	技術スキル	`skill:python`、`skill:react-hooks`
`about:`	個人または組織の情報	`about:background`、`about:mission`
`project:`	プロジェクトの説明	`project:graphrag`、`project:api-v2`
`principle:`	ガイドラインと価値観	`principle:security-first`
`workflow:`	プロセス	`workflow:deployment`、`workflow:review`
`reference:`	参考資料	`reference:api-auth`、`reference:schema`

ステップ7：YAMLフロントマターの作成

entitiesとchunksの両方を定義します。

---
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: skill:python-api
    tags: [Python, Backend, API]
    entities: [entity:python, entity:fastapi]
    context: "REST APIとサービス実装に焦点を当てたPythonバックエンドスキル"
    created_at: "2026-03-08"
    version: 1
    type: text
    priority: high
    dependencies: []
  - id: skill:python-data
    tags: [Python, Data]
    entities: [entity:python, entity:pandas]
    context: "表形式分析とETL作業に焦点を当てたPythonデータ処理スキル"
    created_at: "2026-03-08"
    version: 1
    type: text
    priority: medium
    dependencies: []
---

ステップ8：チャンクをエンティティにリンク

各チャンクは、実際に議論している標準的なエンティティをリストする必要があります。

リンクルール：

チャンクにとって中心的なエンティティを含める
簡単に触れられているだけのエンティティはスキップする
チャンクあたり1～6個のエンティティを推奨
すべてのドキュメントエンティティをすべてのチャンクにコピーしない
2つのチャンクが異なる理由で同じエンティティに言及している場合は、contextでそれを区別する

ステップ9：コンテンツを`<Chunk>`タグでラップ

フロントマターのチャンクIDと一致する<Chunk>タグを適用します。

<Chunk id="skill:python-api">
## Python API作業

PythonとFastAPIを使用してREST APIや内部サービスを構築しています。
</Chunk>

ステップ10：検証とエクスポート

付属のスクリプトを使用します。

python3 scripts/validate_chunks.py document.md
python3 scripts/export_to_lancedb.py document.md --output chunks.json
python3 scripts/diagnose_chunks.py document.md --level suggest

エンティティルール

エンティティとしてカウントされるもの

以下を優先します。

具体的
複数のドキュメント間で再利用可能
グラフノードとして意味がある
検索や展開に有用

良い例：

Python
FastAPI
Docker
Kubernetes
CI/CD
Event-Driven Architecture
JWT

通常はエンティティではないもの：

experience
technology
feature
application
computer
problem
task

エンティティタイプ

以下のデフォルトタイプのいずれかを使用します。

skill
tool
library
framework
platform
database
architecture
protocol
concept
domain
product

どれも適切でない場合は、多数のカスタムタイプを発明する代わりにconceptを使用します。

ワールドモデルのエンティティタイプ

ワールドモデルやエージェントループに参加するドキュメントを構築する場合、以下の追加タイプが利用可能です。

state — ワールド状態ノード（例：entity:resume-parsed）
action — 実行可能なアクション（例：entity:analyze-resume）
goal — タスク目標（例：entity:learn-kubernetes-path）
agent — アクターまたはユーザー（例：entity:ian-chou）
evidence — 観測結果（例：entity:docker-3yr-experience）

ワールドモデルYAMLフィールド

ワールドモデルに参加するSKILL.mdファイルには、以下のオプションのYAMLフロントマターフィールドが含まれる場合があります。

---
name: analyze-resume
description: "生の履歴書を解析し、スキルの証拠を抽出する"
# === ワールドモデルフィールド（すべてオプション） ===
preconditions:
  - "entity:has-raw-resume"
  - "NOT entity:has-parsed-resume"
postconditions:
  - "entity:has-parsed-resume"
  - "entity:has-skill-evidence"
related_nodes:
  - "entity:resume-parsing"
  - "entity:skill-extraction"
related_skills:
  - "career-mapping"
  - "skill-gap-analysis"
cost: low
idempotent: true
---

フィールド	型	説明
`preconditions`	`string[]`	このスキルを実行する前に存在する必要がある状態エンティティ
`postconditions`	`string[]`	実行後に作成または更新される状態エンティティ
`related_nodes`	`string[]`	セマンティックグラフ内のアンカーポイント
`related_skills`	`string[]`	順次または補完的なスキル名
`cost`	`enum`	`low`、`medium`、`high` — 推定実行コスト
`idempotent`	`bool`	副作用なしで再実行しても安全かどうか

前提条件は否定にNOTプレフィックスを使用します（例："NOT entity:has-parsed-resume"はその状態が存在してはならないことを意味します）。

タグとエンティティの比較

タグは以下に使用します。

大まかな分類
フィルタリング
ドキュメント整理

エンティティは以下に使用します。

標準的な概念の同一性
チャンクからグラフへのリンク
類似性とトラバーサルワークフロー
ドキュメント間の概念の再利用

例：

タグ：Backend
エンティティ：entity:fastapi

フロントマタースキーマ

エンティティスキーマ

entities:
  - id: entity:fastapi
    name: FastAPI
    type: framework
    aliases: []

必須フィールド：

id
name
type

オプションフィールド：

aliases

チャンクスキーマ

chunks:
  - id: skill:python-api
    tags: [Python, Backend, API]
    entities: [entity:python, entity:fastapi]
    context: "FastAPIで構築されたREST APIに焦点を当てたPythonバックエンドスキル"
    created_at: "2026-03-08"
    version: 1
    type: text
    priority: high
    dependencies: []

推奨フィールド：

id
entities
context

オプションフィールド：

tags
created_at
version
type
priority
dependencies

コンテキスト記述ルール

各チャンクのcontextは以下を行う必要があります。

ドキュメント内でのチャンクの役割を説明する
識別可能なユースケースに言及する
リンクされたエンティティを自然に反映する
最初の文をそのままコピーしない

良い例：

"REST API、非同期サービス、FastAPIベースの実装に焦点を当てたPythonバックエンドスキル"

弱い例：

"このチャンクはPythonについて話しています"

変換例

変換前

## 私について

私はAPIと分散システムに重点を置いたバックエンドエンジニアです。

## Python

REST APIや内部ツールにPythonを使用しています。

### 主要ライブラリ
- FastAPI（ウェブサービス用）
- Pandas（データ処理用）

変換後

---
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, Experience]
    entities: []
    context: "APIと分散システムに取り組むバックエンドエンジニアとしての職歴"
    created_at: "2026-03-08"
    version: 1
    type: text
    priority: medium
    dependencies: []
  - id: skill:python
    tags: [Python, Backend]
    entities: [entity:python, entity:fastapi, entity:pandas]
    context: "API開発、サービス作業、データ処理のためのPythonスキル"
    created_at: "2026-03-08"
    version: 1
    type: text
    priority: high
    dependencies: [about:background]
---

<Chunk id="about:background">
## 私について

私はAPIと分散システムに重点を置いたバックエンドエンジニアです。
</Chunk>

<Chunk id="skill:python">
## Python

REST APIや内部ツールにPythonを使用しています。

### 主要ライブラリ
- FastAPI（ウェブサービス用）
- Pandas（データ処理用）
</Chunk>

GraphRAGガイダンス

グラフ指向の検索用にドキュメントを準備する場合：

entitiesを標準的なノードインベントリとして扱う
チャンクのentities配列をチャンクからエンティティへのエッジとして扱う
dependenciesをチャンク間の前提条件リンクとして扱う
タグは広く、エンティティは正確に保つ

エンティティベースのナビゲーションが目標の場合、タグだけに依存しないでください。

多くのエンティティを抽出しない場合

以下の場合は控えめにします。

ドキュメントが非常に短い場合
ドキュメントが主にナラティブでドメイン用語が少ない場合
同じ概念が有用な区別なしに繰り返されている場合
ソースがノイズが多く、エンティティ抽出がジャンクノードを生成する場合

これらの場合、より小さくクリーンなエンティティセットを返します。

バリデーション

変換後、以下を確認します。

すべての<Chunk> IDがchunksに存在すること
すべてのchunks[].entities参照がentitiesに存在すること
エンティティIDが一意で標準的であること
チャンクIDが一意であること
ネストされたチャンクが存在しないこと
contextフィールドが類似チャンクを区別していること
汎用的またはノイズの多いエンティティが削除されていること

python3 scripts/validate_chunks.py path/to/document.md

診断

ユーザーが診断を依頼した場合、チャンクの品質とエンティティの品質の両方を確認します。

チェックカテゴリ

チャンクの類似性
- 検索時に区別がつかないほど類似しているチャンクをフラグ付けする
コンテキスト品質
- 曖昧、反復的、または過度に短いコンテキストフィールドをフラグ付けする
タグの重複
- あらゆる場所に出現し、フィルタリングに役立たなくなったタグをフラグ付けする
エンティティノイズ
- 汎用的または低価値のエンティティをフラグ付けする
エンティティの重複
- 1つの標準的なノードにマージされるべきエイリアスをフラグ付けする
チャンクとエンティティのリンク
- 欠落、過剰、または無関係なエンティティリンクを持つチャンクをフラグ付けする

診断プロンプト

診断のみ：

このドキュメントのチャンクとエンティティの品質問題をチェックしてください

…

[翻訳切り詰め]

お気に入りのAIに質問する

ドキュメント