🧩 Skills

Uma skill é um diretório dentro de ~/.claude/skills/ com obrigatoriamente um arquivo SKILL.md na raiz. A pasta pode conter subpastas (scripts/, prompting/, references/) e arquivos auxiliares.

Entender que a skill é uma pasta — e não apenas um arquivo — muda como você organiza o conhecimento. Você separa regras (SKILL.md) de execução (scripts/) de documentação (references/), mantendo tudo modular e fácil de manter.

Diretório raiz em ~/.claude/skills/nome-da-skill/; SKILL.md obrigatório; subpastas opcionais mas recomendadas para skills complexas; nome do diretório em kebab-case.

O frontmatter YAML no topo do SKILL.md define os metadados da skill: name (identificador único), description (o que faz e quando disparar), e opcionalmente triggers (frases-gatilho explícitas).

O frontmatter é o "contrato" da skill com o agente. Uma description fraca resulta em skill que nunca dispara ou dispara quando não deve. Um frontmatter bem escrito garante que o Claude Code saiba exatamente quando invocar a skill.

Bloco delimitado por ---; campos name e description obrigatórios; descrição em linguagem natural; YAML válido sem tabs.

Após o frontmatter, o SKILL.md contém o corpo em Markdown com: fluxo de trabalho (seções numeradas), regras rígidas ("NUNCA faça X"), exemplos de bom e mau uso, referências a arquivos auxiliares e gates de confirmação antes de ações irreversíveis.

O corpo é o cérebro da skill. É aqui que você programa o comportamento detalhado: ordem de passos, o que verificar, como reportar resultados. Um bom corpo substitui dezenas de prompts manuais repetitivos.

Seções com ## para fluxo; listas - para passos; blocos ``` para código; tabelas para comparação bom/mau; hard rules em destaque (**NUNCA**); referências a ./scripts/ e ./references/.

Skills globais ficam em ~/.claude/skills/ e estão disponíveis em qualquer projeto. Skills locais de projeto podem ficar em .claude/skills/ na raiz do repo — escopo restrito ao projeto.

Separar skills globais (utilitários reutilizáveis) de skills de projeto (lógica específica do repo) evita poluição de namespace e garante que skills sensíveis de um cliente não vazem para outros projetos.

Global: ~/.claude/skills/; Local: .claude/skills/; Local sobrescreve global de mesmo nome; skills se aplicam ao contexto ativo.

O Claude Code varre o diretório de skills e injeta os metadados (name + description) no contexto do sistema. Quando a mensagem do usuário bate com a description, o agente usa a ferramenta Skill para carregar e executar o SKILL.md completo.

Entender o mecanismo de descoberta explica por que a description é o campo mais crítico. O agente não lê o corpo da skill até decidir ativá-la — a descrição é o único sinal de relevância disponível no momento da decisão.

Varredura automática ao iniciar; injeção de metadados no sistema prompt; match semântico description ↔ pedido do usuário; ativação lazy (corpo só é lido quando ativada).

Skill = comportamento especializado reutilizável com estado e regras (ex.: formato-curso). Prompt = instrução pontual sem persistência. Comando slash = atalho de teclado para prompt repetitivo. Skills carregam contexto, scripts e referências; prompts e comandos não.

Escolher a ferramenta errada custa tempo. Um workflow complexo de 10 etapas virou um prompt? Vai esquecer passos. Transformou em skill? O agente garante execução completa toda vez.

Skill: persistente, multi-arquivo, com regras; Prompt: stateless, inline, descartável; Comando slash: atalho rápido; Use skill quando: fluxo complexo, regras rígidas, scripts auxiliares necessários.

O campo description do frontmatter é analisado semanticamente pelo agente. Ele compara a mensagem do usuário com todas as descriptions disponíveis e aciona a skill de maior relevância. Uma description ruim = skill invisível.

Sem entender como o agente usa a description, você escreverá skills que nunca disparam ou skills que competem entre si. A description é o único "anúncio" da skill — precisa ser claro, específico e cobrindo os cenários reais de uso.

Match semântico (não literal); description como "anúncio"; especificidade > generalidade; incluir verbo de ação ("Use quando...", "Acionar ao..."); cobrir variações de linguagem do usuário.

