CommunityEscrita e Ediçãogithub.com

kricha/knowledge-capture

Skill de agente para salvar capturas de conhecimento raw no repositório local.

O que é knowledge-capture?

Este skill permite que um agente (como Claude Code, Cursor ou Codex) crie e atualize automaticamente capturas de conhecimento no formato raw no repositório local. Ele foi projetado para preservar detalhes úteis do fluxo de trabalho atual—como mudanças em arquivos, decisões, descobertas e próximos passos—em arquivos Markdown armazenados em `.ai/raw/`. O skill gerencia um arquivo de ponteiro (`active-session.json`) que indica qual captura está ativa para o workflow em andamento. Ele suporta tipos de captura como `session`, `discussion`, `investigation`, `decision` e `handoff`, e pode ser usado tanto manualmente via comandos `/capture` quanto automaticamente no final de uma resposta, se houver mudanças ou decisões relevantes. O skill inclui um helper Node.js opcional (sem dependências) para criar ou atualizar capturas, mas também permite a criação direta de arquivos Markdown. É útil para manter um registro contínuo do trabalho do agente, facilitando retomadas, compactação e transferência de contexto entre sessões.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add kricha/knowledge-capture

Installed? Explore more Escrita e Edição skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Captura de Conhecimento

Uso automático

Antes da resposta final para qualquer tarefa do repositório, se arquivos foram alterados, testes executados ou uma decisão/descoberta/acompanhamento foi feita, crie ou atualize exatamente uma captura de sessão ativa para a sessão/fluxo de trabalho atual. Faça isso após a verificação e antes de pedir limpeza do backlog ou aprovação.

Não crie uma nova captura apenas porque o skill foi invocado novamente. Se um caminho de captura ativa for conhecido para este fluxo de trabalho, atualize esse arquivo. Caso contrário, leia .ai/raw/active-session.json como um ponteiro candidato ativo. Se não existir uma captura ativa confiável ou o fluxo de trabalho tiver mudado claramente, crie uma nova captura raw e substitua o ponteiro.

Capture detalhes suficientes da tarefa atual para uso posterior. Leia/atualize apenas a captura ativa para o fluxo de trabalho atual; não leia, atualize, deduplique, mescle, sincronize, faça commit, publique ou promova capturas não relacionadas na v0.2.

Uma captura não está completa apenas porque o auxiliar escreveu um arquivo. Não deixe Não capturado. em seções cujos fatos são conhecidos, especialmente Solicitação do usuário, Mudanças e evidências, Decisões e descobertas e Perguntas em aberto e próximos passos.

Ao atualizar uma captura ativa, escreva a captura inteira como ela deve ficar após a etapa atual do fluxo de trabalho. Não acrescente uma nota apenas de delta. Use o contexto da tarefa atual, arquivos visíveis, diffs, testes, resultados de comandos e texto de transferência como evidência; se a continuidade não estiver clara, crie uma nova captura em vez de inventar contexto faltante.

Mantenha a captura alinhada com a realidade atual, não com cada pensamento intermediário. Se uma decisão anterior mudou e o trabalho mudou junto, capture a decisão/evidência final/atual. Mantenha a decisão substituída apenas quando ela explica código implementado, um rollback, um risco não resolvido ou uma pergunta em aberto; omita opções abandonadas puramente teóricas.

Armazene capturas como .ai/raw/<pasta-do-tipo>/YYYY-MM-DDTHH-mm-ssZ--<tipo>--<slug-do-tópico>.md. Se o nome de arquivo exato existir, acrescente --2, --3 e assim por diante antes de .md.

Tipos: session -> sessions, discussion -> discussions, investigation -> investigations, decision -> decisions, handoff -> handoffs.

Para capturas do tipo session, mantenha .ai/raw/active-session.json como um ponteiro local para a captura do fluxo de trabalho ativo. Não o limpe após cada resposta final; ele suporta retomada, compactação e transferência. Substitua-o quando uma nova captura de fluxo de trabalho for iniciada.

Captura

