Skill Miner

O que Skill Miner faz?

Transforme o sinal enterrado em sessões passadas de agentes de codificação em novas ou existentes "Agent Skills". Uma sessão só ganha uma skill quando passa por este portão — repetível E (espaço para melhorar OU um pedido repetido):

1. Repetível — a tarefa ou conhecimento se repete, ou claramente poderia se repetir. Repetição passada é a evidência mais forte, mas uma tarefa plausivelmente repetível conta; uma tarefa genuinamente única nunca conta. (Obrigatório.)
2. Espaço para melhorar — há feedback significativo, para que da próxima vez seja melhor que a primeira:
   • Feedback do ambiente — o que a execução do trabalho revelou: falhas, peculiaridades recorrentes deste ambiente, caminhos indiretos e seus atalhos, heurísticas conquistadas a duras penas. Estes são literalmente skills.
   • Feedback do usuário — o usuário é o especialista e seu feedback é raro; extraia-o para captar sua mente (uma correção, uma maneira melhor que ele conhecia, um fato que erramos).
3. Um pedido repetido — o usuário continua solicitando a mesma coisa; extraia de uma vez para que ele não precise pedir novamente.

Pipeline: descobrir → destilar (LLM barato, por conversa) → agrupar, julgar e gerar.

0. Pré-requisitos

Um LLM pequeno deve estar acessível. Verifique primeiro:

python3 scripts/llm.py --check   # imprime o backend que usará, ou como habilitar um

Defina uma das variáveis OPENAI_API_KEY / GEMINI_API_KEY / OPENROUTER_API_KEY, ou tenha um CLI claude / codex / gemini no PATH. Substitua o modelo com SKILL_MINER_MODEL, force um backend com SKILL_MINER_LLM.

1–2. Execute o pipeline (scripts fazem o trabalho pesado com LLM barato)

Mantenha seu diretório de trabalho no diretório de lançamento: todos os artefatos vão para ./out.

OUT=./out
python3 scripts/discover.py  --since 35 --out $OUT/inventory.jsonl       # encontra transcrições entre agentes
python3 scripts/extract.py   --inventory $OUT/inventory.jsonl --out $OUT/conversations.jsonl --workers 10

• discover.py percorre cada adaptador em common.py:ADAPTERS (Claude Code, Codex, opencode; adicione mais lá) e mantém sessões dos últimos --since dias. Comece com no máximo 100 conversas, a menos que o usuário peça mais. Adicione --limit 15 ao extract.py para amostragem rápida.
• extract.py analisa cada conversa e emite uma linha JSONL: agent, session_id, path, main_dir, datetime, n_user_turns, topics[], tasks[], skills_used[], env_feedback[], user_feedback[]. main_dir = a pasta mais profunda onde a maior parte do trabalho ocorreu (a partir de arquivos editados / lidos / mencionados), não o cwd de lançamento. topics são o escopo (geralmente um — servindo como título — para agrupamento). tasks, env_feedback e user_feedback são arrays curtos que o LLM barato copia das próprias palavras do usuário (cada [] para a sessão típica) — eles mapeiam para as três dimensões do portão. A chamada barata vê apenas turnos do usuário, então env_feedback é o que o usuário disse sobre o que foi executado, não a saída bruta da ferramenta — verifique na etapa 4.

3. Agrupe as conversas

Leia conversations.jsonl — uma linha por sessão. Com ≤100 linhas o arquivo inteiro cabe no contexto, então leia-o. (Se você minerou muitas mais, examine com jq/grep por linhas com env_feedback / user_feedback não vazios primeiro, depois leia as fatias interessantes.) Ignore linhas cujo topics seja <error> ou trivial/vazio.

Agrupe por arquétipo de tarefa — o TIPO de trabalho, não apenas o diretório (por exemplo, "depuração de deploy CI", "iteração de UI de configurações", "migração de dependência") — para julgar dimensão 1 (repetível): quais tarefas se repetem ou claramente poderiam. Em seguida, entre as linhas, reúna as outras duas dimensões:

• dimensão 2 — env_feedback e user_feedback que apontam para uma maneira de fazer uma tarefa melhor da próxima vez (comece com feedback do ambiente). Uma única lição difícil é uma pista mesmo sem um agrupamento em torno dela.
• dimensão 3 — um detalhe que se repete em muitas sessões' tasks (o usuário continua pedindo a mesma coisa).

