Open Knowledge Format (OKF)

Habilidade Open Knowledge Format (OKF)

O OKF representa conhecimento como um diretório de arquivos markdown com frontmatter YAML. É mínimo por design: sem registro de esquema, sem runtime, sem SDK. Seu trabalho é produzir, manter e consumir bundles OKF conformes com a especificação, não com sua memória dela.

Sempre leia a especificação canônica antes de trabalho não trivial: reference/SPEC.md. Ela é a especificação literal OKF v0.1 e a fonte da verdade para cada regra abaixo.

A única regra rígida

Um bundle é conforme (§9) se, e somente se: todo arquivo .md não reservado tiver um bloco de frontmatter YAML analisável, e todo bloco tiver um campo type não vazio. Todo o resto é orientação flexível. CONSUMIDORES DEVEM tolerar campos opcionais ausentes, tipos desconhecidos e links quebrados — nunca rejeitar um bundle por causa deles.

Convenções a aplicar

• Um conceito = um arquivo. O caminho do arquivo (menos .md) é o ID do conceito.
• Frontmatter: type é obrigatório. Adicione title, description, tags, timestamp (ISO 8601) quando auxiliarem no consumo; adicione resource (uma URI canônica) apenas para conceitos vinculados a um ativo real — omita para conceitos abstratos.
• Corpo: prefira markdown estrutural (cabeçalhos, tabelas, listas, código em bloco). Cabeçalhos convencionais: # Schema, # Exemplos, # Citações.
• Links cruzados: links markdown padrão; prefira a forma absoluta relativa ao bundle (/services/auth-api.md). Um link afirma um relacionamento; seu tipo reside na prosa circundante, não no link.
• Arquivos reservados: index.md (listagem de diretório, sem frontmatter — exceto o índice raiz do bundle pode carregar apenas okf_version) e log.md (histórico de alterações datadas ISO, mais recente primeiro). Nunca use esses nomes para conceitos.

Modelos a copiar: conceito, índice, log.

Localização padrão do bundle

Use .okf/ na raiz do repositório, a menos que o projeto já use outro local. Commita-o junto com o código que descreve — conhecimento como código.

Modos

produzir — criar ou estender um bundle

1. Leia reference/SPEC.md.
2. Escolha a(s) fonte(s): código (derive conceitos de código, READMEs, docstrings, config), docs/wiki (destile páginas em conceitos, link os originais sob # Citações), manual (decisões, playbooks, métricas).
3. Escolha um layout de diretório por domínio (ex.: services/, datasets/, decisions/). Um conceito por arquivo.
4. Escreva cada conceito a partir de templates/concept.md: defina um type descritivo, preencha campos recomendados, faça links cruzados para conceitos relacionados.
5. Adicione/atualize index.md por diretório (e okf_version: "0.1" no índice raiz). Acrescente uma entrada datada em log.md.
6. Valide (veja abaixo). Corrija todo erro antes de finalizar.

manter — manter um bundle sincronizado com a realidade

1. Identifique quais conceitos a alteração afeta (pesquise por resource, caminho ou tópico). Essa manutenção de registros é exatamente onde agentes são bons — toque em todo arquivo afetado em uma passada.
2. Atualize o corpo e timestamp; corrija ou adicione links cruzados; crie novos conceitos para novos ativos; marque ativos removidos (**Depreciação**) em vez de deletar contexto silenciosamente.
3. Atualize os arquivos index.md relevantes e acrescente uma entrada datada em log.md descrevendo o que mudou.
4. Valide.

consumir — usar um bundle como contexto

1. Leia primeiro o index.md raiz do bundle para divulgação progressiva, depois siga links apenas para os conceitos relevantes à tarefa.
2. Trate links quebrados como conhecimento ainda não escrito, não como erros.
3. Se aprender algo duradouro durante o trabalho, mude para manter e escreva de volta.

Validação (faça isso antes de declarar concluído)

Nunca verifique conformidade visualmente — execute o verificador determinístico. Invoque a habilidade validate companheira (/okf:validate <bundle-dir> --strict), que inclui o verificador. Se essa habilidade não estiver instalada, execute-a diretamente:

uv run "${CLAUDE_SKILL_DIR}/../validate/scripts/okf_validate.py" <bundle-dir> --strict

Resolva todo ERROR (falhas rígidas §9). Avisos são flexíveis; corrija-os quando baratos, mas eles nunca bloqueiam.