Elites Skills Architect

Transforma uma ideia bruta em uma skill que funciona: descoberta, especificação, validação, execuções de teste, revisão humana, ajuste de descrição e empacotamento. Toda afirmação sobre uma skill é respaldada por um script ou uma execução avaliada, não por lê-la uma vez e sentir-se bem sobre ela.

Por onde começar

Oito estágios. Descubra onde o usuário está e comece por ali:

Descoberta: obtenha um problema concreto e os fatos necessários para escrever a especificação
Identificar problemas: muito simples, muito amplo, sobreposições, contradições
Categorizar: criação de documentos, automação de fluxo de trabalho ou aprimoramento de MCP
Construir e validar: frontmatter, corpo, pasta, evals, scripts/validate_spec.py
Testar e revisar: execute os evals, mostre as saídas, avalie-as, teste sob pressão qualquer regra que a skill imponha
Melhorar: corrija o padrão por trás do feedback, não o caso isolado
Ajuste de descrição: testes de acionamento e scripts/optimize_description.py
Empacotar: scripts/package_skill.py

Ajuste seu ritmo ao usuário. Alguém que diz "servidor MCP" e "frontmatter" sem ser solicitado quer rapidez. Alguém que diz "Quero que o Claude faça minhas faturas" quer ser guiado uma pergunta de cada vez. Português claro, sem jargão que eles não usaram primeiro.

Todos os scripts são Python 3.9 ou superior da biblioteca padrão, executados a partir da raiz da skill:

cd <caminho-para-elites-skills-architect>
python3 scripts/validate_spec.py <pasta-da-skill>

Estágio 1: Descoberta

Leia references/discovery-questions.md para o banco de perguntas e as perguntas de acompanhamento para respostas fracas. Pergunte em lotes de duas ou três, baseie-se nas respostas, nunca despeje a lista.

Lote 1, problema: o único resultado que a skill deve produzir; 5 a 10 frases que os usuários realmente diriam; o que a skill NÃO deve tratar. Lote 2, dados: entradas e seu formato; o que o usuário tem quando funcionou; o que comumente dá errado com a entrada. Lote 3, fluxo de trabalho: ordem das etapas; dependências; caminhos se/então; o que acontece com as etapas 1 e 2 quando a etapa 3 falha. Lote 4, integrações: servidores MCP, APIs, embutidos do Claude, autenticação e limites de taxa. Lote 5, resiliência: as três falhas de tempo de execução mais prováveis; a mensagem em falha total.

Pare de perguntar quando você puder fazer tudo isso sem adivinhar: escrever a descrição com frases de acionamento reais, listar cada etapa em ordem, nomear três modos de falha com seu tratamento e explicar a skill bem o suficiente para outro desenvolvedor construí-la.

Se o usuário já tem o conhecimento escrito (um manual, documentação de API, um guia de estilo, páginas da web salvas), importe-o em vez de redigitá-lo:

python3 scripts/import_sources.py <arquivos-ou-pastas> --skill <pasta-da-skill> --dry-run

Isso converte Markdown, texto e HTML salvos em arquivos de referência, divide os longos nos cabeçalhos, escreve um sources-index.md ao lado deles e imprime as linhas "leia X quando Y" para o corpo. Nunca baixa nada; salve as páginas primeiro.

Estágio 2: Identificar problemas antes de construir

Muito simples: o Claude já faz isso. Uma skill ganha seu lugar quando há lógica de domínio ou um formato a ser imposto toda vez. Pergunte se há.
Muito amplo: vários fluxos de trabalho não relacionados. Sugira uma divisão; skills pequenas acionam com mais confiabilidade. Pergunte qual vem primeiro.
Sobreposição: próximo a docx, pptx, xlsx, pdf ou design de frontend. Diga isso e pergunte se deve estender ou construir algo diferente.
Impossível ou inseguro: diga claramente e ofereça a versão viável mais próxima.
Contradição: "totalmente automático" antes, "pergunte-me primeiro" agora. Resolva antes de escrever uma linha.

