Skill Chunk MD

Transforme Markdown em documentos CtxFST com tags <Chunk> semânticas, frontmatter estruturado e uma camada explícita de entidades.

Objetivo

Use esta habilidade para produzir documentos que suportem:

Recuperação de chunks para contexto detalhado
Recuperação de entidades para navegação, expansão de grafos e descoberta de conceitos relacionados

Não apenas divida o texto. Extraia também as entidades de domínio importantes, normalize-as e vincule cada chunk às entidades que realmente discute.

Escolhendo um Layout

Decida cedo se a fonte tem formato de nota ou de memória:

Formato de nota (um perfil, um benchmark, um registro de reunião): use o layout padrão multi-entidade-por-arquivo descrito abaixo.
Formato de memória (uma base de conhecimento que cresce com o tempo, dossiês por entidade, memória de agente): use a convenção Entidade-Cêntrica — um arquivo por entidade, nome do arquivo entidade-<id-sufixo>.ctxfst.md, entities: com exatamente um proprietário, cada chunk referenciando o proprietário. Referências cruzadas usam IDs de entidade e resolvem para outros arquivos.

Entidade-cêntrica é uma convenção, não uma mudança de esquema. As mesmas regras de frontmatter se aplicam; a diferença é que len(entities) == 1 e o nome do arquivo carrega o proprietário. Veja assets/examples/entity-centric/ para um exemplo prático e valide com python3 scripts/validate_chunks.py <caminho> --entity-centric.

Formato Alvo

Documentos CtxFST devem conter:

Frontmatter YAML
Catálogo de entities no nível do documento
Catálogo de chunks no nível do documento
Conteúdo do corpo envolto em tags <Chunk>

---
title: "Título do Documento"
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: "Trabalho backend em Python focado em APIs construídas com FastAPI"
---

<Chunk id="skill:python-api">
## Trabalho com API Python
Uso Python e FastAPI para construir APIs REST...
</Chunk>

Princípio Central

Use chunks como o portador de conteúdo e entidades como o índice semântico.

Chunks respondem: "Que passagem exata deve ser recuperada?"
Entidades respondem: "A que conceito essa passagem pertence?"

Tags são úteis para filtragem ampla. Entidades são os nós canônicos do grafo.

Fluxo de Trabalho Central

Passo 1: Analisar a Estrutura do Documento

Identifique limites semânticos no Markdown de origem:

