promote

Visão geral do promote skill

O que o promote faz

O promote skill transforma um comportamento repetido e já validado do Claude, antes registrado na memória automática, em uma regra explícita do projeto. Em vez de deixar um padrão útil escondido em MEMORY.md, o promote ajuda a movê-lo para CLAUDE.md, .claude/rules/<topic>.md ou para um arquivo global de instruções do Claude, para que o comportamento seja aplicado de forma consistente em sessões futuras.

Melhor uso em fluxos de Claude que se autoaperfeiçoam

Use o promote quando sua equipe já permite que o Claude aprenda com correções, preferências e convenções recorrentes do projeto, mas agora precisa transformar um desses aprendizados em algo durável. Ele é especialmente útil em configurações de Context Engineering, nas quais MEMORY.md registra observações e os arquivos de regras definem o que o agente deve seguir de forma confiável.

Bons exemplos incluem “sempre use pnpm neste repositório”, “handlers de API devem validar a entrada” ou “testes para código de billing exigem estes fixtures”. Maus exemplos são preferências pontuais, debates ainda não resolvidos ou regras que você ainda não viu funcionar na prática.

O que torna este promote skill útil

O skill não é apenas um lembrete para copiar e colar. Ele oferece um fluxo de decisão: esclarecer o padrão, localizar entradas de memória que o sustentem, escolher o arquivo de destino correto, escrever uma regra aplicável e preservar a memória original com uma nota de promoção. Isso importa porque a parte difícil não é editar markdown; é decidir se uma memória merece aplicação permanente e onde essa regra deve ficar.

Como usar o promote skill

Instalação do promote e caminho de leitura do repositório

Instale o skill a partir da coleção de skills no GitHub com:

npx skills add alirezarezvani/claude-skills --skill promote

Depois, leia SKILL.md primeiro. Atualmente, esse caminho do repositório expõe o fluxo do promote em um único arquivo, portanto não há scripts auxiliares, referências ou templates de regras para inspecionar. Isso simplifica a adoção, mas também significa que você deve revisar com atenção os exemplos de comandos e a tabela de seleção de destino antes de usá-lo em um repositório importante.

Como chamar o promote na prática

O gatilho esperado é /si:promote, seguido do padrão que você quer tornar permanente:

• /si:promote use pnpm instead of npm
• /si:promote API handlers need validation --target rules/api.md
• /si:promote tests for auth changes must include session expiry cases --target rules/testing.md --paths "src/auth/**/*.ts"

O skill primeiro verifica qual comportamento você quer dizer. Se a solicitação estiver vaga, ele deve fazer uma pergunta de esclarecimento, por exemplo se a regra se aplica globalmente ou apenas a determinados caminhos. Em seguida, ele pesquisa entradas relacionadas no arquivo de memória automática do Claude do projeto em ~/.claude/projects/.../memory/MEMORY.md, mostra as correspondências e confirma que a memória sustenta a promoção.

Como transformar uma ideia vaga em um bom prompt

Um prompt fraco diz: “promote our testing preference.” Um uso mais forte do promote informa o comportamento, a evidência, o escopo e o destino, se já forem conhecidos:

/si:promote "When changing billing code, add regression tests for failed payment and retry paths" --target rules/testing.md --paths "src/billing/**/*.ts"

Isso funciona melhor porque o skill consegue escrever uma regra aplicável, em vez de uma preferência vaga. Inclua:

• o comportamento exato que o Claude deve seguir
• se ele se aplica ao projeto inteiro, a tipos de arquivo selecionados ou a todos os projetos
• caminhos de exemplo, caso a regra tenha escopo específico
• a frase da memória ou o incidente que comprovou que o padrão é útil

Fluxo sugerido antes de fazer merge da regra

Depois que o promote criar ou editar a regra, revise-a como se fosse configuração de produção. Verifique se a instrução é curta, testável e não é mais ampla do que as evidências justificam. Para comportamentos em todo o projeto, CLAUDE.md geralmente é apropriado. Para comportamentos mais específicos, prefira .claude/rules/<topic>.md com escopo por caminho. Para uma convenção pessoal entre repositórios, use um arquivo global de instruções do Claude apenas se o padrão for realmente universal.

FAQ do promote skill

O promote é para Context Engineering ou para prompts em geral?

O promote é mais valioso em Context Engineering porque formaliza o caminho entre um comportamento observado e uma instrução persistente. Prompts gerais podem pedir ao Claude para lembrar algo durante uma sessão; o promote ajuda a decidir se esse aprendizado deve passar a fazer parte do contexto operacional do repositório.

Quando não devo usar o promote?

Não use o promote para ideias não testadas, soluções temporárias, preferências pessoais que entrem em conflito com normas da equipe ou instruções que deveriam estar no código da aplicação, em testes, linters ou CI. Uma regra é útil quando orienta o comportamento do agente; ela é arriscada quando vira substituta de validação executável.

Qual é a diferença em relação a editar o CLAUDE.md manualmente?

Editar manualmente pode funcionar, mas muitas vezes pula a evidência e o escopo. O promote skill adiciona um processo repetível: encontrar a memória, confirmar o comportamento pretendido, escolher o destino correto e deixar um rastro de que a memória foi promovida. Isso reduz a proliferação de regras e ajuda futuros mantenedores a entender por que a instrução existe.

O promote é amigável para iniciantes?

Sim, desde que a pessoa já entenda onde ficam a memória do projeto Claude e os arquivos de regras. Iniciantes devem começar com um único padrão claro para o projeto inteiro, usar --target claude.md e evitar regras com escopo por caminho até estarem confortáveis com as convenções de .claude/rules/.

Como melhorar o promote skill

Melhore os resultados do promote com evidências melhores

O promote skill funciona melhor quando a memória de origem é específica. Antes de invocá-lo, reúna a entrada exata da memória, a correção ou a falha repetida que prova que a regra é necessária. “Claude keeps using npm” é mais fraco do que “In three sessions Claude ran npm commands, but this repo uses pnpm and has no package-lock.json.”

Evite falhas comuns de promoção

A falha mais comum é promover demais: transformar uma observação restrita em um comando global. Outra é escrever regras que parecem boas, mas não são acionáveis, como “write better tests.” Uma regra melhor nomeia o gatilho, a ação obrigatória e o escopo: “For src/api/**/*.ts, validate request bodies before calling service functions.”

Faça iterações depois da primeira regra gerada

Depois da primeira saída do promote, pergunte se a regra está ampla demais, vaga demais ou duplicada em outro lugar. Em seguida, refine-a. Prompts de acompanhamento úteis incluem:

• “Make this rule enforceable in one paragraph.”
• “Narrow this to only API route files.”
• “Add one example and one non-example.”
• “Check whether this belongs in CLAUDE.md or .claude/rules/testing.md.”

Mantenha o sistema de regras saudável

Um bom guia de promote deve proteger a camada de regras para que ela não fique ruidosa. Revise periodicamente as regras promovidas em busca de conflitos, convenções desatualizadas e instruções que deveriam ser movidas para ferramentas. O melhor resultado do promote não é mais markdown; é ter menos correções repetidas porque o Claude agora recebe o contexto durável certo, no escopo certo.