Separe etapas de configuração únicas e observações isoladas. Mantenha notas curtas: grupos nomeados, cada um com sua contagem de conversas, main_dir(s) dominante(s), o feedback / pedidos repetidos que carrega, e alguns paths de exemplo para abrir como evidência depois.

4. Julgue e gere

Leia references/quality-bar.md e aplique seu portão: repetível E (feedback OU um pedido repetido).

1. Conheça o cenário. Verifique suas skills existentes para o que pode ser estendido — especialmente uma cujo feedback diga que ficou aquém; se um candidato sobrepõe a ela, abra esse SKILL.md e edite-o no local. Para encontrar caminhos de arquivos de skills:

   python3 scripts/skills_inventory.py
   

   Use apenas para encontrar arquivos para editar; seu contexto permanece a fonte da verdade para o cenário. Se um candidato se concentrar em um repositório específico, verifique quais documentos Markdown já existem lá (README.md, documentos de design, planos); se o conhecimento recorrente pertence a esses documentos em vez de uma skill, recomende isso ao usuário em seu relatório.
2. Confirme com as transcrições. Para cada pista, abra 1–3 transcrições de exemplo (o campo path) para confirmar que o sinal é real e para capturar os detalhes — a regra exata, o erro exato e solução alternativa, o caminho melhor que o usuário apontou, o pedido repetido. Leia as palavras do usuário em torno de qualquer correção e em torno dos marcadores [skill used: X]. As linhas condensadas mostram apenas turnos do usuário, então a transcrição é onde você verifica o que o ambiente realmente fez. Separe uma peculiaridade recorrente (anote-a) de configuração única (no máximo uma dica de uma linha).
3. Decida, contra o portão. Uma pista se torna uma skill apenas se for repetível E tiver espaço para melhorar (feedback) ou um pedido repetido. As três dimensões têm peso igual — não descarte uma lição difícil porque a tarefa apareceu uma vez se ela claramente se repete, e não entregue uma tarefa repetível que não tem nada a melhorar e nenhum pedido repetido.
4. Gere / modifique ≤ 5 skills. Escreva cada uma como conteúdo concreto: a regra, o gatilho, os passos/comandos, a peculiaridade + solução alternativa — com caminhos de arquivo relativos à raiz do repositório (src/pages/Run.tsx), nunca absolutos específicos da máquina (/home/<user>/…) copiados de uma transcrição. Onde cai:
   • Estendendo uma skill existente → edite-a no local no caminho da skill. Não bifurque ou copie.
   • Uma skill totalmente nova → escreva-a sob ~/.agents/skills/generated-skills/<nome>/, preparada para o usuário revisar e promover — não coloque novas skills diretamente em um diretório ativo.
5. Relatório. Liste o que você criou/modificou e, para cada um, de qual(is) dimensão(ões) veio. Para cada candidato rejeitado notável, diga em uma linha qual dimensão faltou. Inclua quaisquer documentos do repositório que você acha que devem ser atualizados em vez de, ou além de, as alterações de skill.

Estendendo para outros agentes

Cada agente armazena transcrições de forma diferente. Para suportar um novo (Gemini CLI, Cursor, …) adicione um par (discover_fn, parse_fn) em common.py:ADAPTERS que produza um registro normalizado (_norm(...)). O resto do pipeline permanece inalterado. Cursor (sqlite state.vscdb) ainda não está conectado — o adaptador do opencode é um modelo baseado em banco de dados (SQLite) a ser seguido.

Notas

• Somente leitura em suas transcrições; as únicas gravações são os artefatos --out e as skills que você escolher gerar ou melhorar — novas skills caem preparadas sob ~/.agents/skills/generated-skills/, edições vão no local para a skill existente.
• Sub-agentes / threads de revisão (cadeias laterais do Claude Code, thread_source: subagent do Codex) são filtrados — apenas conversas reais com usuários são mineradas.

Visualizando os resultados

Executado de forma independente, os resultados são arquivos simples: os artefatos sob ./out, e as skills que você alterou (editadas no local, ou preparadas sob generated-skills/). Esta skill também vem com o Skill Studio, um aplicativo de desktop onde o usuário assiste à execução ao vivo, revisa cada nova skill preparada sob generated-skills/ como um card Proposto para Aceitar ou Descartar, e vê edições no local como alterações rastreadas pelo git para salvar como versão ou reverter.