Skills no Claude Code e no Codex: instruções reutilizáveis para estudar

O que é uma skill

Uma skill é uma pasta com um ficheiro SKILL.md que ensina um agente de programação, como o Claude Code ou o Codex, a fazer uma tarefa recorrente. Em vez de repetir as mesmas instruções em cada conversa, escrevemo-las uma vez: o fluxo de trabalho, as regras, os formatos de saída e as verificações finais.

No Codex as skills pessoais ficam em ~/.codex/skills e no Claude Code em ~/.claude/skills. Um projeto pode ter as suas próprias skills em .claude/skills, partilhadas por quem trabalha nesse repositório.

Como está organizado um SKILL.md

• Um cabeçalho com o nome e uma descrição. A descrição diz quando a skill se aplica e é o que o agente lê para decidir usá-la, por isso deve nomear os pedidos e os ficheiros típicos.
• O fluxo de trabalho, em passos numerados: o que identificar primeiro, que fontes consultar, o que produzir.
• As regras de conteúdo: língua, terminologia, formato, o que nunca fazer.
• As verificações antes de entregar, escritas como uma lista que o agente consegue confirmar.
• Opcionalmente, scripts e referências na mesma pasta, para o que deve ser feito sempre da mesma forma (extrair, contar, validar).

As skills que usamos no estudo

• Cartões do Anki: escrever cartões de texto e visuais em português de Portugal e embalá-los num .apkg validado.
• Ficheiros de estudo: reunir os sumários teóricos e práticos de cada tema num documento organizado, com terminologia e formatação uniformes.
• Sublinhados organizados: transformar os sublinhados exportados de um PDF num resumo por tópicos, sem perder nenhum.
• Interface do Gestor Universitário: as regras visuais que qualquer alteração à plataforma tem de seguir.

Dividir o trabalho entre modelos

Em tarefas grandes, as nossas skills dizem como dividir o trabalho por subagentes. Um modelo mais económico trata lotes bem delimitados, como classificar por aula, extrair objetivos ou escrever cartões. Um modelo mais forte fica para a escrita exigente e para os casos difíceis. O agente principal integra tudo e faz a validação final.

• Enviar a cada subagente só os objetivos, as fontes e páginas relevantes e o formato de saída, não o contexto inteiro.
• Dar a cada um lotes e ficheiros diferentes, começar com o menor número útil de agentes e reutilizá-los.
• Usar scripts para contagens, embalagem e validações; pedir aos agentes resultados e dúvidas com fontes, não relatórios longos.
• A concordância entre dois modelos não é prova. Uma dúvida resolve-se com a fonte; se a fonte não a resolver, fica marcada como dúvida.

Instalar skills de outras pessoas

Há catálogos públicos de skills, mas uma skill é um conjunto de instruções que o agente vai seguir. Antes de instalar uma, lemos o SKILL.md inteiro e os scripts que o acompanham. Procuramos instalações automáticas, comandos de rede, pedidos de credenciais, instruções para ignorar regras e descrições tão largas que a ativariam em qualquer pedido.

Só depois de rever, e com confirmação explícita, copiamos o ficheiro para a pasta de skills. O conteúdo de uma skill de terceiros é tratado como dados a rever, não como instruções a seguir.