skill-optimizer

Quando Usar Esta Habilidade

• Use quando as habilidades não estiverem sendo acionadas como esperado ou parecerem quebradas
• Use quando quiser auditar e melhorar a qualidade da sua biblioteca de habilidades
• Use quando quiser entender quais habilidades estão com desempenho inferior ou desperdiçando tokens de contexto

Regras

• Somente leitura: nunca modifique arquivos de habilidade. Apenas gere o relatório.
• Todas as 8 dimensões: não pule nenhuma. Se os dados forem insuficientes, relate "N/A — dados de sessão insuficientes" em vez de omitir.
• Quantifique: "você teve 12 tarefas de pesquisa na semana passada, mas a habilidade nunca foi acionada" é melhor do que "você faz pesquisa com frequência".
• Sugira, não prescreva: dê sugestões de redação específicas para melhorias na descrição, mas enquadre como sugestões.
• Mostre evidências: para alegações de subacionamento, cite a mensagem real do usuário que deveria ter acionado a habilidade.
• Sugestões baseadas em evidências: ao sugerir reescritas de descrição, cite a descoberta de pesquisa específica que motiva a mudança (por exemplo, "priorize palavras-chave de acionamento — estudo MCP mostra melhoria de 3,6x na taxa de seleção").

Visão Geral

Analise habilidades usando dados históricos de sessão + verificações estáticas de qualidade, gere um relatório de diagnóstico com correções priorizadas P0/P1/P2. Pontua cada habilidade em uma escala composta de 5 pontos em 8 dimensões.

CSO (Otimização de Busca Claude/Agente) = escrever descrições de habilidades para que os agentes selecionem a habilidade certa no momento certo. Esta habilidade verifica violações de CSO.

Uso

• /optimize-skill → digitalizar todas as habilidades
• /optimize-skill my-skill → habilidade única
• /optimize-skill skill-a skill-b → várias habilidades especificadas

Fontes de Dados

Detecte automaticamente a plataforma de agente atual e escaneie os caminhos correspondentes:

Detecção de plataforma: Verifique quais diretórios existem. Escaneie todas as fontes disponíveis — um usuário pode ter Claude Code e Codex instalados.

Fluxo de Trabalho

Identify target skills
        ↓
Collect session data (python3 scripts scan JSONL transcripts)
        ↓
Run 8 analysis dimensions
        ↓
Compute composite scores
        ↓
Output report with P0/P1/P2

Etapa 1: Identificar Habilidades de Destino

Digitalize os diretórios de habilidades em ordem: ~/.claude/skills/, ~/.codex/skills/, ~/.agents/skills/. Deduplique por nome de habilidade (mesmo nome em vários locais = mesma habilidade). Para cada uma, leia SKILL.md e extraia:

• nome, descrição (do frontmatter YAML)
• palavras-chave de acionamento (do campo descrição)
• etapas de fluxo de trabalho definidas (Etapa 1/2/3... ou seções ### sob Fluxo de Trabalho)
• contagem de palavras

Se o usuário especificou nomes de habilidades, filtre apenas para esses.

Etapa 2: Coletar Dados de Sessão

Use scripts python3 via Bash para digitalizar arquivos JSONL de sessão. Extraia:

Sessões do Código Claude (~/.claude/projects/**/*.jsonl):

• chamadas de tool_use Skill (quais habilidades foram invocadas)
• Mensagens do usuário (texto completo)
• Mensagens do assistente após a invocação da habilidade (para rastreamento do fluxo de trabalho)
• Mensagens do usuário após a invocação da habilidade (para análise de reação)

Sessões do Codex (~/.codex/sessions/**/*.jsonl):

• eventos tool_code session_meta → extraia base_instructions para evidência de carregamento de habilidade
• eventos assistant_response response_item → saídas do assistente (rastreamento do fluxo de trabalho)
• eventos tool_code event_msg → execução de ferramenta e eventos relacionados à habilidade
• Mensagens do usuário de eventos user_message turn_context (para análise de reação)

Observação: O Codex injeta habilidades via contexto em vez de chamadas explícitas de ferramenta tool_use Skill. O carregamento de habilidade (presente em base_instructions) NÃO é igual à invocação ativa. Para detectar o uso real, procure marcadores de fluxo de trabalho específicos da habilidade (cabeçalhos de etapa, formatos de saída) no conteúdo response_item dentro dessa sessão. Uma habilidade é "invocada" apenas se o agente produziu saída seguindo o fluxo de trabalho definido da habilidade.

Agregado:

• Por habilidade: contagem de invocação, contagem de correspondência de palavras-chave de acionamento
• Por habilidade: sentimento da reação do usuário após a invocação
• Por habilidade: marcadores de conclusão de etapa do fluxo de trabalho

Etapa 3: Executar 8 Dimensões de Análise

Você DEVE executar TODAS as 8 dimensões. O comportamento padrão sem esta habilidade é pular as dimensões 4.2, 4.3, 4.5b e 4.8. Estas são as dimensões mais valiosas — não as pule.

4.1 Taxa de Acionamento

Conte quantas vezes cada habilidade foi realmente invocada versus quantas vezes suas palavras-chave de acionamento apareceram nas mensagens do usuário.

Código Claude: conte chamadas de tool_use Skill nas transcrições.

…