Construtor de Habilidades de IA

O que Construtor de Habilidades de IA faz?

Construa Habilidades de Agente usando o formato SKILL.md compartilhado e a metodologia da Anthropic: o menor núcleo portátil que funciona em cada destino nomeado, mais adaptadores de tempo de execução explícitos. Portabilidade é uma afirmação de compatibilidade testada, não um estilo de formatação. references/sources.md cita a documentação do host para Claude Code, Codex e Qwen Code; todos os outros hosts não foram testados aqui, portanto, verifique o que você está segmentando (Etapa 1).

Esta metodologia exige deliberadamente regiões XML semânticas consistentes dentro do corpo do Markdown. Isso é uma política de qualidade para reduzir ambiguidades em instruções operacionais complexas, suportada pelas atuais diretrizes de prompt da Anthropic e verificada pelos testes de avanço na Etapa 4. Não é um requisito do analisador da especificação portátil do Agent Skills, um limite de autorização ou uma afirmação de que apenas XML impede injeção de prompt.

Fonte primária da metodologia: "The Complete Guide to Building Skills for Claude" (Anthropic, Janeiro de 2026)

• PDF: https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf
• Texto extraído: references/ai-skill-builder-guide.md

Fonte do formato portátil: https://agentskills.io/specification

---

Início Rápido

Para criar uma habilidade do zero, siga o processo de 4 fases abaixo. Para melhorar uma habilidade existente, leia references/refining-skills.md. Para validar a estrutura, execute scripts/audit-skill.sh.

Invocar com: peça por ai-skill-builder; os hosts podem expô-lo como /ai-skill-builder, $ai-skill-builder, ou através do seletor de habilidades deles.

Requisitos P0

Cada habilidade produzida por esta metodologia atende a todos os treze. Cite-os por ID em auditorias e revisões.

1. SKILL-REQ001-descobrir-destinos-de-execução. Identifique produtos, versões, modos de invocação, raízes de instalação, limites de confiança e semântica do sistema de arquivos exatos antes de escrever.
2. SKILL-REQ002-separar-padrão-de-extensões. Mantenha a especificação do Agent Skills, extensões de tempo de execução e convenções do projeto em colunas separadas. Nunca apresente um campo específico do Claude, Codex, Copilot, Gemini ou estrutura como universal.
3. SKILL-REQ003-usar-núcleo-portátil-válido. Coloque um SKILL.md obrigatório em um diretório cujo nome corresponda ao seu name portátil; inclua uma description específica que diga o que a habilidade faz e quando usá-la. Use campos opcionais padrão apenas quando necessário.
4. SKILL-REQ004-usar-regiões-xml-semânticas. Envolva cada região operacional principal em tags XML consistentes e descritivas dentro do corpo do Markdown, como <purpose>, <requirements>, <workflow>, <examples> e <output_contract>. Mantenha o Markdown dentro dessas regiões e o código fonte literal em blocos de código com cercadura. Esta regra metodológica obrigatória visa a separação de instruções da mais alta qualidade; não é um requisito do analisador do Agent Skills ou um limite de segurança. scripts/audit-skill.sh falha em um corpo sem região, uma tag desbalanceada ou mal aninhada, ou um título ## fora de cada região.
5. SKILL-REQ005-projetar-divulgação-progressiva. Mantenha a descrição de ativação precisa e o fluxo de trabalho principal conciso. Mova detalhes verdadeiramente condicionais para referências focadas e diretamente vinculadas; mantenha a automação reutilizável em scripts e materiais de saída em ativos.
6. SKILL-REQ006-preservar-contexto-operacional. Cada referência ou script deve dizer quando usá-lo, quais entradas aceita, o que retorna ou altera e como a falha é relatada. Evite cadeias de referência profundas.
7. SKILL-REQ007-tornar-invocação-correta. Teste a ativação automática e a invocação explícita. Onde um tempo de execução suportar parâmetros, teste entradas vazias, posicionais, nomeadas, entre aspas, Unicode, inválidas e grandes. Não presuma que outro tempo de execução implementa a mesma sintaxe de substituição.
8. SKILL-REQ008-minimizar-autorização-de-ferramenta. Trate habilidades e scripts empacotados como dependências executáveis. Solicite a menor autoridade necessária, valide entradas, preserve prompts de aprovação quando prático e nunca descreva delimitadores de prompt como prevenção de injeção de prompt.
9. SKILL-REQ009-validar-todo-arcabouço. Valide descoberta, carregamento, referências, scripts, argumentos, links simbólicos, resolução de duplicatas, atualizações e remoção em cada arcabouço suportado. Passar em um analisador não prova compatibilidade entre tempos de execução.
10. SKILL-REQ010-preservar-estado-do-usuário. A instalação e desinstalação devem possuir caminhos exatos gerados, preservar edições manuais, suportar múltiplas raízes de habilidade configuradas e remover apenas links ou arquivos de propriedade do instalador.
11. SKILL-REQ011-medir-custo-de-contexto-e-execução. Registre tamanho dos metadados de descoberta, tamanho das instruções carregadas, custo de referência condicional, tempo/memória/E/S do script e carregamento duplicado. Trate metas de linha e token como heurísticas, a menos que um tempo de execução de destino as torne normativas.
12. SKILL-REQ012-testar-avanço-em-tarefas-reais. Use prompts realistas positivos, negativos, ambíguos e adversariais. Verifique o resultado da tarefa, não meramente se a habilidade apareceu em uma lista.
13. SKILL-REQ013-separar-criação-de-execução. Classifique se a tarefa é alterar a habilidade, usar a habilidade para produzir um artefato ou resultado, ou avaliar a habilidade com base em evidências. Entradas de tempo de execução, saídas geradas, exemplos e observações de dogfood não se tornam instruções de habilidade, a menos que uma decisão explícita de criação as aceite e generalize.

