O mesmo
ficheiro,
sítios diferentes

1.1 O mapa das pastas

1.2 Como se chama uma skill, em cada uma

Três símbolos diferentes para a mesma acção — /, @ e $. É trivial e é a primeira coisa que confunde quem alterna entre ferramentas.

1.3 Uma diferença que morde: a ordem de precedência

1.4 O que este volume é

2.1 Onde põe, e o que descobre

Descobre também em pastas acima, até à raiz do repositório, e em pastas aninhadas abaixo — o que resolve bem o caso do monorepo: uma skill em apps/web/.claude/skills/ carrega quando o agente trabalha nessa subpasta, e fica disponível como apps/web:nome.

2.2 Invocar

# directa
/nome-da-skill

# com argumentos
/nome-da-skill argumento1 argumento2

# várias encadeadas, com argumentos no fim
/skill-1 /skill-2 argumentos

E automaticamente, pela description, a menos que a skill declare disable-model-invocation: true.

2.3 Os dois comandos que valem a pena conhecer

• /skills — lista o que está disponível com as descrições, e permite ligar e desligar a visibilidade de cada uma.
• /skill-doctor — mostra estatísticas de uso, custo em tokens e quais nunca são usadas. É a ferramenta de higiene: skills que nunca disparam estão a pagar o custo permanente do nível 1 sem devolver nada (volume I, cap. 3.4).

2.4 Os campos que só existem aqui

O Claude Code acrescenta uma dúzia de campos que não fazem parte da especificação:

2.5 Controlar o que aparece

// .claude/settings.local.json
{
  "skillOverrides": {
    "deploy": "off",                    // esconder por completo
    "legacy": "name-only",              // listar só o nome, sem descrição
    "review": "user-invocable-only"     // esconder do agente; a pessoa pode invocar
  },
  "disableBundledSkills": true,
  "skillListingBudgetFraction": 0.02,   // fatia do contexto para a listagem
  "skillListingMaxDescChars": 1536
}

O skillListingBudgetFraction é a resposta directa ao problema do volume I: há um orçamento de contexto para as descrições, e quando é ultrapassado as descrições são encurtadas — o que degrada a activação sem avisar. /skill-doctor mostra quando isso está a acontecer.

3.1 Onde põe

3.2 Invocar

• No ChatGPT: escreve-se @ e o nome da skill, como se mencionasse alguém.
• No Codex CLI: escreve-se $ e o nome.
• Automaticamente: em ambos, pela descrição, com o mesmo mecanismo de divulgação progressiva.

3.3 As duas skills embutidas que interessam

O instalador é conveniente e é exactamente onde o capítulo 11 do volume I se aplica com mais força: instalar com um comando não dispensa ler o que se instalou.

3.4 O ficheiro de configuração extra

Para além do SKILL.md, o Codex admite um agents/openai.yaml opcional com:

• interface — nome a mostrar, ícones, cor da marca.
• policy — nomeadamente allow_implicit_invocation, o equivalente ao disable-model-invocation do Claude Code.
• dependencies — declaração de ferramentas necessárias.

É a mesma decisão de desenho do Claude Code — estender o formato — resolvida ao contrário: as extensões ficam num ficheiro à parte em vez de no cabeçalho. Tem uma vantagem concreta de portabilidade: o SKILL.md mantém-se limpo e válido em qualquer ferramenta; outra simplesmente ignora o ficheiro extra.

3.5 O limite de listagem

3.6 Desligar

# ~/.codex/config.toml
[[skills.config]]
# entradas para desactivar skills concretas

4.1 Cursor: lê as pastas de toda a gente

E, por compatibilidade, carrega também as pastas do Claude e do Codex — é a implementação mais tolerante entre os editores dedicados. Só o VS Code lê mais (4.3). Descobre recursivamente qualquer subpasta que contenha um SKILL.md, o que permite organizar por temas sem configuração.

4.2 Gemini CLI: consentimento explícito

Precedência, do menor para o maior: embutidas < extensões < utilizador (~/.gemini/skills/ ou ~/.agents/skills/) < espaço de trabalho (.gemini/skills/ ou .agents/skills/).