Estágio 3: Categorizar

Leia references/categories-and-patterns.md. Escolha um:

Categoria 1, criação de documentos e ativos: cria arquivos com os embutidos do Claude. Os lotes 1 e 2 da descoberta são suficientes.
Categoria 2, automação de fluxo de trabalho: etapas ordenadas entre ferramentas, portões de validação, falha parcial ou reversão. Todos os cinco lotes.
Categoria 3, aprimoramento de MCP: envolve um servidor MCP existente com julgamento e padrões. Lotes 1, 2 e 4.

Diga ao usuário a categoria e por quê. Misturas são aceitáveis; escolha a principal para a descrição e layout da pasta.

Estágio 4: Construir e validar

Leia references/worked-example.md uma vez antes de gerar qualquer coisa, para que sua saída corresponda a esse nível de detalhe. Use references/spec-output-template.md como o esqueleto.

4a: Frontmatter

Leia references/yaml-rules.md. O que o validador verifica (erros, a menos que marcado):

name: kebab-case, sem "claude" ou "anthropic"; corresponde ao nome da pasta (aviso, erro com --portable)
description: 1 a 1024 caracteres; verbo de ação, o que faz, quando usá-la, 3 a 8 frases de acionamento entre aspas duplas, um escopo negativo (o comprimento é um erro; verbo, frases e escopo negativo são avisos)
sem colchetes angulares, tabulações, aspas inteligentes ou travessões que não sejam o hífen
sem apóstrofos na descrição (aviso; alguns parsers de upload os rejeitaram)
tags como uma string, tags: "a, b, c", nunca [a, b, c] (aviso); cite valores de metadados que parecem números, version: "1.0"

Torne a descrição convincente. Em nossos testes, o Claude deixa uma skill sem uso com mais frequência do que a escolhe erroneamente, então adicione "também aciona quando alguém menciona ..." para as solicitações indiretas.

4b: Corpo

No máximo 500 linhas, imperativo, e explica o porquê, não apenas o quê. Ordem: propósito em uma linha; quando usar e quando não usar; etapas numeradas com uma verificação após cada uma; dois ou três exemplos (frase, ações, resultado); tratamento de erros com causa e resposta; práticas recomendadas curtas. Mova qualquer coisa maior para references/ e aponte para ela com "leia X quando Y".

4c: Pasta

nome-da-skill/
  SKILL.md
  evals/evals.json        casos de teste, veja references/schemas.md
  scripts/                lógica determinística que o modelo não deve rederivar
  references/             material profundo carregado sob demanda
  assets/                 modelos e amostras

Nenhum README.md dentro da pasta da skill; a documentação fica em SKILL.md e references/.

4d: Plano de teste e evals

Escreva 5 ou mais consultas que devem acionar e 5 ou mais consultas que NÃO devem acionar. Boas consultas são específicas e soam como uma pessoa: "ok iniciando a reformulação do checkout segunda-feira, configure a sprint no Linear, 2 semanas, equipe de frontend". Os melhores negativos compartilham palavras com os positivos, mas querem outra coisa: conselho em vez de ação, relatório em vez de criação.

Escreva 2 ou 3 evals em evals/evals.json (formato em references/schemas.md). Cada expectativa é uma frase verificável. Mostre-as ao usuário antes de executar qualquer coisa.

4e: Validar

python3 scripts/validate_spec.py <pasta-da-skill>
python3 scripts/validate_spec.py <pasta-da-skill> --json     # para ferramentas
python3 scripts/validate_spec.py <pasta-da-skill> --strict   # avisos também falham
python3 scripts/validate_spec.py <pasta-da-skill> --portable # para agentes que não sejam Claude

Ele verifica as regras de frontmatter, comprimento do corpo, as seções acima, espaços reservados deixados, evals.json, pressure-evals.json quando presente, e se cada caminho scripts/... ou references/... que o corpo menciona existe. Corrija todos os erros. Nunca mostre uma especificação que falha. --portable adiciona as regras da especificação open Agent Skills (o nome da pasta deve corresponder, os valores de metadados devem ser texto) para skills que também serão executadas em outros agentes.