Frases-gatilho são cláusulas explícitas na description que listam os cenários de ativação: "Use quando o usuário pedir para criar páginas HTML de curso", "Acionar ao mencionar trilhas, módulos ou INEMA.CLUB". São a "lista de casos de uso" da skill.

Frases-gatilho explícitas tornam o comportamento de ativação previsível e auditável. Sem elas, a ativação vira adivinhação. Com elas, você pode testar: "se eu disser X, a skill Y deve disparar?"

Prefixos padrão: "Use quando", "Acionar ao", "TRIGGER when"; listar contextos (não apenas palavras-chave); incluir sinônimos do domínio; separar por ponto e vírgula para clareza.

Cláusulas SKIP na description listam os casos onde a skill NÃO deve disparar, mesmo que haja sobreposição temática. Ex.: "SKIP: arquivo importa openai, código genérico sem SDK Anthropic". Delimita o escopo com precisão cirúrgica.

Skills muito genéricas disparam para tudo e adicionam ruído. SKIP cria contornos nítidos: a skill é especialista em X, não em tudo que superficialmente parece X. Reduz conflitos entre skills e promove precisão.

Prefixo "SKIP:" explícito; lista de anti-casos; complementa o TRIGGER; quanto mais específica a skill, menos SKIP você precisa; teste de negação ("se fizer Y, não deve disparar").

O nome da pasta e do campo name no frontmatter seguem kebab-case: letras minúsculas, palavras separadas por hífen. Ex.: formato-curso, ads-skill, n8n-code-python.

Kebab-case é URL-safe, filesystem-safe e visualmente legível no terminal. Permite comandos slash automáticos (/formato-curso) e referências sem aspas em scripts bash. Misturar convenções cria bugs silenciosos.

Tudo minúsculo; separador hífen; sem espaços, underscores ou camelCase; nome descritivo (2-4 palavras); coerência pasta ↔ frontmatter name; evitar abreviações ambíguas.

Uma boa description combina: (1) o que a skill faz em 1 frase, (2) frases-gatilho cobrindo múltiplas formulações, (3) SKIP delimitando o escopo. Ex. da skill claude-api: "Build, debug, and optimize Claude API apps. TRIGGER when: code imports anthropic/SDK. SKIP: openai, other-provider SDK."

Ler exemplos reais acelera o aprendizado mais do que qualquer teoria. Patterns que funcionam em produção revelam nuances que documentação teórica omite: tamanho ideal, nível de especificidade, equilíbrio TRIGGER/SKIP.

3-6 linhas de description é o ideal; frase-resumo + TRIGGER + SKIP; testar com 5 perguntas reais antes de publicar; revisar após usar 10 vezes na prática.

Descriptions ruins são: (1) genéricas demais — "Ajuda com código" (tudo é código), (2) ambíguas — "Usa quando precisa de IA" (toda skill usa IA), (3) técnicas demais — "Processa tokens via API" (usuário não pensa assim), (4) sem TRIGGER/SKIP — deixa o agente adivinhar.

Erros de description causam problemas silenciosos: a skill existe mas nunca é usada, ou pior, dispara em contextos errados e produz resultados inesperados. Identificar os anti-patterns evita horas de debug.

Anti-patterns: vago, circular, técnico demais, sem âncoras de contexto; teste de "1 frase": alguém sem conhecimento da skill consegue saber quando usá-la só lendo a description?

A subpasta scripts/ contém arquivos .sh (ou .py, .js) que o agente pode executar via Bash. Cada script realiza uma tarefa atômica: verificar dependências, processar arquivos, chamar APIs, formatar saída. O SKILL.md referencia cada script pelo caminho relativo.

Scripts externalizam a lógica operacional do SKILL.md, mantendo-o legível. Um script de 50 linhas não deveria estar inline no markdown — vai para scripts/ e o SKILL.md apenas descreve quando e como chamá-lo.

Scripts atômicos (1 script = 1 responsabilidade); nomear com verbo-substantivo (check-deps.sh, analyze-video.sh); chmod +x necessário; path relativo no SKILL.md (./scripts/check.sh).

