Agent Skills: o que são, como funcionam e como usar no Claude Code e Codex
Se usas um agente de programação no terminal — Claude Code, Codex ou outro — já reparaste num padrão: o agente sabe muito sobre programação em geral e pouco sobre a forma como a tua equipa trabalha. Repete a mesma pergunta, ignora a convenção interna, esquece o passo de verificação que nunca pode faltar. Uma Agent Skill existe para resolver exactamente isso.
Este guia explica o conceito desde o zero, mostra os comandos reais validados numa infraestrutura em produção, compara instalação global e por projecto, explica como a mesma skill serve o Claude Code e o Codex, aborda o tema sensível das confirmações e permissões, e termina com um tutorial para criares a tua primeira skill. No fim, publicamos o inventário real das skills instaladas na infraestrutura PontoTi.
Todos os comandos foram validados contra as versões efectivamente instaladas. Onde a documentação genérica e o comportamento real divergem, este guia segue o comportamento real.
O que é uma Agent Skill
A definição, sem jargão, e o problema concreto que resolve.
Uma Agent Skill é uma pasta com instruções escritas em Markdown que um agente de IA lê quando a tarefa em mãos corresponde ao que essa pasta descreve. Não é um programa, não é um serviço, não é um modelo. É conhecimento arrumado num formato que o agente sabe encontrar e seguir.
A comparação mais útil é com um manual de procedimento numa equipa. Um colega novo não precisa que lhe expliquem tudo de cada vez que abre um ticket: precisa de saber onde está o procedimento e quando o deve aplicar. A skill é esse procedimento, e a descrição no topo do ficheiro é a etiqueta que diz «usa-me quando o problema for este».
O ganho prático é de consistência. Sem skill, o resultado depende de como formulaste o pedido nesse dia. Com skill, o agente segue o mesmo caminho hoje, amanhã e daqui a três meses — e qualquer pessoa da equipa obtém o mesmo comportamento sem ter de reescrever o mesmo prompt longo.
- Codificar um procedimento que não pode ser esquecido: verificar backup antes de tocar na base de dados, correr o lint antes de declarar trabalho concluído.
- Trazer conhecimento especializado que o modelo não tem de cor: convenções de um framework, particularidades de uma versão, regras internas da empresa.
- Uniformizar resultados entre pessoas diferentes e entre sessões diferentes do mesmo agente.
- Reduzir o tamanho do pedido: em vez de um prompt de trinta linhas, um pedido curto e uma skill que já contém o resto.
O que contém uma skill: SKILL.md, scripts, references e assets
A anatomia de uma pasta de skill e para que serve cada parte.
Uma skill é uma pasta. Dentro dela existe obrigatoriamente um ficheiro chamado SKILL.md. Tudo o resto é opcional e existe apenas quando é útil.
minha-skill/ ├── SKILL.md ← obrigatório: identidade + instruções ├── scripts/ ← opcional: comandos ou programas auxiliares ├── references/ ← opcional: documentação longa, carregada só quando precisa └── assets/ ← opcional: templates, imagens, ficheiros de exemplo
O SKILL.md começa com um bloco de metadados delimitado por três traços — o chamado frontmatter — com dois campos essenciais: name e description. Depois do frontmatter vem o corpo em Markdown, que é o procedimento propriamente dito.
---
name: nginx
description: "Nginx configuration expert for reverse proxy, load balancing, TLS, and performance tuning"
---
# Nginx Configuration and Performance
You are a senior systems engineer specializing in Nginx configuration...A description é a parte mais importante do ficheiro e é frequentemente a pior escrita. É por ela que o agente decide se a skill se aplica ao pedido actual. Uma descrição vaga («ajuda com bases de dados») não é accionável. Uma descrição que diz explicitamente quando usar («usar quando o pedido envolver queries lentas, EXPLAIN, índices ou paginação em MariaDB») é escolhida no momento certo.
| Parte | Obrigatório | Para que serve |
|---|---|---|
| SKILL.md | Sim | Identidade da skill (name, description) e o procedimento em Markdown. |
| scripts/ | Não | Programas auxiliares — Python, shell, Node — que o agente pode executar em vez de reescrever lógica de cada vez. |
| references/ | Não | Documentação extensa dividida por temas. O agente abre apenas o ficheiro relevante, mantendo o contexto pequeno. |
| assets/ | Não | Templates, ficheiros de exemplo, imagens e outros materiais usados na produção do resultado. |
A divisão em references/ não é decorativa: é uma estratégia de contexto. A skill playwright-best-practices instalada nesta infraestrutura tem um SKILL.md curto e dezenas de ficheiros temáticos em subpastas como core/, debugging/ e infrastructure-ci-cd/. O agente lê o índice, decide o que interessa e só depois abre esse ficheiro. Se estivesse tudo num único SKILL.md, cada utilização gastaria contexto com matéria irrelevante.
Skill, MCP, plugin e prompt: quatro coisas diferentes
A confusão mais comum de quem chega agora ao tema.
Estes quatro termos aparecem juntos e são frequentemente tratados como sinónimos. Não são. Resolvem problemas distintos e podem — devem — coexistir.
| Conceito | O que é | Responde à pergunta |
|---|---|---|
| Prompt | Texto que escreves numa conversa. Existe enquanto durar a sessão. | «O que quero agora?» |
| Agent Skill | Pasta com SKILL.md que o agente carrega quando o contexto corresponde. Persiste no disco, reutilizável, versionável em Git. | «Como se faz isto aqui?» |
| MCP (Model Context Protocol) | Protocolo que liga o agente a ferramentas e fontes de dados externas — GitHub, PostgreSQL, monitorização — através de um servidor. | «A que sistemas consigo aceder?» |
| Plugin | Pacote de distribuição que pode agrupar skills, comandos, hooks e servidores MCP num só instalável. | «Como distribuo tudo isto de uma vez?» |
A diferença entre skill e MCP é a que mais interessa perceber. A skill dá conhecimento e método; o MCP dá acesso. Uma skill que explica como investigar um incidente em PostgreSQL não abre ligação nenhuma à base de dados. Um servidor MCP que expõe PostgreSQL em modo leitura dá acesso, mas não diz ao agente qual é o procedimento de investigação da tua equipa. Juntos funcionam bem; isolados resolvem metade do problema.
A diferença entre skill e prompt é de permanência e de alcance. Um prompt excelente que só existe no histórico de uma pessoa não é conhecimento da equipa. Passar esse prompt a SKILL.md, colocá-lo num repositório e instalá-lo transforma-o em algo revisível, versionável e partilhável.
Na infraestrutura PontoTi os plugins são visíveis na prática: o Codex carrega skills que não estão em nenhum directório de skills, mas dentro de plugins instalados. É por isso que o inventário final deste guia distingue skills instaladas de skills fornecidas por plugin.
Como o agente descobre e usa uma skill
O mecanismo real, verificado com uma ferramenta de diagnóstico.
O agente não lê todas as skills no arranque — isso encheria o contexto. O que faz é ler um índice: para cada skill encontrada, o nome, a descrição e o caminho do ficheiro. Só quando a tarefa corresponde a uma descrição é que abre o SKILL.md completo.
- ArranqueO agente percorre os directórios de skills que conhece e recolhe o frontmatter de cada SKILL.md encontrado.
- ÍndiceConstrói uma lista compacta de nome, descrição e caminho. É esta lista, e não o conteúdo integral, que fica visível ao modelo.
- CorrespondênciaAo receber um pedido, o modelo compara a intenção com as descrições disponíveis.
- CarregamentoSe houver correspondência, abre o SKILL.md e, se necessário, os ficheiros de references/ indicados.
- ExecuçãoSegue o procedimento. Cada acção continua sujeita ao sistema de permissões da CLI.
Isto não é teoria. O Codex tem um comando de diagnóstico que mostra exactamente o que fica visível ao modelo, incluindo a tabela de directórios onde procurou:
codex debug prompt-input### Skill roots
- `r0` = `/home/pontoti/.codex/skills`
- `r1` = `/home/pontoti/.agents/skills`
- `r2` = `/home/pontoti/.codex/skills/.system`
- `r3` = `/home/pontoti/.codex/plugins/cache/n8n-io/n8n-skills/1.1.0/skills`
### Available skills
- nginx: Nginx configuration expert for reverse proxy... (file: r1/nginx/SKILL.md)
- security-audit: Security audit of a codebase... (file: r1/security-audit/SKILL.md)Como encontrar a skill certa
Procurar pela tecnologia ou pelo problema, não ao acaso.
O erro habitual é abrir um directório de skills e navegar à espera de encontrar algo interessante. O método que funciona é o inverso: parte do problema concreto, traduz o problema para a tecnologia envolvida e procura por esse termo.
problema real
│
▼
tecnologia envolvida
│
▼
npx skills find <termo>
│
▼
analisar resultados → ver origem → ler SKILL.md
│
▼
avaliar segurança
│
▼
instalarNa versão 1.5.22 da CLI, o comando find aceita um termo directamente e devolve uma lista com o identificador de instalação, o número de instalações e o endereço da página da skill. Sem termo, entra em modo interactivo.
npx skills find php
npx skills find symfony
npx skills find prestashop
npx skills find mariadb
npx skills find postgresql
npx skills find docker
npx skills find nginx
npx skills find cloudflare
npx skills find security
npx skills find playwright
npx skills find linux
npx skills find systemd
npx skills find devopsInstall with npx skills add <owner/repo@skill>
jeffsenso/prestashop-skills@prestashop-module-development 123 installs
└ https://skills.sh/jeffsenso/prestashop-skills/prestashop-module-development
prestashop/skills@prestashop-restore 14 installs
└ https://skills.sh/prestashop/skills/prestashop-restore
prestashop/skills@prestashop-update 13 installs
└ https://skills.sh/prestashop/skills/prestashop-updateHá ainda uma opção útil quando já sabes de quem queres skills: restringir a pesquisa a um dono de repositório no GitHub.
npx skills find react --owner vercel| Necessidade | Pesquisa sugerida |
|---|---|
| Frontend e interface | react, nextjs, web-design, frontend |
| E-commerce PrestaShop | prestashop, php, symfony |
| Bases de dados | mariadb, mysql, postgresql |
| Contentores | docker, compose |
| Servidor Linux | linux, systemd, nginx |
| Cloud e edge | cloudflare, workers, wrangler |
| Segurança | security, hardening, audit |
| Testes web | playwright, testing |
| DevOps e entrega | devops, deployment, ci-cd |
Como escolher uma skill de confiança
O que verificar antes de instalar código de terceiros no teu ambiente.
Uma skill é conteúdo executável por procuração: influencia o que um agente com acesso ao teu sistema vai fazer. Instalar uma skill de origem desconhecida não é equivalente a ler um artigo — é mais próximo de adicionar uma dependência ao projecto.
- Verificar a origemPrefere repositórios do próprio fabricante da tecnologia. Nesta infraestrutura, as skills de Cloudflare vêm de cloudflare/skills, as de PrestaShop de prestashop/skills, as de MariaDB de mariadb/skills. Origem oficial não é garantia absoluta, mas é o primeiro filtro.
- Ler o SKILL.md antes de instalarA CLI permite ver o que existe num repositório sem instalar nada, e a página em skills.sh mostra o conteúdo. Lê o procedimento inteiro; se não perceberes o que faz, não instales.
- Inspeccionar a pasta scripts/É aqui que mora o risco real. Uma skill que só tem Markdown influencia comportamento; uma skill com scripts pode executar código. Abre cada script e confirma o que faz.
- Desconfiar de pedidos de segredosNenhuma skill legítima precisa que lhe entregues chaves, tokens ou o conteúdo de um ficheiro .env. Uma instrução nesse sentido é motivo suficiente para rejeitar.
- Instalar primeiro no projectoSe tiveres dúvidas, instala no âmbito de um projecto isolado e observa. Só promove a global depois de a skill provar que é útil e previsível.
Existe também um sinal quantitativo: o número de instalações apresentado pelo find. É informação útil, não é uma auditoria. Uma skill com muitas instalações é mais provável de ter sido lida por outras pessoas; continua a merecer a tua leitura.
Como instalar
A sintaxe real da CLI 1.5.22, sem flags inventadas.
Antes de copiar qualquer comando deste ou de outro guia, confirma a ajuda da versão que tens instalada. A CLI evolui e as opções mudam entre versões.
npx skills --version
npx skills --helpA forma mais simples de instalar é indicar o repositório. A CLI apresenta as skills disponíveis e pergunta o que queres instalar e para que agentes.
npx skills add cloudflare/skillsPara automatizar, existem quatro opções que interessam conhecer. A opção -s (ou --skill) escolhe skills específicas; -a (ou --agent) escolhe os agentes de destino; -g (ou --global) instala ao nível do utilizador em vez do projecto; -y (ou --yes) dispensa as perguntas de confirmação.
npx skills add cloudflare/skills \
--skill wrangler \
--global \
--agent claude-code \
--agent codex \
--yesA CLI também aceita a forma abreviada owner/repo@skill que o comando find apresenta nos resultados, e permite listar o que um repositório contém antes de decidir.
npx skills add prestashop/skills --list| Opção | Forma curta | Efeito |
|---|---|---|
| --global | -g | Instala ao nível do utilizador em vez do projecto actual. |
| --agent <agentes> | -a | Agentes de destino. Aceita * para todos os agentes detectados. |
| --skill <nomes> | -s | Skills específicas a instalar. Aceita * para todas. |
| --list | -l | Lista as skills do repositório sem instalar nada. |
| --yes | -y | Salta as perguntas de confirmação da instalação. |
| --copy | — | Copia os ficheiros em vez de criar symlinks para os directórios dos agentes. |
| --all | — | Atalho equivalente a --skill '*' --agent '*' -y. |
| --full-depth | — | Procura em todas as subpastas mesmo quando já existe um SKILL.md na raiz. |
Instalar globalmente ou apenas num projecto?
A decisão que mais afecta a qualidade do dia-a-dia.
A regra é simples de enunciar e fácil de esquecer: instala globalmente aquilo que é verdade em qualquer projecto; instala no projecto aquilo que só é verdade naquele projecto.
Uma skill global sobre Docker ou Linux é útil em todo o lado. Uma skill que descreve a arquitectura de uma aplicação específica, se for global, passa a aparecer como candidata em projectos onde não faz qualquer sentido — e o agente pode segui-la no sítio errado.
npx skills add bagelhole/devops-security-agent-skills \
--skill linux-hardening \
--global \
--agent claude-code \
--agent codex \
--yescd /caminho/do/projeto
npx skills add owner/repo --skill nome-da-skill --agent claude-code --yesSem -g, a CLI instala no âmbito do projecto: cria o directório .agents/skills dentro da pasta actual, os directórios equivalentes dos agentes que não usam esse caminho, e um ficheiro de bloqueio que permite reconstituir o conjunto noutra máquina.
npx skills experimental_install| Critério | Global | Projecto |
|---|---|---|
| Onde vive | ~/.agents/skills e directórios dos agentes no teu utilizador | .agents/skills dentro do repositório |
| Quem beneficia | Todos os teus projectos, imediatamente | Só quem trabalha naquele repositório |
| Versionável em Git | Não (fica na tua máquina) | Sim, e viaja com o projecto |
| Vantagem | Instalas uma vez e esqueces; menos manutenção | Contexto certo no sítio certo; a equipa recebe o mesmo conjunto |
| Inconveniente | Cresce sem controlo; skills irrelevantes competem por atenção | Repetição entre projectos; é preciso instalar em cada um |
| Risco de conflito | Maior: duas skills globais podem descrever procedimentos contraditórios | Menor: o âmbito limita a colisão |
| Bom para | Docker, Linux, PHP, PostgreSQL, Playwright, segurança, boas práticas | Arquitectura interna, convenções da aplicação, skills experimentais |
Recomendação prática: começa restritivo. Instala no projecto, observa durante algumas semanas, e só promove a global aquilo que provou ser transversal. O caminho inverso — limpar um conjunto global inchado — dá muito mais trabalho.
Usar a mesma skill no Claude Code e no Codex
O que significa skill universal e como funciona nesta infraestrutura.
Sim, a mesma skill serve os dois agentes. O formato SKILL.md é comum, e a CLI trata a instalação para vários destinos numa só operação através da opção --agent, repetível.
npx skills add owner/repo \
--skill nome-da-skill \
--global \
--agent claude-code \
--agent codex \
--yesO que acontece a seguir depende do agente, e este é o ponto que quase nenhuma documentação explica bem. A CLI mantém um único directório canónico — ~/.agents/skills no âmbito global — onde os ficheiros vivem uma única vez. A partir daí há dois comportamentos distintos.
Agentes universais são os que lêem directamente o directório .agents/skills. O Codex é um deles: não recebe cópia nem symlink, lê a fonte. Agentes não universais têm um directório próprio, e para esses a CLI cria um symlink — um atalho ao nível do sistema de ficheiros que aponta para a pasta original sem duplicar conteúdo. O Claude Code está neste segundo grupo.
~/.agents/skills/
(fonte única · 31 pacotes)
│
┌───────────────┴───────────────┐
│ │
symlink por skill leitura directa
│ │
▼ ▼
~/.claude/skills/ Codex CLI 0.147.0
(29 symlinks + 1 pasta) (root r1 = ~/.agents/skills)
│ │
▼ ▼
Claude Code ~/.codex/skills/
(8 skills próprias · root r0)ls -la ~/.claude/skills/
lrwxrwxrwx nginx -> ../../.agents/skills/nginx
lrwxrwxrwx security-audit -> ../../.agents/skills/security-audit
lrwxrwxrwx wrangler -> ../../.agents/skills/wranglerA consequência prática é boa: uma actualização da skill no directório canónico chega imediatamente aos dois agentes, porque não existem cópias a divergir. É também por isso que a opção --copy deve ser usada apenas quando há uma razão concreta — em sistemas de ficheiros que não suportam symlinks, por exemplo. Copiar reintroduz o problema das versões divergentes.
O Codex acrescenta ainda um directório próprio, ~/.codex/skills, que a CLI não gere. É lá que vivem as skills criadas localmente com as ferramentas do próprio Codex. Os dois directórios coexistem sem conflito: o Codex lê ambos.
Como ver o que está instalado
Confirmar nome, origem, agente, caminho e âmbito.
Uma instalação só está concluída quando é possível confirmá-la. O comando list — abreviado ls — mostra o que existe. Por omissão lista o âmbito do projecto; com -g, o âmbito global.
npx skills ls # skills do projecto actual
npx skills ls -g # skills globais
npx skills ls -a codex # filtrar por agente
npx skills ls --json # saída legível por máquina, sem coresA saída em JSON é a mais útil para verificação séria, porque devolve para cada skill o nome, o caminho real, o âmbito, os agentes onde está instalada e a origem de onde veio.
{
"name": "prestashop-update",
"path": "/home/pontoti/.agents/skills/prestashop-update",
"scope": "global",
"agents": ["Claude Code", "Codex", "Gemini CLI", "GitHub Copilot"],
"source": "prestashop/skills",
"sourceUrl": "https://github.com/prestashop/skills.git",
"sourceType": "github"
}| Verificação | Onde | Como |
|---|---|---|
| Nome | campo name | npx skills ls -g --json |
| Origem | campos source e sourceUrl | npx skills ls -g --json |
| Agente | campo agents | npx skills ls -g --json ou npx skills ls -a codex |
| Caminho | campo path | npx skills ls -g --json |
| Symlink | sistema de ficheiros | ls -la ~/.claude/skills/ |
| Global ou projecto | campo scope | npx skills ls (projecto) vs npx skills ls -g (global) |
Vale a pena cruzar duas fontes. A CLI diz o que instalou; o agente diz o que efectivamente carrega. No Claude Code, as skills disponíveis aparecem na sessão; no Codex, o comando codex debug prompt-input mostra o índice completo. Foi este cruzamento que revelou, nesta auditoria, uma skill listada uma vez pela CLI mas carregada duas vezes pelo Codex, a partir de raízes diferentes. A listagem sozinha não mostrava o problema; o índice do agente mostrava.
Actualizar e remover
Manutenção do conjunto instalado.
Skills envelhecem. Uma skill escrita para uma versão anterior de um framework pode passar a recomendar padrões descontinuados, e o agente segue-a sem hesitar. Rever o conjunto instalado é manutenção, não zelo excessivo.
npx skills update # todas
npx skills update nginx # apenas uma
npx skills update -g # apenas as globais
npx skills update -p # apenas as do projectonpx skills remove # selecção interactiva
npx skills remove web-design # por nome
npx skills remove --global nginx # do âmbito globalA remoção aceita as mesmas opções de âmbito e agente da instalação: -g para global, -a para agentes específicos, -s para skills específicas e -y para dispensar confirmação. Depois de remover, confirma sempre com uma listagem — é o passo que a maioria salta.
Como abrir o Claude Code
Tutorial de terminal para quem começa hoje.
Primeiro, confirma o que está instalado. As opções mudam entre versões e um guia desactualizado é pior do que nenhum.
claude --version
claude --helpDepois, entra na pasta do projecto e arranca. O agente usa a pasta actual como contexto de trabalho, por isso o cd não é um detalhe.
cd /caminho/do/projeto
claude| Opção | Para que serve |
|---|---|
| -p, --print | Executa o pedido, imprime a resposta e sai. É o modo não interactivo, útil em scripts e pipes. |
| -c, --continue | Continua a conversa mais recente na pasta actual. |
| -r, --resume | Retoma uma conversa por identificador, ou abre um selector. |
| --model <modelo> | Escolhe o modelo da sessão. |
| --add-dir <pastas> | Dá acesso a pastas adicionais além da pasta actual. |
| --permission-mode <modo> | Define o modo de permissões da sessão. |
| --allowedTools / --disallowedTools | Lista de ferramentas permitidas ou negadas. |
| --output-format <formato> | text, json ou stream-json. Só funciona com --print. |
| --safe-mode | Arranca com skills, plugins, hooks, MCP e restantes personalizações desactivadas. Serve para diagnosticar uma configuração partida. |
| --disable-slash-commands | Desactiva todas as skills. |
| doctor | Subcomando que verifica a saúde da instalação. |
Como abrir o Codex
O mesmo exercício, com a CLI da OpenAI.
codex --version
codex --helpcd /caminho/do/projeto
codex| Opção | Para que serve |
|---|---|
| -s, --sandbox <modo> | Política de sandbox: read-only, workspace-write ou danger-full-access. |
| -a, --ask-for-approval <política> | Quando pedir aprovação humana: untrusted, on-request ou never. |
| -m, --model <modelo> | Modelo a utilizar. |
| -C, --cd <pasta> | Define a pasta de trabalho do agente. |
| --add-dir <pasta> | Pastas adicionais com permissão de escrita. |
| -c, --config <chave=valor> | Sobrepõe um valor de configuração para esta execução. |
| -p, --profile <nome> | Aplica um perfil de configuração por cima da configuração base. |
| --search | Activa pesquisa web em tempo real. |
| -i, --image <ficheiro> | Anexa imagens ao pedido inicial. |
| Subcomando | Para que serve |
|---|---|
| codex exec | Execução não interactiva, para automação. |
| codex review | Revisão de código não interactiva. |
| codex doctor | Diagnóstico da instalação, configuração, autenticação e estado. |
| codex sandbox | Executa comandos dentro da sandbox do Codex. |
| codex debug prompt-input | Mostra em JSON o que fica visível ao modelo, incluindo o índice de skills. |
| codex mcp | Gere servidores MCP externos. |
| codex plugin | Gere plugins do Codex. |
| codex resume | Retoma uma sessão anterior. |
Como reduzir as confirmações no terminal
Duas coisas diferentes que são frequentemente confundidas.
Há dois tipos de confirmação em jogo, com origens e consequências completamente distintas. Confundi-los leva a decisões perigosas.
O primeiro é a confirmação da instalação de skills. A opção -y do comando npx skills dispensa as perguntas do instalador. O risco é baixo e circunscrito: estás a dizer «sim, instala isto» sem que te perguntem outra vez. Continua a ser boa prática ler o SKILL.md antes.
npx skills add owner/repo --skill nome --global --agent claude-code --yesO segundo é o sistema de permissões do próprio agente — o que decide se um comando é executado no teu sistema. Nada tem que ver com o instalador de skills, e é aqui que as decisões têm consequências reais.
| Opção | Efeito |
|---|---|
| --permission-mode <modo> | Modo da sessão: manual, acceptEdits, auto, dontAsk, plan ou bypassPermissions. |
| --allowedTools <ferramentas> | Permite explicitamente um conjunto de ferramentas, por exemplo "Bash(git *)" ou Edit. |
| --disallowedTools <ferramentas> | Nega explicitamente um conjunto de ferramentas. |
| --tools <ferramentas> | Restringe o conjunto de ferramentas disponíveis a partir das existentes. |
| --add-dir <pastas> | Alarga o acesso a pastas concretas, em vez de alargar tudo. |
| -p, --print | Modo não interactivo. Não há ninguém para responder às perguntas — as permissões têm de estar definidas antes. |
| --allow-dangerously-skip-permissions | Torna possível activar o bypass total, sem o activar por omissão. |
| --dangerously-skip-permissions | Ignora todas as verificações de permissão. Recomendado apenas em sandbox sem acesso à Internet. |
| Opção | Efeito |
|---|---|
| -s read-only | O agente lê, mas não escreve. |
| -s workspace-write | Escrita limitada ao espaço de trabalho. |
| -s danger-full-access | Sem restrições de sandbox. |
| -a untrusted | Só executa comandos considerados de confiança sem perguntar; escala para o utilizador nos restantes. |
| -a on-request | O modelo decide quando pedir aprovação. |
| -a never | Nunca pede aprovação; as falhas de execução são devolvidas ao modelo. |
| --approve-for-me | Encaminha os pedidos de aprovação para revisão automática usando a sandbox workspace-write. |
| --dangerously-bypass-approvals-and-sandbox | Salta todas as confirmações e executa sem sandbox. Destinado apenas a ambientes já isolados por fora. |
| --add-dir <pasta> | Acrescenta pastas com permissão de escrita, sem abrir o sistema inteiro. |
Quatro níveis de autonomia, e o que está em jogo em cada um
Remover confirmações aumenta o risco. Vale a pena saber quanto.
Não existe um nível correcto para toda a gente. Existe um nível adequado a cada combinação de ambiente, tarefa e capacidade de recuperação. O erro é escolher o nível pela impaciência em vez de o escolher pelo risco.
| Nível | Postura | Quando usar |
|---|---|---|
| 1 — Seguro | Confirmações normais. O agente propõe, tu aprovas. | Produção, primeira utilização de uma skill, qualquer sistema com dados reais. |
| 2 — Desenvolvimento | Mais autonomia dentro do projecto: escrita no espaço de trabalho, leitura alargada, aprovação para o resto. | Trabalho normal num repositório com Git, onde qualquer erro se reverte com um comando. |
| 3 — Automação controlada | Execução sem intervenção, mas dentro de limites explícitos: sandbox activa, pastas declaradas, ferramentas em lista de permissões. | Tarefas repetitivas e bem definidas, CI, geração de relatórios. |
| 4 — Acesso total | Sem sandbox e sem aprovações. Todo o poder do teu utilizador. | Apenas em ambiente descartável e isolado por fora — contentor sem rede, máquina virtual efémera. Nunca numa máquina com acesso a produção. |
Independentemente do nível escolhido, há uma categoria de operações que merece aprovação humana explícita — porque são difíceis ou impossíveis de reverter:
| Categoria | Exemplos | Porque é crítico |
|---|---|---|
| Ficheiros | rm, rm -rf, truncate | Perda de dados sem rede de segurança. |
| Base de dados | DROP DATABASE, DROP TABLE, DELETE sem WHERE, migrations | Destrói dados de produção; o restauro depende de um backup que pode não existir. |
| Contentores | docker volume rm, docker system prune | Apaga volumes persistentes e dados que ninguém julgava estarem ali. |
| Serviços | systemctl stop, disable, alterações a units | Interrompe serviço; efeitos que só aparecem no próximo arranque. |
| Rede e proxy | alterações a Nginx, regras de firewall, Cloudflare | Pode cortar o acesso à própria máquina onde estás a trabalhar. |
| Entrega | deploy, publicação, alterações em produção | Impacto imediato e visível para clientes. |
| Segredos | leitura, escrita ou cópia de .env, tokens, chaves | Uma exposição não se desfaz; obriga a rotação de credenciais. |
A regra que usamos internamente: automatiza o que é reversível, aprova o que não é. Um commit reverte-se; uma tabela apagada sem backup, não.
Como criar a tua própria Agent Skill
Do procedimento que já existe na cabeça de alguém para um ficheiro.
A melhor primeira skill não é ambiciosa: é um procedimento que já repetes e que já explicaste a alguém pelo menos duas vezes. Se tiveste de explicar duas vezes, vale a pena escrever.
A CLI tem um comando para criar o esqueleto, e é a forma mais rápida de começar com a estrutura correcta.
npx skills init minha-skill- Escolhe um âmbito estreitoUma skill que faz uma coisa bem vale mais do que uma que tenta cobrir uma área inteira. Âmbito largo produz descrições vagas, e descrições vagas nunca são escolhidas.
- Escreve a descrição primeiroDiz o que a skill faz e, sobretudo, quando deve ser usada. Inclui as palavras que aparecerão nos pedidos reais. É por aqui que o agente decide.
- Escreve o procedimento em passosNumera. Um passo por acção. Indica o que verificar entre passos e o que fazer quando a verificação falha — é aí que os procedimentos reais se distinguem dos que só descrevem o caminho feliz.
- Separa o que é longoSe ultrapassares algumas centenas de linhas, move o detalhe para references/ e deixa no SKILL.md o índice e o essencial.
- Testa com um pedido realAbre uma sessão, faz um pedido nas palavras que usarias normalmente e confirma que a skill é escolhida. Se não for, o problema está quase sempre na descrição.
- VersionaColoca a skill num repositório Git. Passa a ser revisível em pull request, como qualquer outro código que a equipa mantém.
Exemplo completo: pontoti-prestashop-safety
Transformar um procedimento de segurança operacional numa skill.
Vale a pena ver o processo do princípio ao fim com um caso concreto. O procedimento: antes de qualquer alteração potencialmente destrutiva numa loja PrestaShop, há nove passos que ninguém pode saltar. Hoje isto vive na cabeça de quem opera. Vamos escrevê-lo.
1. identificar ambiente → produção ou desenvolvimento? 2. verificar Git → árvore limpa? branch correcta? 3. verificar backup → existe, é recente, é restaurável? 4. verificar base de dados → ligação, tamanho, tabelas afectadas 5. analisar contentores → estado, volumes, dependências 6. criar rollback → como se desfaz isto? 7. executar alteração → só agora 8. testar → a loja responde? o resultado é o esperado? 9. reportar → o que mudou, evidência, o que falta
A tradução para skill é directa. A descrição indica quando aplicar; o corpo indica o que fazer e, em cada passo, o que fazer quando a verificação falha.
---
name: pontoti-prestashop-safety
description: Verificações obrigatórias antes de alterações potencialmente
destrutivas numa loja PrestaShop. Usar quando o pedido envolver migrations,
alterações de esquema, remoção de dados, reconstrução de contentores,
reindexação, alterações de categorias ou qualquer operação sem rollback óbvio.
---
# PrestaShop — verificações antes de alterar
Aplicar por ordem. Não avançar com uma verificação por confirmar.
Parar e reportar sempre que um passo falhar.
## 1. Identificar o ambiente
Confirmar se o alvo é produção ou desenvolvimento antes de tudo o resto.
Em caso de dúvida, assumir produção.
## 2. Verificar o estado do Git
Confirmar que a árvore de trabalho está limpa e a branch é a esperada.
Alterações por commitar tornam o rollback ambíguo — parar e reportar.
## 3. Verificar o backup
Confirmar que existe backup recente e que é restaurável.
Um backup que nunca foi testado não conta como backup.
Sem backup válido: parar. Não avançar sem decisão humana explícita.
## 4. Verificar a base de dados
Confirmar a ligação e identificar as tabelas afectadas.
Registar contagens antes da alteração, para comparação posterior.
## 5. Analisar os contentores
Confirmar o estado dos serviços e que volumes estão montados.
Identificar o que depende do serviço a alterar.
## 6. Criar o plano de rollback
Escrever, antes de executar, como se desfaz a alteração.
Se não for possível descrever o rollback, a alteração não está pronta.
## 7. Executar a alteração
Um passo de cada vez. Guardar stdout e stderr em logs com timestamp.
Nunca registar segredos nem valores de ficheiros .env.
## 8. Testar
Confirmar que a loja responde e que o resultado corresponde ao esperado.
Comparar com as contagens registadas no passo 4.
## 9. Reportar
Indicar o que mudou, com que evidência, o que ficou por fazer e como
reverter. Sem evidência produzida pelos comandos, a tarefa não está
concluída.Repara em três decisões deliberadas. A descrição enumera situações concretas — migrations, alterações de esquema, remoção de dados — em vez de dizer «ajuda com PrestaShop»; é isso que faz a skill ser escolhida no momento certo. Cada passo diz o que fazer quando falha, não apenas quando corre bem. E o passo 9 exige evidência, o que impede o agente de declarar concluído aquilo que não verificou.
Skills utilizadas na infraestrutura PontoTi
Inventário real, obtido por auditoria em 15 de Agosto de 2026.
Esta secção não é ilustrativa. Foi produzida a partir da leitura directa dos directórios, da saída de npx skills ls -g --json e do índice que o Codex efectivamente carrega.
| Métrica | Valor | Fonte |
|---|---|---|
| Pacotes no store partilhado ~/.agents/skills | 31 | listagem do sistema de ficheiros |
| Entradas em ~/.claude/skills | 30 (29 symlinks + 1 pasta real) | ls -la |
| Skills próprias em ~/.codex/skills | 8 (mais 6 internas em .system, das quais 5 carregadas) | listagem + codex debug prompt-input |
| Skills geridas pela CLI, total | 39 | npx skills ls -g --json |
| Skills fornecidas por plugins do Codex | 33 | n8n-skills 14 · pontoti-core 14 · pontoti-astro 5 |
| Skills visíveis ao Codex, incluindo aninhadas | 115 | codex debug prompt-input |
A diferença entre 39 e 115 explica-se por dois factores já referidos: os pacotes que contêm várias skills em subpastas — prestashop-module-development sozinho contribui com 39 ficheiros SKILL.md — e as skills que chegam por plugin, que a CLI não gere.
| Skill | Origem | Para que serve |
|---|---|---|
| linux-hardening | bagelhole/devops-security-agent-skills | Endurecimento de servidores Linux, SSH, utilizadores e firewall. |
| systemd-services | bagelhole/devops-security-agent-skills | Criação e gestão de serviços e timers systemd. |
| nginx | rightnow-ai/openfang | Reverse proxy, balanceamento, TLS e afinação de desempenho. |
| docker-patterns | affaan-m/ecc | Padrões Docker e Compose, segurança de contentores e orquestração local. |
| security-audit | cloudflare/security-audit-skill | Auditoria de segurança focada em vulnerabilidades exploráveis. |
| security-best-practices | openai/skills | Revisão de boas práticas de segurança por linguagem e framework. |
| Skill | Origem | Para que serve |
|---|---|---|
| postgresql-best-practices | mindrally/skills | Desenho de esquema, optimização e administração em PostgreSQL. |
| postgresql-optimization | github/awesome-copilot | Funcionalidades específicas de PostgreSQL: JSONB, arrays, tipos e extensões. |
| mariadb-features | mariadb/skills | Capacidades de MariaDB que vão além do MySQL padrão. |
| mariadb-query-optimization | mariadb/skills | Índices, EXPLAIN, paginação e afinação do optimizador. |
| mysql-best-practices | mindrally/skills | Boas práticas de esquema, queries e administração em MySQL. |
| Skill | Origem | Para que serve |
|---|---|---|
| prestashop-module-development | jeffsenso/prestashop-skills | Desenvolvimento de módulos PrestaShop. Contém 39 SKILL.md em subpastas. |
| prestashop-update | prestashop/skills | Actualização de uma loja PrestaShop. |
| prestashop-update-check | prestashop/skills | Verificação de compatibilidade antes de actualizar. |
| prestashop-restore | prestashop/skills | Restauro de uma loja a partir de backup. |
| php-best-practices | asyrafhussin/agent-skills | PHP 8.x, normas PSR e princípios SOLID em revisão de código. |
| php-development | mindrally/skills | Desenvolvimento PHP 8+ com padrões modernos. |
| Skill | Origem | Para que serve |
|---|---|---|
| agents-sdk | cloudflare/skills | Agentes com estado em Cloudflare Workers. |
| workers-best-practices | cloudflare/skills | Boas práticas de produção em Cloudflare Workers. |
| wrangler | cloudflare/skills | CLI da Cloudflare para deploy e gestão de recursos. |
| cloudflare-email-service | cloudflare/skills | Envio e encaminhamento de email na Cloudflare. |
| vercel-react-best-practices | vercel-labs/agent-skills | Desempenho em React e Next.js. |
| vercel-composition-patterns | vercel-labs/agent-skills | Padrões de composição de componentes React. |
| vercel-optimize | vercel-labs/agent-skills | Optimização de custo e desempenho em projectos Vercel. |
| web-design-guidelines | vercel-labs/agent-skills | Revisão de interface contra directrizes de web design. |
| playwright-best-practices | currents-dev/playwright-best-practices-skill | Testes Playwright: arquitectura, CI, acessibilidade e depuração. |
| playwright-cli | microsoft/playwright-cli | Automação de browser a partir do terminal. |
| impeccable | instalação local | Revisão e melhoria de interfaces. Instalada em duas variantes de plataforma — ver nota abaixo. |
| Skill | Origem | Para que serve |
|---|---|---|
| learn | agentskill.sh | Procurar, instalar, actualizar e avaliar skills. |
| review-skill | agentskill.sh | Rever e melhorar ficheiros SKILL.md contra boas práticas. |
| find-skills | vercel-labs/skills | Descoberta de skills. Instalada apenas para agentes universais. |
| Skill | Natureza | Para que serve |
|---|---|---|
| pontoti-public-site-quality | PontoTi | Auditoria de grelha, responsividade, acessibilidade, idiomas e metadata do site público. |
| catalog-expert | PontoTi | Trabalho sobre catálogo de produtos, EAN, SKU e dados de fornecedor. |
| security-ownership-map | PontoTi | Mapa de responsabilidade sobre componentes e superfícies expostas. |
| security-threat-model | PontoTi | Modelação de ameaças aplicada aos projectos internos. |
| frontend-app-builder | local | Construção de aplicações frontend. |
| ui-ux-pro-max | local | Trabalho de interface e experiência de utilização. |
| playwright | local | Automação de browser a partir do terminal. |
| screenshot | local | Captura de ecrã para validação visual. |
| Plugin | Skills | Âmbito |
|---|---|---|
| pontoti-core | 14 | Backend, frontend, Next.js, TypeScript, Tailwind, design system, DevOps, segurança, SEO, testes, desempenho, documentação, IA e gestão de produto. |
| pontoti-astro | 5 | Motor astrológico, motor editorial, templates editoriais, numerologia e produção de PDF do Mapa Astral Premium. |
| n8n-skills | 14 | Automação em n8n: agentes, expressões, nós de código, credenciais, depuração e ciclo de vida de workflows. |
A auditoria encontrou dois casos de nomes repetidos em directórios diferentes. Um era um problema real; o outro não era. Vale a pena ver a diferença, porque é o erro de diagnóstico mais fácil de cometer nesta matéria: assumir que nome repetido significa duplicação a eliminar.
A lição é operacional: antes de remover uma cópia, compara o conteúdo integralmente e verifica se a diferença é versão ou plataforma. Diferença de versão resolve-se consolidando; diferença de plataforma resolve-se mantendo ambas e documentando porquê.
Categorias representadas: infraestrutura e sistemas, bases de dados, e-commerce e PHP, web e cloud, testes automatizados, segurança, automação e meta-skills sobre a própria gestão de skills. A distribuição reflecte a operação real — servidores Linux, PostgreSQL, PrestaShop, Cloudflare, Next.js — e não uma lista de conveniência.
Perguntas frequentes
Respostas curtas às dúvidas que aparecem sempre.
Uma skill é o mesmo que um prompt?
Não. Um prompt existe durante uma conversa. Uma skill é um ficheiro no disco, reutilizável, versionável em Git e partilhável com a equipa. O agente carrega-a sozinho quando o contexto corresponde.
Uma skill é o mesmo que MCP?
Não. A skill dá conhecimento e método; o MCP dá acesso a ferramentas e fontes de dados externas. São complementares: o MCP liga o agente à base de dados, a skill diz-lhe qual é o procedimento correcto para lá mexer.
Uma skill é o mesmo que um plugin?
Não. Um plugin é um pacote de distribuição que pode incluir skills, comandos, hooks e servidores MCP. Nesta infraestrutura, 33 das skills visíveis ao Codex chegam através de plugins.
O Claude Code e o Codex podem usar a mesma skill?
Sim. O formato SKILL.md é comum e a instalação faz-se numa só operação com --agent claude-code --agent codex.
O que significa uma skill universal?
É uma skill instalada para um agente que lê directamente o directório partilhado .agents/skills, sem precisar de cópia nem de symlink. O Codex funciona assim; o Claude Code recebe um symlink para o mesmo conteúdo.
O que é um symlink?
É um atalho ao nível do sistema de ficheiros: uma entrada que aponta para outra pasta em vez de duplicar o conteúdo. Permite que a mesma skill apareça em vários directórios de agentes sem existir mais do que uma vez em disco.
Instalar uma skill dá mais permissões ao agente?
Não. A skill influencia o comportamento; as permissões continuam a ser decididas pela configuração da CLI e pelo modo de aprovação escolhido.
Como confirmo que uma skill ficou mesmo instalada?
Com npx skills ls -g --json, que devolve nome, caminho, âmbito, agentes e origem. Para confirmar do lado do agente, ls -la no directório de skills ou, no Codex, codex debug prompt-input.
Quantas skills são demasiadas?
Não há número mágico, mas há um sintoma: quando o agente começa a escolher a skill errada, o problema é normalmente de descrições sobrepostas, não de quantidade. Nessa altura, revê descrições e remove o que não usas.
Posso escrever a skill em português?
Sim. O idioma não afecta o funcionamento. A convenção PontoTi é procedimento em português europeu, comandos e termos técnicos em inglês.
Validação técnica
As versões contra as quais este guia foi verificado.
Nenhum comando deste guia foi copiado de documentação genérica. Todos foram confirmados contra as versões instaladas na infraestrutura PontoTi, através da ajuda de cada CLI e da execução dos comandos de leitura.
| Ferramenta | Versão | Comando de verificação |
|---|---|---|
| Claude Code | 2.1.233 | claude --version |
| Codex CLI | 0.147.0 | codex --version |
| skills CLI | 1.5.22 | npx skills --version |
| Node.js | 24.16.0 | node --version |
| npm | 11.17.0 | npm --version |