Toda equipe que adotou agentes de programação com IA tem aquele desenvolvedor cujos prompts simplesmente funcionam. Suas solicitações de revisão voltam estruturadas do jeito que a equipe gosta. Suas instruções para escrever testes geram testes que seguem o padrão da casa já na primeira tentativa. Pergunte como ele faz, e a resposta costuma ser um arquivo de rascunho, um repositório de dotfiles ou um parágrafo que ele cola em uma sessão nova toda manhã. A habilidade é real. O problema é onde ela mora.
O talento para escrever prompts que vive na cabeça de uma só pessoa não escala, não sobrevive a férias e não aparece nas execuções de agente de mais ninguém. Quando esse desenvolvedor se ausenta, a qualidade cai. Quando a equipe passa de um agente para cinco, os cinco discordam sobre como o trabalho deve ser feito.
As Skills são a resposta da Sharkly para essa lacuna. Uma Skill empacota instruções reutilizáveis e arquivos de apoio para o trabalho dos Agentes, com um responsável, um escopo e permissões explícitas. Se você quiser entender primeiro o conceito geral, o que é uma Skill de agente de programação cobre a definição e o ecossistema mais amplo. Este post é sobre o fluxo de trabalho dentro da própria Sharkly.
TL;DR
Uma Skill na Sharkly empacota instruções reutilizáveis e arquivos de apoio para o trabalho dos Agentes: regras de revisão, checklists de entrega, padrões de escrita, um processo de equipe. Você pode criar uma do zero, instalar uma Skill publicada a partir de uma fonte pública compatível, importar uma descoberta por um Runtime local ou enviar um SKILL.md, um arquivo .skill ou um pacote zip. Toda Skill tem exatamente um escopo — Organização, Space ou Agente — escolhido na criação e fixo para sempre. Os Agentes vinculam Skills elegíveis por meio de suas configurações de Skills, as alterações se aplicam às execuções seguintes e os direitos de edição permanecem com o criador, os Owners e Admins da Organização. O resultado: o talento de escrever prompts deixa de viver nos dotfiles de um desenvolvedor e se torna infraestrutura compartilhada da equipe, com controle de permissões.
O que muda quando o talento dos prompts ganha um lar
A diferença entre um bom prompt e uma Skill não está no texto. Está em tudo ao redor do texto.
Um prompt em um arquivo de rascunho não tem responsável, não tem público e não tem ciclo de vida. Ninguém sabe que ele existe, ninguém consegue dizer se a cópia que encontraram no Slack está atualizada e ninguém é responsável por atualizá-lo quando o processo muda. Uma Skill tem os três. Ela pertence a uma organização. Seu escopo define exatamente quais Agentes podem usá-la. Suas permissões de edição definem exatamente quem pode alterá-la. Quando o processo muda, você atualiza a Skill uma vez, e as execuções seguintes de todos os Agentes vinculados já incorporam a mudança.
Essa é a tese da alavancagem em miniatura. A alavancagem da equipe não vem de abrir mais chats de IA; vem de compartilhar papéis, regras, contexto e fluxos de trabalho. E, como os Agentes devolvem seus resultados para a Task, a saída de uma execução guiada por Skill fica no registro compartilhado, onde a equipe pode revisá-la.
Uma delimitação antes do fluxo de trabalho. Uma Skill não é um requisito de Task. Mantenha requisitos pontuais na descrição ou nos comentários da Task. Se só esta Task precisa disso, é contexto. Se as execuções do mês que vem também precisarem, é infraestrutura.
Criando uma Skill do zero
Uma Skill começa com três coisas: um nome, uma descrição e instruções. Essa divisão importa mais do que parece.
A descrição define quando o Agente deve usar a Skill. É a condição de disparo, a frase que diz a um Agente que está examinando suas capacidades que esta Skill se aplica ao trabalho que ele tem em mãos. As instruções definem o processo repetível e a saída esperada: as etapas, as verificações e o formato que o resultado deve ter. Um teste útil é verificar se você consegue dizer em uma frase quando um Agente deve recorrer a esta Skill. Se não conseguir, provavelmente você está diante de duas Skills — ou de nenhuma.
Por baixo dos panos, as instruções principais ficam em um arquivo SKILL.md: campos YAML name e description no topo, seguidos das instruções. Arquivos de apoio podem acompanhá-la para fornecer modelos, exemplos ou dados de referência. Uma Skill de checklist de entrega pode trazer o modelo do checklist; uma Skill de escrita de migrações pode incluir dois exemplos comentados. Mantenha-os focados. Coleções de arquivos grandes ou sem relação entre si adicionam contexto sem melhorar as decisões do Agente.
Importando o talento que você já tem
A maioria das equipes não começa do zero. O talento para escrever prompts já existe; ele só está espalhado. A Sharkly oferece três caminhos de importação.
Instalar a partir de uma fonte pública compatível. A Sharkly pode buscar uma Skill publicada e criar uma cópia gerenciada no escopo que você escolher. A cópia gerenciada importa: você não está linkando para o arquivo de outra pessoa, está tirando um snapshot que sua organização controla. Revise a fonte e o conteúdo importado antes de vinculá-la a qualquer Agente. Trate instruções externas como código de terceiros, não como política confiável da organização.
Importar de um Runtime local. Este é o caminho feito exatamente para o problema dos dotfiles. Um Runtime local online pode reportar as Skills descobertas em seus diretórios locais de Skills, o que significa que o conhecimento que um desenvolvedor vinha acumulando silenciosamente se torna visível para a organização. A importação copia a Skill para a organização; a cópia local original permanece separada, então nada na configuração daquele desenvolvedor deixa de funcionar. Uma ressalva mantém isso honesto: Skills locais disponíveis diretamente para o Runtime de um Agente não precisam ser vinculadas no produto. Importe uma quando ela deve se tornar uma Skill gerenciada e reutilizável, com um escopo explícito — não apenas porque ela existe.
Enviar um pacote. Se a Skill está em um repositório ou veio de um colega, envie um SKILL.md, um arquivo .skill ou um pacote zip. A Sharkly valida o que entra: os caminhos de arquivo precisam ser relativos e não podem escapar da Skill, e o upload e a importação rejeitam caminhos ocultos ou sensíveis, conteúdo binário não suportado, entradas de arquivo inseguras, caminhos duplicados e pacotes que ultrapassam os limites do serviço. Uma Skill são instruções que um Agente vai seguir; ela merece o mesmo escrutínio que uma dependência.
Escopo: decidindo quem pode usar uma Skill
Toda Skill pertence a uma organização e tem exatamente um escopo, escolhido na criação. O escopo determina quais Agentes podem vinculá-la, e não pode ser alterado depois.
| Escopo | Quem pode usar | Escolha quando | Regra de vinculação |
|---|---|---|---|
| Organização | Agentes elegíveis em toda a organização | O procedimento é realmente corporativo, como um padrão de revisão ou um checklist de segurança | Pode ser vinculada por qualquer Agente da mesma organização |
| Space | Agentes associados a esse Space | Um único time ou área de produto é dono do processo | Um Agente só consegue vinculá-la se pertencer a esse Space |
| Agente | Apenas um Agente | A capacidade define o papel de um único especialista | Vinculada ao Agente de destino no momento da criação ou importação |
A regra prática da documentação é a correta: escolha o escopo mais restrito que corresponda ao público pretendido. O escopo também é um raio de impacto. Uma Skill com escopo de Space que fica desatualizada confunde os Agentes de um time; uma com escopo de Organização confunde todos eles. Um prompt em dotfiles tem um público de uma pessoa, permanentemente. O público de uma Skill é uma decisão deliberada, registrada no sistema.
Vinculando Skills a Agentes
Uma Skill não faz nada até que um Agente a carregue. Na Sharkly, um Agente é uma configuração de trabalho salva, e vincular uma Skill adiciona uma capacidade a ele.
A mecânica é simples. Use as configurações de Skills do Agente para adicionar ou remover Skills elegíveis, ou selecione Skills ao criar o Agente. A elegibilidade segue as regras de escopo. As alterações se aplicam às execuções seguintes do Agente, então uma vinculação que você adiciona hoje molda o trabalho de amanhã sem perturbar nada que já esteja em andamento.
A questão de julgamento é quantas Skills um Agente deve carregar. A documentação é direta: evite vincular muitas Skills que se sobrepõem, porque instruções conflitantes ou redundantes tornam a execução menos previsível. Duas Skills bem definidas valem mais do que seis que brigam entre si. Se a lista de Skills de um Agente parece uma gaveta de bagunça, suas execuções também vão parecer.
Há também uma divisão de trabalho entre as instruções do próprio Agente e suas Skills. As instruções do Agente carregam o comportamento estável daquele papel: escopo, quando pedir intervenção humana, formato de relatório. Um procedimento reutilizável que vários Agentes podem compartilhar pertence a uma Skill. Quando você se pegar colando o mesmo parágrafo nas instruções de um terceiro Agente, esse parágrafo quer virar uma Skill.
A vinculação é o que faz o restante da plataforma acumular ganhos. O mesmo Agente que carrega sua Skill de revisão é aquele que suas Automações acionam em um agendamento ou em uma mudança de status, então um padrão capturado uma vez aparece em execuções recorrentes que ninguém dispara manualmente. As Skills também são scriptáveis: a CLI expõe sharkly skill list e sharkly skill view com saída em JSON.
Governança: quem edita, quem exclui, quem revisa
Capacidade compartilhada exige controle compartilhado, e é aqui que as Skills mais se distanciam dos arquivos de prompt.
Uma Skill pode ser editada ou excluída por seu criador ou por um Owner ou Admin da Organização. Uma Skill com escopo de Space também exige permissão de escrita nesse Space. Criar ou importar uma Skill com escopo de Agente, assim como alterar as vinculações de Skills de um Agente, exige permissão para gerenciar o Agente de destino. Ninguém reescreve o padrão de revisão às escondidas numa sexta-feira à tarde.
A manutenção segue o mesmo princípio do lugar único. Quando um processo muda, atualize as instruções e os arquivos de apoio da Skill, e as execuções seguintes já usam a nova versão. A exclusão é a operação que merece mais calma: ela remove a Skill de todos os Agentes que a usam, então confira as vinculações atuais antes.
As regras de segurança são curtas e não são negociáveis. Nunca armazene senhas, tokens de acesso, chaves privadas ou outros segredos nas instruções ou nos arquivos de apoio de uma Skill. Revise toda Skill externa ou importada localmente antes de usá-la. Mantenha comandos e exemplos com o mínimo de privilégios necessários. E verifique novamente as vinculações depois de alterar as associações de Space de um Agente ou o conteúdo de uma Skill, porque a elegibilidade pode mudar sob uma vinculação.
Em meio a tudo isso, o contrato entre humanos e agentes se mantém. Os Agentes carregam Skills, seguem o processo e devolvem os resultados para a Task. As pessoas decidem quais Skills têm autoridade na equipe. Uma Skill eleva o piso de consistência. Ela não elimina o revisor.
Quando não criar uma Skill
Skills são infraestrutura, e infraestrutura tem um custo de manutenção. O par de decisão honesto: mantenha requisitos pontuais na descrição ou nos comentários da Task; crie uma Skill quando a mesma capacidade precisar estar disponível em execuções futuras.
Mais alguns casos em que a resposta certa é não criar uma Skill. Se um procedimento vive no diretório de Skills de um Runtime local e só as execuções daquele Computer precisam dele, deixe-o local. Se duas Skills candidatas se sobrepuserem muito no mesmo Agente, una-as ou refine-as antes de vincular qualquer uma. E, se você não consegue escrever a frase de descrição, o processo ainda não está estável o suficiente para ser documentado.
Comece com um procedimento
Escolha um procedimento que sua equipe repete e do qual, discretamente, depende de uma só pessoa. Escreva-o como uma única Skill bem específica: um nome, uma descrição que diga quando ela se aplica e instruções que definam o processo e a saída esperada. Defina o escopo como o seu Space. Vincule-a a um Agente, atribua a esse Agente uma Task real e leia o que volta.
Esse é o ciclo completo. O conhecimento que vivia na cabeça de um desenvolvedor agora tem nome, escopo, responsável e um único lugar para ser atualizado. Se você é novo na plataforma, a visão geral da Sharkly explica como as Skills se encaixam ao lado de Tasks, Agentes e Computers, e o guia de primeiros passos com a Sharkly percorre a primeira conexão do início ao fim. A documentação de Skills cobre todas as regras acima em detalhes.
Perguntas frequentes
Qual é a diferença entre uma Skill e as instruções de um Agente?
As instruções do Agente definem o comportamento estável de um papel: seu escopo, quando pedir informações e como reportar. Uma Skill é um procedimento reutilizável que vários Agentes podem compartilhar, empacotado com seus próprios arquivos de apoio e permissões. Se um parágrafo está sendo copiado de um Agente para outro, ele pertence a uma Skill.
Posso alterar o escopo de uma Skill depois de criá-la?
Não. O escopo de uma Skill é fixado na criação. Quando o público precisa mudar, crie uma nova Skill no escopo correto e revincule os Agentes que precisam dela. É por isso que a documentação recomenda escolher desde o início o escopo mais restrito que corresponda ao público pretendido.
Skills importadas permanecem sincronizadas com a origem?
Não. Instalar a partir de uma fonte pública compatível cria uma cópia gerenciada no escopo escolhido, e importar de um Runtime local copia a Skill para a organização enquanto a cópia local original permanece separada. A partir daí, sua organização controla a cópia dela.
Vincular uma nova Skill afeta as Tasks em execução de um Agente?
Não. Alterações nas vinculações de Skills de um Agente se aplicam às execuções seguintes. O trabalho já em andamento termina com a configuração com que começou, e a próxima execução assume o conjunto de Skills atualizado.
É seguro instalar Skills de fontes públicas?
Pode ser, desde que você as revise. Trate toda Skill externa ou importada localmente como código ou configuração de terceiros: leia as instruções e os arquivos de apoio antes de vincular, mantenha os comandos com o mínimo de privilégios e nunca permita segredos em uma Skill. A validação de upload da Sharkly rejeita caminhos e entradas de arquivo inseguros, mas o julgamento sobre se as instruções merecem a confiança da sua equipe continua sendo das pessoas.