Arquivos reference.md (ou em references/) contêm documentação detalhada: specs de API, tabelas de decisão, exemplos extensos, histórico de decisões. O SKILL.md os menciona mas não duplica o conteúdo — "ver reference.md para a tabela completa".

SKILL.md precisa ser curto e escaneável — o agente o lê completamente a cada ativação. Detalhes extensos no SKILL.md aumentam o custo de tokens e dificultam a leitura. References são carregados sob demanda, quando necessário.

SKILL.md curto (50-150 linhas); references longos (sem limite); link explícito no SKILL.md; subpasta references/ para múltiplos arquivos; README.md explicando cada arquivo da pasta.

O arquivo .env.example lista as variáveis de ambiente necessárias com valores de exemplo (nunca reais). O usuário copia para .env e preenche. Scripts leem de $VARNAME — nunca hardcoded. O SKILL.md instrui o agente a verificar se o .env existe antes de usar a skill.

Chaves de API no código ou nos logs são vulnerabilidades graves. .env.example é o padrão da indústria: documenta o que é necessário sem expor segredos. Uma skill que respeita isso não vaza credenciais por acidente.

.env.example no repo (sem valores reais); .env real no .gitignore; scripts usam os_environ ou source .env; gate de verificação no SKILL.md ("checar se .env existe"); hard rule "NUNCA logar API key".

Progressive disclosure é o princípio de mostrar primeiro o essencial e aprofundar sob demanda. No contexto de skills: SKILL.md contém o fluxo principal + links para detalhes; references/ e scripts/ contêm os detalhes. O agente decide quando mergulhar na documentação extra.

Um SKILL.md de 500 linhas é difícil de ler, caro em tokens e propenso a contradições internas. Progressive disclosure força clareza: o que é sempre necessário fica no principal; o que é raramente necessário fica nos detalhes.

Nível 1 (SKILL.md): fluxo, regras críticas, referências; Nível 2 (references/): specs detalhadas, tabelas extensas; Nível 3 (scripts/): implementação; links explícitos entre níveis; SKILL.md lido sempre, detalhes lidos quando relevante.

Hard rules são restrições absolutas escritas em MAIÚSCULAS no SKILL.md: "NUNCA logar a API key", "SEMPRE pedir confirmação antes de deletar", "JAMAIS parafrasear o transcript — verbatim apenas". Diferem de guidelines (sugestões) — são invioláveis.

Hard rules protegem contra os erros mais caros: vazamento de dados, gasto desnecessário de créditos, perda irreversível de arquivos. São a rede de segurança da skill — quanto mais crítica a skill, mais importantes as hard rules.

Formatação: "NUNCA", "SEMPRE", "JAMAIS" em maiúsculas; seção dedicada "## Hard Rules" no SKILL.md; 3-7 regras (mais que isso vira ruído); cada regra com justificativa curta; testar cada regra com um caso adversarial.

Gates de confirmação são checkpoints no fluxo da skill onde o agente para e pergunta ao usuário antes de executar uma ação cara, irreversível ou de alto impacto. Ex.: "Você confirma gerar o vídeo? (isso usa 10 créditos Arcads)". Implementados como passos explícitos no SKILL.md.

Gates salvam dinheiro e tempo. Uma skill de geração de vídeo sem gate pode disparar 50 gerações acidentais em um loop. O custo de confirmar é zero; o custo de não confirmar pode ser enorme. Gates também melhoram a confiança do usuário na skill.

Gate antes de ações custosas ($$); gate antes de ações irreversíveis (delete, publish); mostrar custo/impacto estimado; oferecer opção de cancelar; documentar gates na seção "Fluxo" do SKILL.md.

A ads-skill faz 2 coisas distintas: (1) Análise: extrai frames+áudio de um vídeo UGC via ffmpeg, identifica a estrutura narrativa HOOK→SHOW→PROOF→CTA e produz um relatório viral; (2) Geração: recebe 4 inputs (imagem/áudio/vídeo/ator) e gera um novo anúncio via API Arcads, roteando pelo melhor modelo.

Ver uma skill com dois poderes complementares mostra como agrupar funcionalidades relacionadas em vez de criar 2 skills separadas. Análise + geração são inseparáveis no workflow de ads — a análise informa os inputs para a geração.

