neat-freak

Visão geral do skill neat-freak

neat-freak é um skill de limpeza de fim de sessão para projetos em que docs, memória do agente e código saem de sincronia. O skill neat-freak funciona melhor para technical writers, operadores de agentes e desenvolvedores que precisam de uma passagem de bastão confiável depois de uma feature, refactor ou milestone — não só um README mais bonito, mas uma base de conhecimento coerente, alinhada ao código atual.

A função central é simples: reconciliar a documentação do projeto, como CLAUDE.md, AGENTS.md e docs/, com a realidade, removendo orientações desatualizadas, unificando duplicatas e adicionando as regras que pessoas e agentes futuros realmente vão precisar. Isso torna o neat-freak especialmente útil em workflows de Technical Writing, em que precisão, qualidade da transição e prontidão para novos integrantes pesam mais do que polimento de texto.

O que diferencia o neat-freak

Ao contrário de um prompt genérico de “atualizar docs”, o neat-freak é opinativo sobre higiene da informação: ele trata a documentação como instruções operacionais vivas, não como um changelog. Ele também reconhece múltiplos ecossistemas de IA, então o mesmo skill pode ser usado em Claude Code, OpenAI Codex, OpenCode e OpenClaw com menos tentativa e erro.

Casos de uso mais indicados

Use o neat-freak quando você tiver:

• concluído uma etapa de desenvolvimento e precisar sincronizar a documentação antes da entrega
• instruções conflitantes ou desatualizadas entre arquivos markdown do projeto
• um novo colega ou agente que precise começar sem atrito
• um conjunto de docs que cresceu por acúmulo e agora precisa de poda

O que limita a adoção

Para esse skill ser útil, você precisa ter acesso à árvore do projeto e permissão para editar os arquivos de conhecimento. Ele ajuda menos em brainstorming pontual, revisão de texto isolada ou tarefas em que a fonte da verdade está, de propósito, fora do repositório.

Como usar o skill neat-freak

Instale e acione no contexto certo

Uma instalação típica do neat-freak começa pelo caminho do repositório e pelo nome do skill, por exemplo: npx skills add KKKKhazix/khazix-skills --skill neat-freak. Depois de instalado, acione-o no fim de uma sessão de trabalho ou sempre que docs e memória precisarem ser reconciliados. O skill foi pensado para responder a frases como “sync up”, “tidy up docs”, “update memory”, “clean up docs”, “/sync” ou “收尾”, então encaixa naturalmente em fluxos baseados em milestones.

Dê um briefing completo de limpeza

O uso forte do neat-freak começa com um limite bem definido: o que mudou, quais arquivos podem estar desatualizados e o que deve ser tratado como fonte autoritativa. Em vez de dizer “limpa a documentação”, diga algo como:

• “Mudamos o fluxo de auth e renomeamos uma env var; sincronize CLAUDE.md, README.md e docs/.”
• “Esta branch está pronta; reconcilie a memória com o código e remova notas antigas de setup.”
• “新人能直接上手: revise os docs de handoff, remova etapas duplicadas de setup e adicione qualquer red line que esteja faltando.”

Esse tipo de prompt ajuda o neat-freak a distinguir entre limpeza, consolidação e documentação de onboarding.

Leia estes arquivos primeiro

O repositório aponta um caminho prático de partida: SKILL.md primeiro, depois references/agent-paths.md e references/sync-matrix.md para caminhos de plataforma e regras de sincronização. Essas referências são as leituras de maior valor porque mostram onde o conhecimento está guardado e o que deve ser adicionado ou removido, o que é mais útil do que vasculhar o repositório inteiro às cegas.

Dicas de workflow que melhoram o resultado

Trate o neat-freak como uma passagem de reconciliação, não como uma reescrita. Primeiro identifique os fatos do projeto que precisam sobreviver à próxima sessão, depois remova o ruído histórico e só então acrescente as orientações que faltam. Isso é especialmente importante quando o repositório tem docs separadas para operators, agents e newcomers, porque cada público precisa de um nível de detalhe diferente.

FAQ do skill neat-freak

O neat-freak é só para Technical Writing?

Não. O neat-freak para Technical Writing é uma ótima combinação porque o skill foi construído em torno de precisão documental e qualidade de handoff, mas developers e operadores de agentes de IA também podem usá-lo quando precisam que o conhecimento do projeto acompanhe a implementação.

Em que o neat-freak difere de um prompt normal?

Um prompt normal pode pedir limpeza de docs, mas o neat-freak adiciona intenção de workflow: ele procura instruções desatualizadas, divergência entre arquivos e quais são os arquivos certos para atualizar para o próximo agente. Isso reduz o risco de você polir só um documento e deixar orientações conflitantes em outros lugares.

Quando eu não devo usar o skill neat-freak?

Evite usá-lo quando o projeto ainda estiver em exploração, quando a documentação for intencionalmente provisória ou quando ainda não houver uma base estável de código ou processo. Ele também é uma opção ruim se você só precisa editar um único parágrafo e não existe uma reconciliação mais ampla de conhecimento a fazer.

O skill neat-freak é amigável para iniciantes?

Sim, desde que você aponte para o repositório e nomeie a milestone. Iniciantes costumam ter resultados melhores quando especificam a área alterada, o público-alvo e se querem limpeza, preparação de handoff ou reconciliação de memória.

Como melhorar o skill neat-freak

Comece pelos fatos de maior valor

Os melhores resultados com o neat-freak vêm de dizer o que é definitivamente verdade agora: novas features, conceitos renomeados, premissas quebradas ou etapas de setup alteradas. Se isso ficar implícito, o skill pode preservar material desatualizado porque não tem como inferir com segurança o que deve ser apagado.

Dê o contexto certo, não só o sintoma

Uma entrada fraca diz “as docs estão bagunçadas”. Uma entrada melhor diz “CLAUDE.md ainda menciona o caminho antigo de deploy, o README duplica as etapas de setup e o doc de handoff precisa refletir as novas env vars”. Essa especificidade ajuda o neat-freak a decidir se deve mesclar, mover ou remover informação.

Fique atento aos modos de falha mais comuns

A falha mais comum é reter demais detalhes históricos que já não ajudam o próximo agente. A segunda é atualizar regras do projeto em um arquivo enquanto deixa a mesma regra contradita em outro. Use o guia do neat-freak para forçar uma passagem completa pelas superfícies de conhecimento relevantes, em vez de parar no primeiro ajuste aceitável.

Faça iteração depois da primeira passada

Depois que o neat-freak fizer as edições, compare a saída com a árvore real do repositório e pergunte o que um novo contribuidor ainda poderia não saber. Se a resposta for “setup”, “ownership”, “red lines” ou “onde ler primeiro”, devolva isso explicitamente e rode a limpeza de novo com essas lacunas nomeadas.