# na sessão
/skills list [all] [nodesc]
/skills activate <nome>
/skills disable <nome>   /skills enable <nome>
/skills reload

# no terminal
gemini skills list --all
gemini skills install <url-do-repositório> --consent
gemini skills uninstall <nome> --scope workspace

4.3 GitHub Copilot e VS Code: seis pastas, e uma divergência interna

É a implementação com maior alcance de todas — não por ser a melhor, mas por estar onde as pessoas já estão. E é a mais permissiva a ler: seis caminhos, três de projeto e três pessoais.

Repare no primeiro: .github/skills/ é o único caso, em todo este volume, em que uma ferramenta põe as skills numa pasta que a equipa já tem e já revê. Não é um detalhe de arrumação — é a diferença entre uma skill que passa por code review como qualquer outro ficheiro e uma que vive numa pasta que ninguém abre.

E é a única que deixa acrescentar caminhos por configuração, com chat.agentSkillsLocations; e ler as personalizações do repositório-pai, com chat.useCustomizationsInParentRepositories — o que resolve o caso do monorepo, que nas outras ferramentas se resolve com ligações simbólicas.

Invoca-se por barra, com argumentos a seguir:

# escreva / para ver a lista
/webapp-testing para a página de entrada

Um aviso que a própria GitHub publica e que vale a pena repetir: as skills não são verificadas por ninguém e podem conter injecções de instruções, instruções escondidas ou scripts maliciosos. Numa pasta como .github/skills/, que entra no repositório por pull request, isto é um argumento a favor — é revista como código. Numa pasta pessoal instalada à pressa, não é.

4.4 E os outros

À data desta apostila, o registo oficial da norma lista cerca de meia centena de produtos compatíveis. Alguns que interessam a públicos diferentes:

5.1 claude.ai — para quem não programa

Isto muda quem pode escrever skills. Uma pessoa de marketing, de recursos humanos ou de contabilidade pode escrever um SKILL.md num editor de texto, comprimir a pasta e ter as convenções da sua área aplicadas automaticamente. Não é preciso perceber de programação — é preciso saber escrever instruções claras, que é o volume I.

5.2 Duas limitações do claude.ai que decidem a estratégia de equipa

5.3 A API — para quem constrói produtos

• Exige a ferramenta de execução de código. As skills correm no contentor dessa ferramenta; sem ela não funcionam.
• Indica-se o skill_id no parâmetro container. As pré-construídas são pptx, xlsx, docx e pdf.
• As próprias enviam-se pelos endpoints /v1/skills.
• Partilha por espaço de trabalho: todos os membros têm acesso. É o modelo de partilha que o claude.ai não tem.

5.4 As três superfícies, lado a lado

5.5 Duas restrições de nome que só existem aqui

6.1 O facto

É contraintuitivo porque tudo o resto na experiência sugere continuidade: é a mesma conta, o mesmo modelo, a mesma marca. E é exactamente por isso que se perde tempo — a suposição por omissão é que sincroniza, e não há erro nenhum a corrigi-la: a skill simplesmente não está lá.

6.2 Onde isto morde, caso a caso

6.3 As três estratégias

6.4 O script de sincronização, em oito linhas