Os nomes das regiões seguem a tarefa, em vez de uma taxonomia universal: fluxos de trabalho usam <workflow>, habilidades de referência podem usar <decision_guide>, habilidades de modo múltiplo <routing>, contratos de resultado estritos <output_contract>, material de referência embutido <reference> e ponteiros para arquivos e fontes empacotados <resources>. As tags devem ser consistentes, descritivas, balanceadas e não mais profundamente aninhadas do que a tarefa exige. A matriz padrão versus extensão, a auditoria de afirmação e o recibo de validação por host residem em references/portability-and-claim-audit.md.

Como Funciona

Metodologia de quatro fases do guia da Anthropic. Cada fase carrega uma Definição de Pronto: a condição que deve ser mantida antes do início da próxima fase.

Fase	Atividade	Definição de Pronto
1: Planejamento e Design	Definir hosts de destino, casos de uso, categoria, critérios de sucesso	Critérios são mensuráveis e a categoria é escolhida
2: Implementação	Criar pasta, escrever SKILL.md, adicionar recursos	audit-skill.sh não relata falhas
3: Teste	Testes de acionamento, funcionais, de desempenho, de compatibilidade, de avanço	Cada host nomeado passa com um recibo de validação; linha de base registrada
4: Distribuição	Empacotar, documentar, publicar	Instalação verificada a partir de uma raiz limpa

A Fase 1 cobre as Etapas 1–2 abaixo; as Fases 2–4 correspondem às Etapas 3–5.

Quanto tempo uma fase leva depende de quem ou o que a executa, portanto, esta habilidade não declara estimativas de tempo real e as habilidades que você construir também não devem.

---

Fluxo de Trabalho de Criação de Habilidade

Etapa 1: Descobrir Requisitos

Pesquise o domínio primeiro — use as ferramentas da web do host para verificar as melhores práticas atuais antes de escrever instruções. Orientação desatualizada é pior que nenhuma: um agente a segue com confiança.

