Seu agente de codificação tem uma única personalidade padrão: a de generalista competente. Peça a ele para revisar um fluxo de autenticação e você recebe conselhos sensatos, mas esquecíveis. Peça a um revisor de segurança com um modelo de ameaças e um checklist, e você recebe achados. Essa diferença não custa nada além de um arquivo markdown, e é por isso que o agency-agents chegou a 149.312 estrelas.
A biblioteca é genuinamente útil. Também é uma pasta de arquivos em uma única máquina, o que se torna a limitação no momento em que mais de uma pessoa precisa que os papéis signifiquem algo. Este artigo aborda o que você recebe, como instalar apenas a parte que deseja e a diferença entre uma definição de papel e um Agent ao qual uma equipe pode atribuir trabalho.
TL;DR
Este é um dos cinco mergulhos profundos do nosso resumo de ferramentas de código aberto que estendem agentes de codificação.
O agency-agents é uma coleção de mais de 300 definições de papéis de agentes distribuídas em cerca de 20 categorias, com licença MIT, instalável no Claude Code, Cursor, Codex, Gemini CLI, OpenCode e cerca de uma dúzia de outras ferramentas com um único comando. Cada arquivo descreve uma identidade, um processo de trabalho, entregáveis e uma definição de pronto. Um papel muda a forma como um agente enquadra uma tarefa; ele não fornece ao agente informações que ele não tem, nem persiste depois que a sessão termina. Instale uma divisão, edite os arquivos para que correspondam à sua stack e promova para configurações salvas — que uma equipe pode atribuir — aqueles que você usa toda semana.
O que você está instalando
Contando a partir da árvore do repositório em 1º de setembro de 2026, há 312 arquivos markdown distribuídos em 20 pastas de categorias de nível superior. O README do repositório ainda diz “230+”, o que está desatualizado.
| Divisão | Arquivos | Divisão | Arquivos |
|---|---|---|---|
| engineering | 59 | testing | 9 |
| specialized | 58 | paid-media | 7 |
| marketing | 36 | project-management | 7 |
| game-development | 21 | academic | 6 |
| integrations | 18 | spatial-computing | 6 |
| strategy | 16 | support | 6 |
| gis | 13 | finance | 5 |
| security | 12 | product | 5 |
| design | 10 | healthcare | 3 |
| sales | 9 | examples | 6 |
A divisão de engenharia é onde a maioria das equipes começa, e o nível de especificidade é maior do que uma coleção de prompts costuma alcançar. Ao lado de Frontend Developer e Backend Architect, há um Network Engineer voltado para Cisco IOS-XE e Juniper Junos, um Embedded Firmware Engineer para alvos ESP32 e STM32, um Incident Response Commander para post-mortems e prontidão de plantão, e um Codebase Onboarding Engineer criado para explorar um repositório em modo somente leitura e afirmar fatos em vez de propor mudanças.
Esse último mostra o padrão funcionando. Um papel somente leitura com um mandato explícito de não editar é uma ferramenta diferente do seu agente padrão, e custa apenas um arquivo.
Instalando apenas o que você precisa
git clone https://github.com/msitarzewski/agency-agents.git
cd agency-agents
./scripts/install.sh # interactive
./scripts/install.sh --tool claude-code --division engineering,security
./scripts/install.sh --tool cursor --agent frontend-developer
./scripts/install.sh --list teams
./scripts/install.sh --tool opencode --division engineering --dry-run
Um aviso que o repositório documenta e que a maioria dos artigos ignora: o runtime do OpenCode registra cerca de 119 agentes e descarta silenciosamente o restante. Instalar um subconjunto com --division mantém você abaixo do limite, e o instalador avisa quando uma seleção o ultrapassaria. O truncamento silencioso é o pior modo de falha possível, porque o papel que você queria está faltando e nada indica isso.
Mesmo sem esse bug, instalar todos os 300 é um erro. Uma lista de papéis que você não consegue memorizar é uma lista que você não vai usar. Instale a divisão em que você atua, leia cinco arquivos e exclua os que não correspondem à forma como sua equipe trabalha.
Onde termina uma definição de papel
Um papel é um enquadramento. Ele define o que o agente procura, que formato produz e o que considera concluído. Isso vale mais do que parece, porque grande parte do que torna a saída de um agente fraca não é o modelo estar errado, e sim o modelo otimizar para o formato errado de resposta.
Duas coisas que um papel não consegue fazer.
Ele não consegue fornecer informações que o modelo não tem. Um papel de Backend Architect produz código bem organizado com base em uma interface que ele inferiu. O papel melhorou a estrutura. Não tornou o resultado correto.
Ele não sobrevive à sessão. Você ativa um papel, ele faz uma tarefa, o terminal fecha. No dia seguinte, você digita a ativação de novo. Nove das divisões deste repositório descrevem funções que só existem dentro de uma organização, e a ferramenta que as instala não tem nenhum conceito de organização. Não há atribuição, nem registro do que o revisor de segurança encontrou na terça-feira passada, nem forma de um colega ver nada disso.
De uma definição de papel a um Agent atribuível
Uma definição de papel é um prompt que você digita novamente. Um Agent no Sharkly é uma configuração salva: instruções, runtime, skills, repositórios e ambiente. Essa é a versão duradoura daquilo que um arquivo em ~/.claude/agents/ busca alcançar.
Cada peça tem uma função. O Agent define como o trabalho deve ser conduzido. O Computer fornece o host e os recursos locais. O Runtime executa a sessão real do agente, usando a ferramenta de codificação que sua equipe já instalou. A Task permanece o registro compartilhado.
O Sharkly não substitui o Claude Code, o Codex ou os papéis deste repositório. Ele adiciona a camada de tarefa compartilhada, Computer, contexto, controle e revisão ao redor deles. O uso do modelo continua pelas assinaturas ou chaves de API configuradas nessas ferramentas.
O conceito de divisão se mapeia diretamente. Uma Crew é um grupo reutilizável de Pessoas e Agents coordenado por um Agent líder. As Crews funcionam com o líder primeiro: o líder lê o contexto da tarefa, decide quais membros envolver e traz os resultados deles de volta para uma única Task, em vez de cada especialista começar ao mesmo tempo. É isso que o agency-agents sugere com suas oito divisões e não consegue executar, porque uma pasta de arquivos não tem líder nem uma tarefa compartilhada para a qual retornar.
A execução, os bloqueios, os resultados e a discussão de acompanhamento voltam para a linha do tempo da tarefa. Quando alguém pergunta o que o revisor de segurança encontrou, a resposta está na Task.
Use o repositório como uma biblioteca, não como uma equipe
Use o agency-agents diretamente quando você é uma só pessoa, trabalhando localmente, e quer um enquadramento melhor para o trabalho de hoje. Instale uma divisão, leia os arquivos e obtenha valor em vinte minutos.
Use Agents salvos quando o papel precisa ser reutilizado por mais de uma pessoa, quando a saída precisa de revisão antes de valer, ou quando alguém vai perguntar daqui a três meses o que um papel produziu e por quê. O critério não é o tamanho da equipe. É se o papel precisa sobreviver à sessão.
O fluxo prático é tratar o repositório como material de origem. Pegue a estrutura dos arquivos, que é a parte genuinamente reutilizável, substitua o conteúdo genérico pela sua stack e pela sua definição de pronto, e promova para uma configuração salva tudo aquilo a que você recorre duas vezes por semana. Os bons arquivos compartilham todos o mesmo formato: identidade, missão, processo ordenado, entregáveis com um formato e critérios de sucesso. Um papel de revisão com um processo de sete etapas produz resultados consistentes entre sessões. Um sem isso produz o que o modelo quiser naquele dia.
Os Agents pesquisam, executam, testam e relatam. As pessoas definem a direção, concedem autoridade e aceitam o resultado.
Perguntas frequentes
O agency-agents funciona com ferramentas além do Claude Code? Sim. Um script de conversão gera arquivos de integração para cada ferramenta, e install.sh --tool tem como alvo uma delas. Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Copilot, Windsurf, Aider e Kimi Code estão entre os alvos suportados. Há também um aplicativo de desktop para macOS, Linux e Windows.
Devo instalar todos os 300 papéis? Não. No OpenCode você não pode, porque cerca de 119 são registrados e o restante é descartado sem aviso. Em outras ferramentas você pode, mas não vai usar a maioria deles. Instale por divisão.
Os papéis tornam um agente mais capaz? Eles o tornam mais bem direcionado. A consistência e o formato da saída melhoram. O conhecimento de fatos que o modelo nunca teve não muda.
Isso é o mesmo que um framework de agentes? Não. Um framework oferece orquestração de runtime em código. O agency-agents oferece arquivos markdown que mudam o comportamento de um agente existente. Camadas diferentes, sem sobreposição.
Como isso se relaciona com as Sharkly Skills? Uma Skill é uma capacidade que você anexa à configuração de um Agent, de modo que ela é reutilizada com esse Agent em vez de ser reinstalada em cada máquina. As definições de papel deste repositório são uma boa matéria-prima para escrevê-las.
A versão resumida
O agency-agents é a melhor versão disponível de uma ideia: um agente faz um trabalho melhor quando sabe qual papel está desempenhando. Instale uma divisão, leia os arquivos e edite-os até virarem algo que combine com sua equipe.
Depois, tenha clareza sobre o limite. Os papéis não conhecem fatos que nunca foram fornecidos ao seu modelo, nem persistem em algo que uma equipe possa ver ou revisar. Uma lista de papéis é um bom começo. Não é uma organização. O Sharkly detém a outra metade: a Task é o registro compartilhado, a execução roda em Computers que você conecta por meio dos runtimes que você já paga, e os resultados retornam para um lugar onde uma pessoa pode revisá-los e aceitá-los.