Estágio 5: Testar e revisar

Uma sequência; não pare no meio.

5a: Executar os evals

Layout do espaço de trabalho (árvore completa em references/schemas.md):

<nome-da-skill>-workspace/iteration-1/eval-<id>/<configuration>/run-<k>/outputs/

Escreva eval_metadata.json em cada pasta eval-<id>/. Em seguida, execute cada eval:

Com subagentes (Claude Code, Cowork): inicie as execuções com e sem skill para cada eval na mesma rodada. Cada executor lê a skill, faz o prompt, salva os arquivos em outputs/, escreve outputs/user_notes.md para qualquer coisa que não tinha certeza, e outputs/metrics.json. Salve timing.json da notificação de tarefa imediatamente; os números não são mantidos em nenhum outro lugar.
Sem subagentes (claude.ai): leia SKILL.md e faça cada prompt você mesmo, um de cada vez, nas mesmas pastas.

5b: Esboçar asserções enquanto as execuções estão em andamento

Adicione expectativas mensuráveis a eval_metadata.json e evals/evals.json. Explique cada uma ao usuário em uma frase. Pule asserções para gosto; uma pessoa julga essas.

5c: Mostrar as saídas antes de julgá-las

python3 eval-viewer/review.py <nome-da-skill>-workspace/iteration-1 --skill-name <nome>

A página abre no navegador, funciona offline e salva o feedback em feedback.json no espaço de trabalho enquanto o usuário digita. No Cowork, ou quando um servidor não é possível, adicione --static review.html; o feedback então é baixado como um arquivo. Abra o visualizador primeiro e veja as saídas você mesmo em segundo lugar. Não altere a skill antes de o usuário ter reagido.

5d: Avaliar e comparar (subagentes)

Avalie cada execução com agents/grader.md. Use um modelo diferente daquele que executou o eval quando possível; um modelo é um péssimo juiz do seu próprio trabalho.

Agregue:

python3 scripts/aggregate_benchmark.py <nome-da-skill>-workspace/iteration-1 --skill-name <nome>

Reabra o visualizador com --benchmark <iteration>/benchmark.json para a guia Benchmark. Para padrões que as médias escondem, execute agents/analyzer.md tarefa 2.

5e: Teste sob pressão (skills que impõem uma regra)

Quando o valor da skill é uma regra que deve ser mantida (um formato, uma verificação, uma etapa de aprovação), leia references/pressure-tests.md e escreva 3 a 5 cenários em evals/pressure-evals.json: uma situação concreta, duas ou mais pressões (prazo, um chefe, o cliente pediu, horas já gastas) e uma escolha forçada que inclui um compromisso tentador.

python3 scripts/pressure_eval.py --skill-path <pasta-da-skill> \
  --scenarios <pasta-da-skill>/evals/pressure-evals.json --runs 3 --model <id-do-modelo> \
  --output <nome-da-skill>-workspace/pressure-results.json \
  --report <nome-da-skill>-workspace/pressure-report.md --dry-run

Remova --dry-run depois que o usuário aprovar a contagem de chamadas. Cada cenário é executado sem e com a skill. "skill não se mantém" significa que o relatório contém as desculpas que Claude deu: contra-argumente cada uma na skill (nomeie-a, diga por que está errada, diga o que fazer), depois execute novamente. "passa, mas a linha de base também passa" significa que o cenário é muito fácil para provar qualquer coisa.

Estágio 6: Melhorar

Encontre o padrão por trás do feedback e corrija isso; três prompts de teste não são o mundo. Leia as transcrições, não apenas as saídas, e corte instruções que fizeram o modelo desperdiçar etapas. Se você estiver escrevendo SEMPRE ou NUNCA em maiúsculas, pare e explique o motivo; um modelo com o motivo vai mais longe do que um modelo com a regra. Quando toda execução escreveu o mesmo auxiliar, coloque-o em scripts/ e diga isso. Cuidado com uma skill que passa seus três evals e nada mais.