Trate /capture como criar/atualizar captura da sessão atual. Trate /capture <tipo> como aquele tipo de captura quando <tipo> for session, discussion, investigation, decision ou handoff.

Antes da compressão de contexto, compactação ou transferência, capture primeiro se trabalho ou decisões significativas ainda não tiverem sido capturados.

Se o Node estiver disponível, o auxiliar sem dependências pode criar a primeira captura, substituir a captura ativa conhecida com --update <caminho> ou substituir a captura apontada com --update-active. Passe detalhes ricos em seções via --stdin ou escreva Markdown diretamente. O auxiliar bloqueia capturas apenas com título/resumo por padrão, pois elas perdem conhecimento útil da sessão.

node .agents/skills/knowledge-capture/scripts/capture.js --type session --title "correção do token de refresh de autenticação" --summary "Corrigido comportamento do token de refresh expirado" --stdin
node .agents/skills/knowledge-capture/scripts/capture.js --type session --title "correção do token de refresh de autenticação" --update .ai/raw/sessions/2026-07-04T18-22-10Z--session--auth-refresh-token-fix.md --stdin
node .agents/skills/knowledge-capture/scripts/capture.js --type session --title "correção do token de refresh de autenticação" --update-active --stdin

Forneça cabeçalhos Markdown de references/raw-capture-schema.md no stdin. Se a execução do Node ou shell não estiver disponível, crie ou atualize o Markdown diretamente.

Use esta ordem para capturas de sessão ativa:

  1. Se o caminho ativo for conhecido no contexto atual, atualize esse caminho.
  2. Caso contrário, leia .ai/raw/active-session.json como um ponteiro candidato.
  3. Se tanto o ponteiro quanto o runtime expuserem um agent_session_id e eles coincidirem, atualize-o.
  4. Se o ID da sessão for diferente, estiver faltando ou não estiver disponível, mas a solicitação do usuário ou transferência claramente continuar o mesmo fluxo de trabalho, atualize-o e atualize o ponteiro.
  5. Caso contrário, crie uma nova captura e substitua o ponteiro. Nunca escolha por adivinhação do nome de arquivo mais recente.

Salvaguardas

  • Capture detalhes raw úteis, mas evite transcrições, logs grandes e arquivos inteiros.
  • Coloque arquivos alterados, testes, comandos e evidências sob Mudanças e evidências; agrupe arquivos por propósito quando vários arquivos foram alterados.
  • Inclua apenas comandos/resultados raros, não óbvios ou relevantes para decisões; omita comandos rotineiros que não importam depois.
  • Reorganize uma captura ativa apenas para torná-la precisa e útil; não invente fatos ou mantenha silenciosamente teoria obsoleta como se ainda fosse verdade.
  • Trate agent_session_id como uma salvaguarda útil, não a definição de um fluxo de trabalho. Uma nova sessão de agente pode continuar o mesmo fluxo de trabalho.
  • Use --agent-session-id apenas quando o runtime expuser claramente um ID estável de sessão, conversa, thread ou execução atual. Se não estiver disponível, omita-o. Nunca invente um.
  • Exclua segredos, credenciais, chaves de API, chaves privadas, dados privados do cliente e memória pessoal não relacionada.
  • Se conteúdo sensível estiver presente, não crie a captura; resuma abstratamente primeiro.
  • O estado raw/local vem do caminho .ai/raw/ e da política do skill, não de campos de captura por fluxo de trabalho.
  • Trate o auxiliar Node como opcional. A criação direta de arquivos ainda é válida.

Após salvar, reporte o caminho, o tipo e se foi criado ou atualizado. Se o auxiliar bloquear a captura, reporte o aviso e não salve o conteúdo raw.

Referências

  • Leia references/raw-capture-schema.md apenas ao escrever manualmente ou alterar o esquema.
  • Leia references/active-session-example.md quando não tiver certeza de como uma captura de fluxo de trabalho atualizada deve se parecer.
  • Leia references/agent-portability.md apenas ao adaptar este skill para outro agente.

Habilidades Relacionadas