Skill multimodal (processa vídeo/áudio/imagem); ffmpeg para extração de frames; estrutura UGC 15s: [0-2s HOOK][2-6s SHOW][6-11s PROOF][11-14s CTA][14-15s LOGO]; API Arcads para geração.

A skill roteia entre 4 modelos: Seedance 2.0 (padrão, melhor lip sync), Veo 3.1 (frame inicial travado, consistência visual), Sora 2 (vídeos longos/cinematográficos), Kling 3.0 (conteúdo silencioso/estético). A lógica de roteamento fica em prompting/model-routing.md.

Roteamento inteligente dentro de uma skill mostra como o SKILL.md pode conter lógica de decisão não-trivial. Em vez de o usuário precisar conhecer 4 modelos, a skill abstrai a escolha com regras claras.

Seedance: padrão para UGC com fala; Veo: quando o frame de referência é crítico; Sora: >30s ou estilo cinematográfico; Kling: sem áudio, foco visual; regras em arquivo dedicado de roteamento.

A ads-skill tem: SKILL.md (frontmatter + fluxo + hard rules), scripts/arcads_check.sh, arcads_analyze.sh, arcads_actors.sh, arcads_upload.sh, arcads_generate.sh, arcads_talking.sh, arcads_status.sh + prompting/ com 3 arquivos + reference.md + .env.example.

A estrutura da ads-skill é um template de referência para qualquer skill que integra API externa. Os 7 scripts cobrem o ciclo completo: check (dependências) → analyze (input) → actors (opções) → upload (mídia) → generate (job) → talking (variante) → status (polling).

Scripts nomeados com prefixo da API (arcads_*); ciclo check→analyze→upload→generate→status; prompting/ com 3 arquivos (viral-analysis, ugc-formulas, model-routing); reference.md com docs da API.

As 3 hard rules da ads-skill: (1) NUNCA parafrasear o transcript do vídeo — sempre verbatim; (2) SEMPRE rodar o "dialogue gate" antes de gerar (confirmar inputs com o usuário para não gastar créditos Arcads à toa); (3) NUNCA logar a API key em nenhum output ou log de debug.

Estas 3 regras protegem: (1) a integridade do conteúdo viral (parafrasear mata o timing); (2) o orçamento (geração de vídeo custa dinheiro real); (3) a segurança (API keys vazadas = conta comprometida). São o mínimo inegociável para usar a skill em produção.

Verbatim: copiar texto exato, não resumir nem reescrever; dialogue gate: tela de confirmação com custo estimado; API key: ler de $ARCADS_API_KEY, nunca imprimir; 3 regras = lembráveis e testáveis.

O framework UGC de 15s: [0-2s HOOK] pattern-interrupt que para o scroll; [2-6s SHOW] demonstração do produto/benefício; [6-11s PROOF] número/resultado/social proof; [11-14s CTA] chamada para ação clara; [14-15s LOGO] marca. A skill identifica e extrai cada segmento automaticamente.

O framework UGC 15s é o padrão de ouro para anúncios virais em mobile. Entendê-lo permite avaliar um UGC existente, identificar onde está fraco e regenerar os segmentos com problema — exatamente o que a skill faz.

HOOK (0-2s): surpresa, pergunta, contradição; SHOW (2-6s): demo real, não stock; PROOF (6-11s): número concreto, não vago; CTA (11-14s): 1 ação específica; LOGO (14-15s): branding rápido.

A ads-skill materializa todos os conceitos: (3.1) pasta com SKILL.md + anatomia completa; (3.2) description com TRIGGER para "analisar UGC" + SKIP para vídeos não-publicitários + nome kebab-case; (3.3) 7 scripts atômicos + 3 references + .env.example + progressive disclosure + 3 hard rules + dialogue gate.

Ver os conceitos em código real elimina a ambiguidade da teoria. Cada decisão de design da ads-skill tem uma razão — e entender o "por quê" de cada escolha prepara você para criar suas próprias skills de produção.

Teoria (3.1-3.3) → implementação (ads-skill); cada elemento da skill mapeia para um conceito; boa skill = checklist dos módulos anteriores; sua próxima skill: copiar a estrutura, adaptar o domínio.