Em seguida: aplique as alterações, execute novamente todos os evals em iteration-2/, abra o visualizador com --previous-workspace iteration-1 para que o usuário veja o antigo e o novo lado a lado, leia o feedback, repita. Pare quando o usuário estiver satisfeito, o feedback estiver vazio ou o progresso tiver estagnado.

Para uma chamada rigorosa de antigo versus novo, use agents/comparator.md (um juiz A/B cego com uma verificação de troca) e depois agents/analyzer.md tarefa 1 para explicar o resultado. Opcional; o loop de revisão geralmente é suficiente.

Estágio 7: Ajuste de descrição

A descrição é o que faz o Claude escolher a skill. Ajuste-a depois que a skill em si funcionar.

7a: Consultas de acionamento

Escreva 20 consultas em evals/trigger-evals.json: cerca de metade deve acionar, metade não deve. Inclua fala casual, nomes de arquivos, contexto pessoal. Os negativos valiosos são quase acertos. Mostre a lista ao usuário e altere o que eles pedirem para alterar; consultas ruins produzem uma descrição ruim.

7b: Contar antes de gastar

python3 scripts/trigger_eval.py --skill-path <pasta-da-skill> --eval-set <pasta-da-skill>/evals/trigger-evals.json --dry-run

Cada execução é uma chamada claude -p. Informe ao usuário o número e obtenha um sim.

7c: Medir

python3 scripts/trigger_eval.py --skill-path <pasta-da-skill> \
  --eval-set <pasta-da-skill>/evals/trigger-evals.json \
  --runs-per-query 3 --workers 4 --model <id-do-modelo> \
  --output <nome-da-skill>-workspace/trigger-results.json --verbose

O script instala a skill em um projeto descartável e executa o Claude lá com apenas as configurações desse projeto, para que nada toque no projeto real do usuário e suas outras skills não possam interferir. Leia o resumo: consultas perdidas (falsos negativos) significam que a descrição é muito restrita; as acionadas erroneamente significam que é muito ampla. Uma consulta cujas execuções todas falharam é relatada como desconhecida, nunca como um passe.

7d: Otimizar (apenas Claude Code)

python3 scripts/optimize_description.py --skill-path <pasta-da-skill> \
  --eval-set <pasta-da-skill>/evals/trigger-evals.json --model <id-do-modelo> \
  --max-iterations 4 --results-dir <nome-da-skill>-workspace/description-runs --verbose

Ele divide as consultas uma vez em conjuntos de treino e retidos, avalia, pede ao Claude uma descrição melhor usando apenas as falhas de treinamento, valida o candidato com as mesmas regras de validate_spec.py e repete. O vencedor é a iteração com a melhor pontuação de treino; empates vão para o texto mais curto. A pontuação do conjunto retido é relatada, mas nunca usada para escolher, então permanece uma verificação honesta: se for muito menor que a pontuação de treino, a descrição está ajustada às consultas de treinamento. Escreve results.json, report.md e best-description.txt, e sai com 0 apenas quando o vencedor passa em todas as consultas de treino. No claude.ai, leia as falhas e reescreva manualmente.

7e: Aplicar

Cole o vencedor em SKILL.md, mostre ao usuário antes e depois com as pontuações e execute scripts/validate_spec.py novamente.

Estágio 8: Empacotar

python3 scripts/package_skill.py <pasta-da-skill> --output dist/
python3 scripts/package_skill.py --inspect dist/<nome-da-skill>.skill

O empacotamento valida primeiro e recusa em erros (e em avisos, a menos que --allow-warnings seja usado). O arquivo é reproduzível e imprime um SHA-256. Dê ao usuário o caminho, ou o próprio arquivo.

[truncado para tradução]

elitesalgorithm/elites-skills-architect

O que é elites-skills-architect?

Perguntar na sua IA favorita

Documentação