Retenha todas as fontes: registre cada URL consultado com uma nota do que foi confirmado. A orientação sem fonte não pode ser verificada ou atualizada.

Para estratégias de pesquisa, padrões de qualidade de fonte e o formato obrigatório da seção Fontes: references/research.md

1. Classifique a solicitação: criação (alterar a habilidade), execução (usar a habilidade para produzir um resultado) ou avaliação (julgar a habilidade com base em evidências). Nomeie o artefato e o limite de mutação antes de usar o conteúdo da tarefa como entrada de design (SKILL-REQ013).
2. Identifique o problema e os usuários-alvo
3. Identifique cada host e versão de destino, sua raiz de descoberta, forma de invocação e comportamento de recarregamento. Marque desconhecidos como desconhecidos em vez de adivinhar. Inspecione as raízes de habilidade existentes e a orientação do projeto antes de criar um pacote paralelo.
4. Defina 2-3 casos de uso concretos
5. Defina critérios de sucesso mensuráveis (tempo economizado, erros reduzidos, qualidade melhorada)
6. Escolha uma categoria de habilidade:

Categoria	ENTRADA → SAÍDA	Exemplos
1: Criação de Documento e Ativo	Dados/especificações → documento, código, relatório	Gerador de teste de API, resumidor de notas de reunião
2: Automação de Fluxo de Trabalho	Parâmetros de tarefa → processo de várias etapas concluído	Pipeline de implantação, fluxo de trabalho de revisão de código
3: Aprimoramento de MCP	Saídas de ferramenta MCP → orquestração mais inteligente	Pesquisa de arquivo inteligente, assistente BigQuery

Para orientação aprofundada de categoria: references/categories.md Para perguntas interativas de descoberta: references/discovery.md

Etapa 2: Projetar Estrutura

Projete usando divulgação progressiva — 3 níveis de carregamento:

Nível	Quando carregado	Comprimento alvo	Conteúdo
1: Metadados	Sempre (~100 palavras)	nome + descrição	Condições de acionamento
2: Corpo SKILL.md	Quando a habilidade aciona	abaixo de 5.000 palavras (idealmente abaixo de 2.000)	Fluxo de trabalho principal + ponteiros
3: Arquivos references/	Conforme necessário	Ilimitado	Detalhes profundos, esquemas, exemplos

Para dicas de escrita de divulgação progressiva e métricas de sucesso: references/best-practices.md

Etapa 3: Implementar

Regras Críticas:

• ✅ O arquivo DEVE ser nomeado SKILL.md (não README.md)
• ✅ O nome da pasta DEVE ser em kebab-case — sem espaços, sem maiúsculas (my-skill não My Skill)
• ✅ O frontmatter YAML DEVE incluir name e description; coloque uma versão sob metadata
• ✅ A descrição DEVE incluir frases de acionamento específicas — o que os usuários DIZEM para ativar a habilidade
• ✅ A descrição deve ter menos de 1024 caracteres (limite rígido — descrições mais longas são truncadas)
• ✅ Sem colchetes angulares XML (< ou >) em nenhum campo do frontmatter — uma restrição do host do guia de habilidade da Anthropic, não uma regra YAML; o corpo não é afetado
• ✅ Corpo: cada seção principal fica dentro de uma região XML balanceada e descritiva em sua própria linha (<purpose>, <requirements>, <workflow>, <examples>, <output_contract>), Markdown dentro, código fonte literal em blocos de código com cercadura (SKILL-REQ004). O título H1 pode permanecer fora.
• ❌ NENHUM README.md dentro da pasta de habilidade — todos os documentos vão em SKILL.md ou references/ (Exceção: um README.md na RAIZ do repositório GitHub, fora da pasta de habilidade, é aceitável para o GitHub.)
• ❌ NENHUM espaço ou sublinhado em nomes de pasta (my_skill → my-skill)

Frontmatter: campos obrigatórios:

