run

Visão geral da skill run

O que a skill run faz

run é uma skill de orquestração do AgentHub para Claude que expõe o comando /hub:run. Ela executa, em uma única solicitação, um ciclo completo no estilo competição: inicializa a tarefa, captura uma baseline, inicia vários agentes, avalia as saídas de cada um e mescla o melhor resultado. Use quando você quiser um fluxo agentic para comparar várias tentativas de solução, em vez de pedir uma única resposta direta.

Melhor uso para usuários do AgentHub

A skill run funciona melhor para equipes que já usam o padrão de comandos do AgentHub e querem um ponto de entrada único, de alto nível, para execução multiagente. Ela se encaixa em tarefas de engenharia como otimização de performance, refatoração, geração de testes, correção de bugs e melhorias de código mensuráveis. Também pode apoiar seleção criativa fora de código quando você usa o modo judge, por exemplo para escolher o melhor texto de marketing entre vários candidatos.

Principal decisão antes de instalar

Instale run se você quer um comando repetível que encadeia o ciclo de vida do AgentHub sem chamar manualmente /hub:init, captura de baseline, criação de agentes, avaliação e etapas de merge. Não trate a skill como um executor genérico de automações: o valor dela depende de existir uma tarefa que possa ser avaliada ou julgada, além de um ambiente AgentHub em que os comandos relacionados estejam disponíveis.

Principal diferencial

Diferente de um prompt comum que pede ao Claude para “tentar várias abordagens”, /hub:run dá ao agente um ciclo estruturado com parâmetros explícitos: tarefa, número de agentes, comando de eval opcional, métrica, direção de otimização e template. Essa estrutura torna o resultado mais fácil de comparar, auditar e mesclar.

Como usar a skill run

Instalação da run e verificação do repositório

Instale a skill a partir do repositório com seu gerenciador de skills, por exemplo:

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

Depois, inspecione primeiro o arquivo upstream:

engineering/agenthub/skills/run/SKILL.md

Esse caminho no repositório contém o comportamento central e os exemplos. Na árvore fornecida, não há pastas complementares visíveis como scripts/, resources/, references/ ou rules/ para esta skill. Por isso, a adoção depende principalmente de entender o contrato do comando em SKILL.md e de ter disponível o conjunto mais amplo de comandos do AgentHub.

Padrão básico de uso da run

O formato do comando é:

/hub:run --task "..." --agents 3 --eval "..." --metric metric_name --direction lower --template optimizer

Parâmetros importantes:

• --task: obrigatório; o trabalho exato em que os agentes devem competir.
• --agents: opcional; nos exemplos da fonte, o padrão é 3.
• --eval: opcional; comando usado para medir os resultados.
• --metric: obrigatório ao usar --eval; o valor a ser comparado.
• --direction: obrigatório ao comparar uma métrica; use lower ou higher.
• --template: opcional; exemplos incluem optimizer, refactorer, test-writer e bug-fixer.
• --judge: útil quando não há uma métrica determinística e um juiz LLM deve comparar as saídas.

Transforme uma meta vaga em um comando forte

Uma solicitação fraca seria:

/hub:run --task "make it faster"

Um prompt de uso da run mais forte seria:

/hub:run --task "Reduce p50 latency in the product search endpoint without changing response schema" --agents 3 --eval "pytest bench.py --json" --metric p50_ms --direction lower --template optimizer

Essa versão melhora a qualidade da saída porque define a área-alvo, preserva uma restrição, oferece aos agentes um benchmark mensurável, nomeia a métrica e declara qual direção vence. Para trabalho de cobertura, use uma métrica em que maior é melhor:

/hub:run --task "Add tests for untested utils without modifying production behavior" --agents 3 --eval "pytest --cov=utils --cov-report=json" --metric coverage_pct --direction higher --template test-writer

Fluxo recomendado antes do merge

