ctxfst/skill-chunk-md

Skill Chunk MD

Markdown을 의미 기반 <Chunk> 태그, 구조화된 프론트매터, 명시적 엔티티 계층을 포함한 CtxFST 문서로 변환합니다.

목표

이 스킬을 사용하여 다음을 모두 지원하는 문서를 생성합니다:

1. 청크 검색 - 세부 컨텍스트 제공
2. 엔티티 검색 - 탐색, 그래프 확장, 관련 개념 발견

단순히 텍스트를 분할하지 마십시오. 중요한 도메인 엔티티를 추출하고, 정규화하며, 각 청크를 해당 청크가 실제로 논의하는 엔티티에 연결하십시오.

레이아웃 선택

소스가 노트 형태인지 메모리 형태인지 초기에 결정하십시오:

• 노트 형태 (프로필 하나, 벤치마크 하나, 회의록 하나): 아래 설명된 표준 다중 엔티티-파일 레이아웃을 사용합니다.
• 메모리 형태 (시간이 지나며 성장하는 지식 베이스, 엔티티별 서류, 에이전트 메모리): 엔티티 중심 규칙을 사용합니다 — 파일당 하나의 엔티티, 파일 이름은 entity-<id-접미사>.ctxfst.md, entities: 필드는 정확히 하나의 소유자, 모든 청크는 소유자를 참조합니다. 교차 참조는 엔티티 ID를 사용하며 다른 파일로 해석됩니다.

엔티티 중심은 스키마 변경이 아닌 규칙입니다. 동일한 프론트매터 규칙이 적용됩니다. 차이점은 len(entities) == 1이고 파일 이름이 소유자를 포함한다는 것입니다. 작업 예제는 assets/examples/entity-centric/를 참조하고, python3 scripts/validate_chunks.py <경로> --entity-centric로 검증하십시오.

대상 형식

CtxFST 문서는 다음을 포함해야 합니다:

1. YAML 프론트매터
2. 문서 수준의 entities 카탈로그
3. 문서 수준의 chunks 카탈로그
4. <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에서 의미 경계를 식별합니다:

• 새로운 주제를 소개하는 헤더 (##, ###)
• 긴 섹션 내의 주제 전환
• 하나의 일관된 개념을 설명하는 목록
• 함께 유지되어야 하는 코드 블록과 그 설명

2단계: 청크 경계 결정

각 청크는 다음을 충족해야 합니다:

• 자체 완결적: 단독으로 검색될 때 이해 가능해야 함
• 집중적: 하나의 주요 주제 또는 밀접하게 관련된 하위 주제에 집중
• 검색 가능: 독립적인 답변 조각으로 유용해야 함

크기 지침:

• 최소: ~100 토큰
• 목표: 300-800 토큰
• 최대: ~1500 토큰

주제가 변경되면 크기가 큰 청크를 분할하십시오. 자체적으로 서 있을 수 없는 경우 크기가 작은 청크를 병합하십시오.

3단계: 후보 엔티티 추출

프론트매터를 작성하기 전에, 문서에서 도메인별 엔티티를 추출합니다.

찾아야 할 항목:

• 하드 스킬
• 도구 및 라이브러리
• 프레임워크
• 플랫폼
• 데이터베이스
• 프로토콜 및 표준
• 아키텍처 및 디자인 패턴
• 명명된 제품 또는 시스템

모든 명사를 엔티티로 승격시키지 마십시오. 지식 그래프에서 노드로서 의미가 있을 용어를 선호하십시오.

4단계: 엔티티 정규화 및 중복 제거

원시 언급을 정규 엔티티로 변환합니다.

정규화 규칙:

• 가장 인식 가능한 정규 이름 사용: postgres가 아닌 PostgreSQL
• 별칭을 하나의 엔티티로 병합: JS -> JavaScript, K8s -> Kubernetes
• 약어와 전체 이름이 실제로 별칭으로 사용되는 경우에만 유지
• system, project, tool, computer, work와 같은 일반 용어 제거
• 검색에 의미적으로 중요하지 않은 우연한 언급 제거

엔티티인지 확실하지 않은 경우, 다음 질문을 해보십시오:

1. 관련 지식 탐색에 도움이 되는가?
2. 스킬 그래프에서 자체 노드를 가질 가치가 있는가?
3. 이 용어로 청크를 검색하면 의미 있는 결과가 나오는가?

대답이 '아니오'라면 엔티티 목록에서 제외하십시오.

5단계: 엔티티 ID 생성

형식 사용: entity:{정규-이름}

예시:

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

ID는 접두사 뒤에 소문자 케밥 케이스여야 합니다.

6단계: 청크 ID 생성

형식 사용: {카테고리}:{주제}[-{하위주제}]

카테고리	사용 사례	예시
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개의 엔티티를 선호
• 모든 문서 엔티티를 모든 청크에 복사하지 않음
• 두 청크가 다른 이유로 동일한 엔티티를 언급하는 경우 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"는 해당 상태가 존재하지 않아야 함을 의미).

태그 vs 엔티티

태그는 다음에 사용합니다:

• 광범위한 분류
• 필터링
• 문서 구성

엔티티는 다음에 사용합니다:

• 정규 개념 식별
• 청크-그래프 연결
• 유사성 및 탐색 워크플로우
• 문서 간 개념 재사용

예시:

• 태그: 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 for web services
- Pandas for data processing

변환 후

---
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 for web services
- Pandas for data processing
</Chunk>

GraphRAG 가이드

그래프 기반 검색을 위한 문서를 준비할 때:

• entities를 정규 노드 인벤토리로 취급
• 청크 entities 배열을 청크-엔티티 엣지로 취급
• dependencies를 청크 간 전제 조건 링크로 취급
• 태그는 넓게 유지하고 엔티티는 정밀하게 유지

엔티티 기반 탐색이 목표일 때 태그에만 의존하지 마십시오.

많은 엔티티를 추출하지 않아야 할 경우

다음과 같은 경우 보수적으로 접근하십시오:

• 문서가 매우 짧은 경우
• 문서가 대부분 서사적이고 도메인 용어가 거의 없는 경우
• 동일한 개념이 유용한 구분 없이 반복되는 경우
• 소스가 노이즈가 많고 엔티티 추출이 정크 노드를 생성할 경우

이러한 경우 더 작고 깔끔한 엔티티 세트를 반환하십시오.

검증

변환 후, 다음을 확인하십시오:

1. 모든 <Chunk> ID가 chunks에 존재하는지
2. 모든 chunks[].entities 참조가 entities에 존재하는지
3. 엔티티 ID가 고유하고 정규화되었는지
4. 청크 ID가 고유한지
5. 중첩된 청크가 없는지
6. Context 필드가 유사한 청크를 구분하는지
7. 일반적이거나 노이즈가 많은 엔티티가 제거되었는지

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

진단

사용자가 진단을 요청하면 청크 품질과 엔티티 품질을 모두 검토하십시오.

확인 카테고리

1. 청크 유사성
   • 검색 중에 구분하기 어려울 정도로 너무 유사한 청크 플래그
2. 컨텍스트 품질
   • 모호하거나, 반복적이거나, 지나치게 짧은 컨텍스트 필드 플래그
3. 태그 중복
   • 모든 곳에 나타나 필터링에 더 이상 도움이 되지 않는 태그 플래그
4. 엔티티 노이즈
   • 일반적이거나 가치가 낮은 엔티티 플래그
5. 엔티티 중복
   • 하나의 정규 노드로 병합되어야 하는 별칭 플래그
6. 청크-엔티티 연결
   • 누락되었거나, 과도하거나, 관련 없는 엔티티 링크가 있는 청크 플래그

진단 프롬프트

진단 전용:

이 문서의 청크 및 엔티티 품질 문제를 확인해주세요.