#!/usr/bin/env bash
# fonte única: skills/ na raiz do repositório
set -euo pipefail
for d in skills/*/; do
  n=$(basename "$d")
  rsync -a --delete "$d" ".claude/skills/$n/"   # Claude Code
  rsync -a --delete "$d" ".agents/skills/$n/"   # Codex, Cursor, Gemini
  (cd skills && zip -qr "../dist/$n.zip" "$n")  # para enviar no claude.ai
done

Correr isto num hook de commit ou na integração contínua resolve o problema de vez, e torna a divergência impossível em vez de improvável — que é a diferença que interessa.

7.1 O núcleo comum

7.2 A pergunta que decide, no início

Decidir isto no início custa um minuto; descobri-lo no fim custa reescrever. É a mesma disciplina de declarar o objectivo antes de construir, de Estatística III, cap. 2.

7.3 Como degradar com elegância

Quando quer usar um campo específico e manter a portabilidade, o padrão é não depender dele:

O princípio é sempre o mesmo: o campo específico é uma optimização, não a fundação. Se a skill não funciona sem ele, não é portável — e isso pode ser aceitável, desde que esteja declarado.

7.4 Declare a compatibilidade

O campo compatibility existe precisamente para isto, faz parte da norma, e é ignorado por quase toda a gente:

compatibility: Desenhada para Claude Code. Usa os campos paths e context,
  que outras ferramentas ignoram. Requer acesso à rede — não corre na API.

Quem instalar sabe o que esperar antes de descobrir por tentativa. Custa uma linha e é a diferença entre uma skill que decepciona e uma que avisa.

7.5 Testar a portabilidade

8.1 As extensões, comparadas

8.2 O padrão que as duas primeiras linhas revelam

8.3 As duas filosofias de extensão

A segunda é melhor para portabilidade e a primeira é mais cómoda no dia a dia. Se escrever para distribuir, o padrão do Codex é o que menos surpresas dá a quem instalar.

8.4 O orçamento de listagem, comparado

10.1 Onde pôr, conforme quem precisa

10.2 A estrutura que funciona num repositório

skills/                       # fonte única, versionada
├── rever-pr/
│   ├── SKILL.md
│   ├── scripts/
│   └── testes/CASOS.md        # os 10 pedidos do volume I, cap. 8
├── relatorio-mensal/
└── README.md                  # o que existe, quem é dono, como se sincroniza

.claude/skills/  →  gerado    # em .gitignore
.agents/skills/  →  gerado    # em .gitignore
dist/*.zip       →  gerado    # para o claude.ai

Os testes ao lado da skill são o detalhe que a mantém viva: quem a alterar tem por onde verificar que não a partiu, o que transforma «não mexer que isso funciona» em «alterar com confiança».

10.3 As regras de governo

• Cada skill tem um dono nomeado. Sem dono, desactualiza-se em silêncio e passa a dar instruções erradas com ar de autoridade (volume I, cap. 8.4).
• Skills de terceiros entram por revisão, como qualquer dependência, e copiadas para o repositório em vez de puxadas de uma fonte que muda sem aviso.
• Inventário do que está instalado e porquê. É o mesmo requisito de Governança de IA, cap. 6 — e aqui é fácil de cumprir, porque são ficheiros no repositório.
• Um limite deliberado ao número. Cada skill instalada custa contexto permanente e degrada as outras (cap. 8.4). «Quantas skills queremos ter?» é uma pergunta com resposta.
• Revisão periódica. Trimestral chega: o que nunca disparou, o que ficou desactualizado, o que se pode fundir.

10.4 Skills como onboarding

11.1 A escada

11.2 A tabela de sintomas

11.3 A terceira linha é a que engana

11.4 O teste mínimo antes de distribuir

Três verificações, dez minutos, e cobrem a maior parte do que corre mal:

1. Validar com skills-ref validate.
2. Correr numa segunda ferramenta — expõe as suposições de pasta e de campos.
3. Correr com a pasta de skills quase vazia e quase cheia — expõe o problema do orçamento antes de ele aparecer a outra pessoa.

12.1 As sete regras

12.2 Catálogo: a documentação de cada ferramenta

12.3 O que vem a seguir

Os quatro volumes temáticos, cada um com o seu catálogo de skills em ficha padronizada: III — Produto digital (sites, aplicações, software, MCP), IV — Marca e identidade, V — Pensar e VI — Jogos e 3D.

12.4 Leituras a par

• Skills de IA I — Fundamentos — o formato, e como se escreve uma que funcione.
• MCP — a outra metade da extensão de um agente.
• Aceleração de Código com IA — o contexto de trabalho onde a maioria destas ferramentas vive.
• Governança de IA — o inventário do capítulo 10.3.
• Código Legado e Refatoração — porque uma pasta de skills sem dono é código legado a formar-se.