Agent Skills & Custom Workflows

1. Visão geral do conceito e problema sistêmico

Com o aumento da complexidade dos sistemas agentic, os desenvolvedores frequentemente tentam fornecer ao agente expertise em todas as áreas simultaneamente: escrevem regras gigantescas de formatação de código, checklists de segurança de servidores, requisitos de acessibilidade de UI, sintaxe de dialetos SQL e templates de documentação.

A tentativa de empacotar tudo isso em um único prompt estático (system prompt) gera três problemas sistêmicos críticos:

1. Esgotamento catastrófico do orçamento de tokens: Mesmo para uma solicitação banal como "corrigir erro de digitação", o modelo é forçado a ler 40.000 tokens de documentação irrelevante a cada interação.
2. Diluição de contexto e degradação no seguimento de instruções (Instruction Drift): Quanto mais regras conflitantes ou heterogêneas estiverem presentes no contexto, maior a probabilidade de o modelo ignorar diretrizes específicas.
3. Impossibilidade de atualização modular: Alterar uma regra em um arquivo monolítico pode alterar imprevisivelmente o comportamento do agente em tarefas completamente distintas.

Agent Skills resolvem esse problema através do princípio da separação procedural de contexto: o conhecimento é armazenado como módulos isolados no disco e carregado na memória operacional do agente apenas quando surge uma necessidade de engenharia correspondente.

2. Taxonomia arquitetural e modelo mental

A arquitetura moderna de um Agent Skill é padronizada como um pacote autônomo de conhecimento procedural:

• 1. Manifesto e gatilhos de ativação (Frontmatter Metadata): Metadados em formato YAML no início do arquivo SKILL.md. Definem o nome, a descrição da competência e a lista de gatilhos em linguagem natural (por exemplo: "comprou VPS", "configurar firewall", "check accessibility").
• 2. Guia algorítmico de ações (Workflow Blueprint): Um algoritmo passo a passo claro, dividido em fases: diagnóstico -> preparação do plano -> execução passo a passo -> verificação final obrigatória do resultado.
• 3. Scripts executáveis e utilitários (scripts/): Scripts determinísticos em Python, Bash ou Node.js que o agente invoca para realizar cálculos rotineiros ou verificações, em vez de gerar tudo do zero de forma lenta e propensa a erros.
• 4. Referências e exemplos canônicos (references/): Padrões ouro de arquitetura, esquemas de configuração (Nginx, Docker Compose, interfaces TypeScript) que o agente usa como template para replicação.

3. Pipeline técnico e mecânica interna

O ciclo de vida da ativação de um skill pelo agente ocorre em 4 etapas:

1. Lightweight Index Discovery (Descoberta do catálogo): Na inicialização, o agente recebe apenas um índice compacto dos skills disponíveis (2-3 frases de descrição por skill). Isso consome menos de 500 tokens.
2. Intent Matching & Trigger Interception (Correspondência de intenção): O usuário define uma tarefa. O agente correlaciona a semântica da solicitação com os manifestos dos skills. Se houver uma correspondência, o agente toma a decisão interna de carregar a expertise.
3. Lazy File Ingestion (Leitura sob demanda da instrução): O agente chama a ferramenta de arquivos (por exemplo, view_file para skills/<skill_name>/SKILL.md) e carrega a especificação completa diretamente no contexto de trabalho.
4. Execution & Context Retirement (Execução e liberação): O agente executa a tarefa seguindo estritamente as instruções do skill. Após a conclusão da tarefa e a fixação do resultado, sessões subsequentes não são sobrecarregadas com detalhes obsoletos.

4. Cenários práticos de engenharia em produção

01. Hardening procedural e proteção de Linux VPS

O agente possui o skill vps-hardening. Quando o usuário informa sobre a aquisição de um novo servidor, o agente carrega um checklist rigoroso de 7 etapas: geração de chaves SSH, configuração do UFW, configuração do fail2ban, tuning do sysctl e desativação do acesso por senha estritamente após a verificação do login via chave.

02. Auditoria especializada de design de acessibilidade (WCAG 2.2)

O usuário solicita uma avaliação do layout de um formulário. O agente ativa o skill better-accessibility: verifica o contraste de cores conforme APCA/WCAG, a presença de aria-labels, navegação por teclado (focus-visible) e compatibilidade com screen readers.

03. Migração automatizada de banco de dados para Drizzle ORM

O skill contém regras precisas para geração de schemas: convenções de nomenclatura snake_case, definição correta de índices, proibição de enums brutos e criação de arquivos de migração seguros sem bloqueio de tabelas.

5. Armadilhas, erros comuns e segurança

• Conflito de gatilhos (Trigger Overlap): Se dois skills diferentes tiverem descrições muito amplas ou semelhantes (por exemplo, code-review e security-audit), o agente pode carregar ambos, inflando o contexto, ou ficar indeciso na escolha. Torne as descrições dos gatilhos mutuamente exclusivas e contrastantes.
• Scripts utilitários desatualizados (Stale Tooling): Mudanças na API de bibliotecas externas podem quebrar scripts auxiliares dentro de scripts/. É necessário executar testes periodicamente para validar a funcionalidade do código do skill.
• Ausência de validação de segurança (Prompt Injection via Untrusted Skills): O carregamento de skills de terceiros de repositórios não confiáveis pode conter instruções ocultas para roubo de chaves privadas. Confie apenas em módulos de conhecimento verificados.