Cabeçalhos (##, ###) que introduzem um novo tópico
Mudanças temáticas dentro de seções longas
Listas que descrevem um conceito coeso
Blocos de código junto com sua explicação quando devem permanecer juntos

Passo 2: Determinar Limites dos Chunks

Cada chunk deve ser:

Autocontido: compreensível quando recuperado sozinho
Focado: centrado em um tópico principal ou subtópico intimamente relacionado
Recuperável: útil como um fragmento de resposta independente

Diretrizes de tamanho:

Mínimo: ~100 tokens
Alvo: 300-800 tokens
Máximo: ~1500 tokens

Divida chunks muito grandes quando o tópico mudar. Mescle chunks muito pequenos quando não puderem ser independentes.

Passo 3: Extrair Entidades Candidatas

Antes de escrever o frontmatter, extraia as entidades específicas de domínio do documento.

Procure por:

Habilidades técnicas
Ferramentas e bibliotecas
Frameworks
Plataformas
Bancos de dados
Protocolos e padrões
Arquiteturas e padrões de design
Produtos ou sistemas nomeados

Não promova todo substantivo a entidade. Prefira termos que fariam sentido como nós em um grafo de conhecimento.

Passo 4: Normalizar e Desduplicar Entidades

Converta menções brutas em entidades canônicas.

Regras de normalização:

Use o nome canônico mais reconhecível: PostgreSQL, não postgres
Mescle aliases em uma entidade: JS -> JavaScript, K8s -> Kubernetes
Mantenha acrônimo + nome completo apenas quando ambos são genuinamente usados como aliases
Remova termos genéricos como sistema, projeto, ferramenta, computador, trabalho
Remova menções incidentais que não são semanticamente importantes para recuperação

Se não tiver certeza se algo é uma entidade, pergunte:

Isso ajudaria a navegar por conhecimento relacionado?
Isso mereceria seu próprio nó em um grafo de habilidades?
Recuperar chunks por este termo produziria resultados significativos?

Se a resposta for não, mantenha fora da lista de entidades.

Passo 5: Gerar IDs de Entidade

Use o formato: entity:{nome-canônico}

Exemplos:

entity:python
entity:fastapi
entity:postgresql
entity:arquitetura-orientada-a-eventos

IDs devem estar em minúsculas com hífens após o prefixo.

Passo 6: Gerar IDs de Chunk

Use o formato: {categoria}:{tópico}[-{subtópico}]

Categoria	Caso de Uso	Exemplos
`skill:`	Habilidades técnicas	`skill:python`, `skill:react-hooks`
`about:`	Informações pessoais ou organizacionais	`about:background`, `about:missao`
`project:`	Descrições de projetos	`project:graphrag`, `project:api-v2`
`principle:`	Diretrizes e valores	`principle:seguranca-primeiro`
`workflow:`	Processos	`workflow:deployment`, `workflow:revisao`
`reference:`	Material de referência	`reference:api-auth`, `reference:schema`

Passo 7: Criar Frontmatter YAML

Defina tanto entities quanto chunks.

---
title: "Meu Documento de Habilidades"
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: "Habilidades backend em Python focadas em APIs REST e implementação de serviços"
    created_at: "2026-03-08"
    version: 1
    type: text
    priority: high
    dependencies: []
  - id: skill:python-dados
    tags: [Python, Dados]
    entities: [entity:python, entity:pandas]
    context: "Habilidades de processamento de dados em Python focadas em análise tabular e trabalhos ETL"
    created_at: "2026-03-08"
    version: 1
    type: text
    priority: medium
    dependencies: []
---

Passo 8: Vincular Chunks a Entidades

Cada chunk deve listar as entidades canônicas que realmente discute.

Regras de vinculação:

Inclua entidades que são centrais para o chunk
Pule entidades que aparecem apenas de passagem
Prefira 1-6 entidades por chunk
Não copie todas as entidades do documento em cada chunk
Se dois chunks mencionam a mesma entidade por razões diferentes, diferencie isso em context

Passo 9: Envolver Conteúdo com Tags `<Chunk>`

Aplique tags <Chunk> que correspondam aos IDs de chunk do frontmatter.

<Chunk id="skill:python-api">
## Trabalho com API Python

Uso Python e FastAPI para construir APIs REST e serviços internos.
</Chunk>

Passo 10: Validar e Exportar

Use os scripts incluídos:

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

Regras de Entidade

O que conta como uma entidade

Prefira entidades que sejam:

Específicas
Reutilizáveis entre documentos
Significativas como nós de grafo
Úteis para recuperação ou expansão

Bons exemplos:

Python
FastAPI
Docker
Kubernetes
CI/CD
Arquitetura Orientada a Eventos
JWT

Geralmente não são entidades:

experiência
tecnologia
funcionalidade
aplicação
computador
problema
tarefa

Tipos de entidade

Use um destes tipos padrão:

skill
tool
library
framework
platform
database
architecture
protocol
concept
domain
product

Se nenhum se encaixar bem, use concept em vez de inventar muitos tipos personalizados.

Tipos de entidade do World Model

Ao construir documentos que participam de um world model ou loop de agente, estes tipos adicionais estão disponíveis:

state — nó de estado do mundo (ex.: entity:curriculo-analisado)
action — ação executável (ex.: entity:analisar-curriculo)
goal — objetivo da tarefa (ex.: entity:aprender-caminho-kubernetes)
agent — ator ou usuário (ex.: entity:ian-chou)
evidence — resultado de observação (ex.: entity:experiencia-docker-3-anos)

Campos YAML do World Model

Arquivos SKILL.md que participam de um world model podem incluir estes campos opcionais de frontmatter YAML:

---
name: analisar-curriculo
description: "Analisar currículo bruto e extrair evidências de habilidades"
# === Campos do World Model (todos opcionais) ===
preconditions:
  - "entity:tem-curriculo-bruto"
  - "NOT entity:tem-curriculo-analisado"
postconditions:
  - "entity:tem-curriculo-analisado"
  - "entity:tem-evidencia-habilidades"
related_nodes:
  - "entity:analise-curriculo"
  - "entity:extracao-habilidades"
related_skills:
  - "mapeamento-carreira"
  - "analise-lacuna-habilidades"
cost: low
idempotent: true
---

Campo	Tipo	Descrição
`preconditions`	`string[]`	Entidades de estado que devem existir antes que esta skill possa executar
`postconditions`	`string[]`	Entidades de estado criadas ou atualizadas após a execução
`related_nodes`	`string[]`	Pontos de ancoragem no grafo semântico
`related_skills`	`string[]`	Nomes de habilidades sequenciais ou complementares
`cost`	`enum`	`low`, `medium`, `high` — custo estimado de execução
`idempotent`	`bool`	Se é seguro reexecutar sem efeitos colaterais

Preconditions usam prefixo NOT para negação (ex.: "NOT entity:tem-curriculo-analisado" significa que esse estado não deve existir).

Tags vs entidades

Use tags para:

classificação ampla
filtragem
organização de documentos

Use entidades para:

identidade canônica de conceito
vinculação chunk-para-grafo
fluxos de similaridade e travessia
reutilização de conceitos entre documentos

Exemplo:

Tag: Backend
Entidade: entity:fastapi

Esquema de Frontmatter

Esquema de entidade

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

Campos obrigatórios:

id
name
type

Campo opcional:

aliases

Esquema de chunk

chunks:
  - id: skill:python-api
    tags: [Python, Backend, API]
    entities: [entity:python, entity:fastapi]
    context: "Habilidades backend em Python focadas em APIs REST construídas com FastAPI"
    created_at: "2026-03-08"
    version: 1
    type: text
    priority: high
    dependencies: []

Campos recomendados:

id
entities
context

Campos opcionais:

tags
created_at
version
type
priority
dependencies

Regras de Escrita de Contexto

Cada context de chunk deve:

explicar o papel do chunk no documento
mencionar o caso de uso distintivo
refletir as entidades vinculadas naturalmente
evitar copiar a primeira frase literalmente

Bom:

"Habilidades backend em Python focadas em APIs REST, serviços assíncronos e implementação baseada em FastAPI"

Fraco:

"Este chunk fala sobre Python"

Exemplo de Transformação

Antes

## Sobre Mim

Sou um engenheiro backend focado em APIs e sistemas distribuídos.

## Python

Uso Python para APIs REST e ferramentas internas.

### Bibliotecas Principais
- FastAPI para serviços web
- Pandas para processamento de dados

Depois

---
title: "Perfil"
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: [Sobre, Experiência]
    entities: []
    context: "Histórico profissional como engenheiro backend trabalhando em APIs e sistemas distribuídos"
    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: "Habilidades em Python para desenvolvimento de API, trabalho com serviços e processamento de dados"
    created_at: "2026-03-08"
    version: 1
    type: text
    priority: high
    dependencies: [about:background]
---

<Chunk id="about:background">
## Sobre Mim

Sou um engenheiro backend focado em APIs e sistemas distribuídos.
</Chunk>

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

Uso Python para APIs REST e ferramentas internas.

### Bibliotecas Principais
- FastAPI para serviços web
- Pandas para processamento de dados
</Chunk>

Orientação para GraphRAG

Ao preparar documentos para recuperação orientada a grafos:

Trate entities como o inventário canônico de nós
Trate os arrays entities dos chunks como arestas chunk-para-entidade
Trate dependencies como links de pré-requisito chunk-para-chunk
Mantenha tags amplas e entidades precisas

Não confie apenas em tags quando o objetivo é navegação baseada em entidade.

Quando Não Extrair Muitas Entidades

Seja conservador quando:

o documento é muito curto
o documento é principalmente narrativo com poucos termos de domínio
o mesmo conceito é repetido sem distinções úteis
a fonte é ruidosa e a extração de entidades criaria nós inúteis

Nestes casos, retorne um conjunto de entidades menor e mais limpo.

Validação

Após a conversão, verifique:

Cada ID de <Chunk> existe em chunks
Cada referência chunks[].entities existe em entities
IDs de entidade são únicos e canônicos
IDs de chunk são únicos
Não existem chunks aninhados
Campos de contexto diferenciam chunks semelhantes
Entidades genéricas ou ruidosas foram removidas

python3 scripts/validate_chunks.py caminho/para/documento.md

Diagnóstico

Quando o usuário pedir para diagnosticar, revise tanto a qualidade dos chunks quanto a qualidade das entidades.

Categorias de verificação

Similaridade de chunks
- Sinalize chunks muito semelhantes para distinguir durante a recuperação
Qualidade do contexto
- Sinalize campos de contexto vagos, repetitivos ou excessivamente curtos
Sobreposição de tags
- Sinalize tags que aparecem em todos os lugares e não ajudam mais na filtragem
Ruído de entidades
- Sinalize entidades genéricas ou de baixo valor
Duplicação de entidades
- Sinalize aliases que devem ser mesclados em um nó canônico
Vinculação chunk-para-entidade
- Sinalize chunks com links de entidade ausentes, excessivos ou irrelevantes

Prompts de diagnóstico

Diagnosticar apenas:

Verifique este documento em busca de problemas de qualidade de chunk e entidade

…

[truncado para tradução]

Perguntar na sua IA favorita

Documentação