Skills oficialmente introduzidas no Codex

• Agent Skills adicionam ao Codex capacidades especializadas por tarefa em uma estrutura extensível, permitindo executar workflows específicos com confiabilidade
• Cada skill é composta por um arquivo SKILL.md e por scripts, recursos e assets opcionais, podendo ser compartilhada entre equipes ou comunidades
• O Codex executa skills por invocação explícita (comando /skills ou entrada $) e por invocação implícita (uso automático quando a descrição da tarefa corresponde)
• As skills são gerenciadas por meio de vários locais de armazenamento e um sistema de prioridade, como REPO, USER, ADMIN e SYSTEM, e novas skills podem ser criadas com $skill-creator
• Esse recurso está disponível tanto na CLI quanto na extensão de IDE do Codex, e é possível instalar skills do GitHub e de outros lugares para expandir funcionalidades

---

Visão geral de Agent Skills

• Agent Skills são uma estrutura que dá ao Codex novas funcionalidades e especialização
  • As skills empacotam instruções, recursos e scripts opcionais para executar tarefas específicas
  • Elas podem ser compartilhadas entre equipes ou comunidades e são baseadas no open Agent Skills standard
• Disponíveis tanto na CLI quanto na extensão de IDE do Codex

Estrutura e componentes das skills

• Cada skill é estruturada em torno do arquivo SKILL.md, com a seguinte organização de pastas
  • SKILL.md: obrigatório, inclui instruções e metadados
  • scripts/: código executável opcional
  • references/: documentação opcional
  • assets/: templates e recursos opcionais
• O Codex usa a abordagem de progressive disclosure para gerenciar o contexto com eficiência
  • No início, carrega apenas o nome e a descrição da skill, e lê as instruções completas quando necessário

Formas de invocar skills

• Invocação explícita (Explicit invocation)
  • É possível indicar diretamente uma skill com o comando /skills ou com uma entrada $
  • As versões web e iOS do Codex ainda não oferecem suporte à invocação explícita, mas skills incluídas no repositório podem ser usadas via prompt
• Invocação implícita (Implicit invocation)
  • Quando a tarefa do usuário corresponde à descrição de uma skill, o Codex usa essa skill automaticamente

Locais de armazenamento e prioridade das skills

• O Codex carrega skills de vários locais, e skills em locais de maior prioridade sobrescrevem skills de menor prioridade com o mesmo nome
• Principais escopos e locais
  • REPO: $CWD/.codex/skills, $CWD/../.codex/skills, $REPO_ROOT/.codex/skills
  • USER: $CODEX_HOME/skills ou ~/.codex/skills
  • ADMIN: /etc/codex/skills
  • SYSTEM: skills incluídas por padrão no Codex
• Cada escopo é usado conforme objetivos de gerenciamento em nível pessoal, de equipe ou de sistema

Como criar skills

• É possível gerar automaticamente uma nova skill com a skill embutida $skill-creator do Codex
  • Quando combinada com a skill $plan, permite definir um plano antes de criar a skill
• Na criação manual, basta criar uma pasta em um local válido e escrever o arquivo SKILL.md
  • Campos obrigatórios: name, description
  • Campo opcional: metadata.short-description
• As skills seguem a Agent Skills specification

Instalação de skills e exemplos

• É possível instalar skills do repositório público de skills no GitHub usando a skill $skill-installer
  • Exemplo: $skill-installer linear
  • Também é possível instalar skills de outros repositórios
• Exemplos de skills embutidas
  • $plan: criação de planos para desenvolver novos recursos ou resolver problemas complexos
  • $skill-installer linear: acesso ao contexto do Linear
  • $skill-installer notion-spec-to-implementation: acesso a dados do Notion

O que isso significa para desenvolvedores do Codex

• Agent Skills são um componente central para aumentar a extensibilidade e a colaboração no Codex
• Desenvolvedores podem definir suas próprias skills para criar workflows de desenvolvimento automatizados
• A integração com CLI e IDE, a integração com o GitHub e uma especificação padronizada de skills ampliam o potencial de expansão do ecossistema do Codex

[GN⁺]

Comentários no Hacker News

• É muito bom ver Skills se consolidando como padrão
  Dá para escrever só com arquivos Markdown e, por padrão, é eficiente em contexto
  Como pode ser encaixado em cima de ferramentas já existentes, dá até para criar uma skill explicando como usar o CLI gh em vez do GitHub MCP
  Também dá para combinar várias skills e incluir scripts em Python ou JS
  Isso permite uma abordagem muito mais simples e flexível, sem precisar expor um servidor MCP separado

  • Além disso, o próprio agente pode editar, melhorar e adicionar skills
    Por exemplo, dá para automatizar algo como “adicione os pontos principais desta sessão como uma skill”
    Dá para registrar o aprendizado como skill não só em sessões boas, mas também nas que tiveram muita tentativa e erro
    Isso oferece um fluxo de expansão de funcionalidades muito mais rápido e acessível do que MCP
  • Estou pensando em como usar skills em um webapp de porte médio com Django + PostgreSQL + Python
    Fico me perguntando se isso não seria mais útil em data science ou DevOps do que em algo focado em CRUD
  • No fim, entendo skill como algo na linha de cache de casos de uso / receitas de workflow