---
name: nome-da-sua-habilidade          # apenas kebab-case; sem espaços, maiúsculas ou sublinhados
description: O que faz. Use quando o usuário pedir "frase específica", "outra frase".
             # DEVE incluir: o que faz + quando usar (condições de acionamento)
             # Menos de 1024 caracteres. Sem colchetes angulares XML.
             # NÃO comece com "claude" ou "anthropic" (namespaces reservados).
---

Para cada campo opcional (license, compatibility, allowed-tools, metadata) com notas de portabilidade de host: references/best-practices.md

Linguagem de posicionamento ("gera testes 87% mais rápido") pertence ao README do repositório, nunca em description. Veja references/best-practices.md.

Estrutura de pasta (exemplo autônomo do Claude Code anotado: references/best-practices.md, seção "Padrões de Estrutura de Pasta"):

Diretório	Carregar no contexto?	Use para
references/	Sim, conforme necessário	Esquemas, documentos de API, políticas, guias de fluxo de trabalho
references/examples/	Conforme necessário	Código funcional que os usuários copiam e adaptam
scripts/	Não (execute diretamente)	Validadores, scaffolders, utilitários
assets/	Não (usado na saída)	Imagens, fontes, modelos HTML que a habilidade cola na saída

Nota: Habilidades de plugin (em nome-do-plugin/skills/) podem colocar examples/ no nível superior — essa é uma convenção de desenvolvimento de plugin. Para habilidades autônomas ~/.claude/skills/, coloque exemplos dentro de references/.

Para criar uma nova habilidade: bash scripts/scaffold-skill.sh nome-da-minha-habilidade (defina SKILLS_DIR para segmentar a raiz de outro host) Para começar a partir de um modelo: copie references/examples/SKILL-template.md

Etapa 4: Testar

Cinco abordagens de teste (execute em ordem):

1. Testes de acionamento — verifique se o agente ativa com frases esperadas e não em solicitações não relacionadas
2. Testes funcionais — valide se o fluxo de trabalho principal da habilidade produz saída correta para entradas conhecidas
3. Testes de desempenho — meça a melhoria em relação à linha de base (tempo economizado, redução de erros, consistência)
4. Testes de compatibilidade — verifique descoberta, invocação explícita, carregamento de referência, execução de script e resolução de duplicatas/nomes em cada host e versão nomeados. Inicie uma sessão limpa para cada host, execute o próprio validador do host onde existir (o Codex envia skill-creator/scripts/quick_validate.py), teste reexecuções do instalador, múltiplas raízes, destinos de link simbólico, arquivos de usuário modificados e desinstalação, e registre um recibo de validação por host (references/portability-and-claim-audit.md).
5. Testes de avanço — prompts realistas positivos, negativos, ambíguos e adversariais; julgue o resultado da tarefa, não se a habilidade apareceu em uma lista, e verifique se ela não aciona excessivamente tarefas próximas (SKILL-REQ012)

Depurando problemas de acionamento:

Pergunte ao agente: "Quando você usaria a habilidade [nome da habilidade]?"

O agente deve citar sua descrição de volta. Ajuste com base no que está faltando ou muito vago.

Corrigindo sub-acionamento: Adicione mais frases de acionamento específicas e termos técnicos relevantes.

Corrigindo super-acionamento: Adicione acionadores negativos à descrição:

description: Processa documentos jurídicos em PDF para revisão de contratos. Use para "revisar este contrato",
  "analisar documento jurídico", "extrair cláusulas de contrato". NÃO use para visualização geral de PDF,
  extração de imagens ou documentos não jurídicos (use a habilidade doc-converter).

Para o guia completo de diagnóstico e correção cobrindo todos os quatro modos de falha: references/troubleshooting.md

Para validar a estrutura:

bash scripts/audit-skill.sh /caminho/para/SUA-HABILIDADE

...

[cortado para tradução]

</workflow>