Antes de usar a skill run em código importante, garanta que o repositório esteja limpo, que os testes sejam reproduzíveis e que o comando de eval retorne uma saída legível por máquina ou consistentemente parseável. Comece com 2–3 agentes para controlar custo e velocidade. Use evals determinísticos para código sempre que possível e reserve --judge para saídas subjetivas, como copywriting ou alternativas de design. Depois que o vencedor for mesclado, ainda revise o diff manualmente; a skill orquestra a seleção, mas não substitui a responsabilidade pelo código.

FAQ da skill run

A run é para Agent Orchestration ou para prompting simples?

run é para Agent Orchestration. Ela foi projetada para coordenar vários agentes ao longo de um ciclo de vida e selecionar um vencedor. Se você precisa apenas de uma explicação, uma sugestão de refatoração ou um rascunho, um prompt normal é mais simples. Use a skill run quando comparação, avaliação e disciplina de merge forem importantes.

O que já precisa existir para a run funcionar bem?

Você precisa de uma configuração compatível com AgentHub em que /hub:run e os comandos relacionados do ciclo de vida possam ser reconhecidos. Para tarefas de software mensuráveis, também precisa de um comando de eval confiável, um nome de métrica claro e uma direção de otimização conhecida. Sem isso, o comando ainda pode rodar em modo judge, mas o resultado será menos objetivo.

Quando devo evitar esta skill?

Evite run para tarefas vagas sem critérios de aceitação, mudanças destrutivas sem plano de rollback ou projetos em que testes e benchmarks sejam instáveis. Também evite usar agentes demais por padrão; mais agentes podem aumentar custo e carga de revisão sem melhorar a qualidade quando a definição da tarefa é fraca.

A skill run é amigável para iniciantes?

Ela é acessível se você já entende skills do Claude em estilo de comando e conceitos básicos do AgentHub. Iniciantes podem ter dificuldade com os parâmetros de eval, especialmente --metric e --direction. Comece com modo judge para tarefas criativas de baixo risco ou use um comando de teste simples antes de tentar fluxos de performance, refatoração ou workflows com muito merge.

Como melhorar a skill run

Melhore os resultados da run com limites de tarefa mais claros

A skill run funciona melhor quando a tarefa é específica o suficiente para que os agentes consigam concluí-la de forma independente. Inclua os arquivos-alvo, o comportamento esperado, as restrições e o que não deve mudar. Por exemplo, “Refactor auth module” é aceitável, mas “Refactor src/auth/session.ts to reduce duplication while preserving public function signatures and existing tests” dá aos agentes um espaço de atuação mais seguro.

Fortaleça evals e métricas

Para tarefas de código, o comando de eval é a alavanca de qualidade mais importante. Prefira comandos que falhem de forma clara e produzam uma métrica estável. Combine a métrica com a direção correta: latência e contagem de erros geralmente usam lower; cobertura, throughput ou pontuação geralmente usam higher. Se a saída do eval for ambígua, a decisão de merge pode se tornar pouco confiável mesmo quando os agentes produziram trabalho útil.

Fique atento a modos de falha comuns

Modos de falha comuns incluem tarefas amplas demais, métricas ausentes, suítes de teste instáveis, decisões em modo judge para tarefas que deveriam ser medidas e templates que não correspondem ao trabalho. Use optimizer para melhoria de performance mensurável, test-writer para cobertura, refactorer para limpeza estrutural sem alterar comportamento e bug-fixer para correção de defeitos. Um template incompatível pode empurrar os agentes para o tipo errado de solução.

Itere depois da primeira saída

Depois do primeiro /hub:run, inspecione o diff vencedor e as abordagens perdedoras. Se nenhuma for aceitável, não rode simplesmente o mesmo comando de novo. Restrinja melhor a tarefa, adicione restrições, melhore o eval ou reduza o escopo. Se o vencedor estiver próximo, mas incompleto, rode um comando de acompanhamento focado apenas no ponto que falta, em vez de reiniciar o ciclo de vida inteiro.