• O ponto principal de Skills é que, pela especificação, não se aplica RAG ao conteúdo principal do código ou markdown da skill
  Ou seja, só o nome e a descrição no front matter entram no prompt e são usados para selecionar a skill
  Por isso, uma lógica que não seja mencionada na descrição pode simplesmente nunca ser descoberta
  Além disso, a descrição da skill funciona como uma espécie de prompt injection, então também afeta o tom geral e o custo em tokens
  Veja este link de código para um exemplo relacionado

  • Pessoalmente, sinto que um índice de skills pode ser mais um fardo do que uma ajuda
    Como é importante manter o contexto limpo, prefiro adicionar arquivos md diretamente só quando necessário
    MCP é complexo demais, e até skill parece um pouco overengineered
  • Alguns sistemas agentic aplicam RAG a skills
    Isso é menos uma questão do próprio LLM e mais um problema de design do harness agentic
    Parece que, no futuro, LLM e harness vão ficar mais integrados
  • MCP e tools acabam tendo o mesmo problema

• Eu já vinha usando uma abordagem parecida há tempos
  Criava uma pasta para cada funcionalidade, com README.md, scripts e GUIDE.md
  Quando encontrava código reutilizável, como integração com clerk.dev, organizava isso em uma pasta
  e, quando precisava, juntava tudo com merge-to-md para usar
  Essa abordagem sempre funcionou muito bem, então é ótimo ver esse tipo de recurso virando nativo nos agentes

  • Essa explicação ajudou a entender facilmente o conceito de skill

• Acho que, no longo prazo, Skills podem evoluir como uma biblioteca open source
  Se soluções padronizadas como autenticação e multitenancy forem fornecidas como skills,
  a segurança e a qualidade do código devem melhorar bastante

  • Indo além, se o modelo puder buscar e baixar a skill necessária em um índice global de skills
    e usá-la imediatamente, isso pode até virar uma alternativa ao aprendizado contínuo

• Skills, plugins, apps, connectors, MCPs, agents… sinceramente, é confuso

  • Essa confusão acontece por causa da imaturidade da tecnologia e da velocidade das mudanças
    Ainda não existe uma melhor abordagem definida, e a terminologia também não foi consolidada
    Até “Agent” significa coisas diferentes dependendo do grupo
  • Na prática, tudo isso são só mecanismos de conveniência para carregar contexto
    Fora executar ferramentas, são apenas várias formas de adicionar contexto ao prompt
  • Tem gente que chama tudo isso de remendo temporário (bandaid)
  • Outros veem isso apenas como nomes de marketing para API e prompt
  • Também lembra o fenômeno de LLMs gerarem em massa ideias parecidas, mas ligeiramente diferentes

• Recentemente, neste post,
  foi descrita uma estrutura em que o agent chama repetidamente o LLM e troca pedidos de uso de ferramentas em formato JSON,
  e fiquei curioso sobre como uma skill se encaixaria nesse framework

  • Antes do primeiro loop, o harness envia um bloco <Skills> para o LLM
    Ex.: <Skill><Name>postgres</Name><Description>como consultar o DB de pré-produção</Description><File>skills/postgres.md</File></Skill>
    Esse aviso é reenviado periodicamente para que o LLM não “esqueça” a skill
    No fim, só nome + descrição + caminho do arquivo são enviados, então o custo em tokens é baixo
    Mas, se o LLM for inteligente o bastante, talvez consiga funcionar bem sem essa estrutura
  • O agente carrega seletivamente uma ou mais skills quando necessário
    É uma forma padronizada de trazer junto o prompt da skill e os scripts relacionados para uso

• Muita gente está entendendo Skills de forma errada
  O ponto principal não é o arquivo .md, e sim o empacotamento de código e instruções
  Skills partem do pressuposto de um ambiente de execução de código

  • Dá para pré-aprovar código executável e chamá-lo no prompt quando necessário
    A grande vantagem é economizar contexto com indexação de metadados e lazy loading
  • Tem quem descreva isso como um renascimento de literate programming

• Se existisse um marketplace de skills.md, acho que isso ajudaria na adoção da tecnologia

  • Mas, na prática, parece difícil operar algo assim por causa de spam, segurança e falta de rentabilidade
    Basta olhar os casos de spam relacionados a MCP
    No fim, isso provavelmente só se sustentaria em torno de empresas confiáveis ou desenvolvedores conhecidos
  • Já existe o repositório de skills da Anthropic
    Não tem avaliações nem comentários, mas dá para esperar uma boa qualidade
  • Tentativas assim aparecem com frequência, mas como o custo de criar uma skill personalizada é praticamente zero,
    há pouco incentivo para usar o prompt de outra pessoa
  • Eu também usei a documentação da Anthropic como referência para criar uma skill que escreve skills
    No fim, o importante é otimizar para o próprio workflow e codebase

• Fico curioso se, usando a skill gerada, o agente conseguiria organizar a solução final obtida depois de várias tentativas

  • Eu também criei uma “meta skill” para que, ao fim da sessão, ela atualize sozinha as próprias regras
    Estou criando esse efeito flywheel assim

• Houve até uma piada dizendo que a Anthropic parece o Chief Product Officer da OpenAI

  • E em seguida veio a piada complementar: “sem nem ganhar por isso”