# Codex Skills para iniciantes: como automatizar fluxos de trabalho de agentes de IA > Guia prático para criar e usar Skills no Codex: anatomia do SKILL.md, ativação explícita e automática, diferenças entre skills, scripts e tools, Skills API e configuração de limites de segurança. ## 1. O que é um Codex Skill: a transição de prompts únicos para cenários reutilizáveis Durante o desenvolvimento regular com **Codex**, engenheiros frequentemente repetem o mesmo conjunto de instruções iniciais: quais arquivos verificar, sob quais critérios realizar a auditoria, quais regras de arquitetura seguir e em qual formato retornar o resultado. Quando esses requisitos precisam ser digitados novamente a cada sessão, isso reduz a produtividade e leva a erros aleatórios. **Codex Skill (Habilidade)** — é um fluxo de trabalho salvo e reutilizável para um tipo específico de tarefa. Criar uma habilidade não envolve fine-tuning do modelo: os pesos da inteligência artificial permanecem inalterados. Em vez disso, o agente recebe um protocolo procedural claro, que ele carrega dinamicamente na sua janela de contexto exatamente quando surge a tarefa correspondente. ```mermaid flowchart LR subgraph AdHoc ["Традиційний підхід (Ручний промптинг)"] User1["Користувач"] -->|Щоразу вводить довгі правила| Prompt["Великий разовий промпт"] Prompt --> Agent1["Codex"] end subgraph Modular ["Підхід на основі Skills"] User2["Користувач"] -->|Короткий запит: $code-review| Agent2["Codex"] SkillsDir["Репозиторій Skills (SKILL.md)"] -->|Автоматичне підвантаження інструкцій| Agent2 Agent2 --> Output["Стандартизований результат"] end ``` > [!NOTE] > No ecossistema oficial da OpenAI, as habilidades já são utilizadas como padrão de automação. Por exemplo, para migrar bases de código para novos modelos, a OpenAI fornece uma Skill pronta `openai-docs`, que conhece todas as nuances do SDK atual sem a necessidade de carregar manualmente a documentação. --- ## 2. Critérios de seleção: quando é necessário um Skill versus quando um prompt comum basta Um Skill é destinado principalmente a processos que possuem alta repetibilidade, sequências de ações estáveis ou requisitos rigorosos quanto ao formato dos dados de saída. | Critério | Prompt Comum | Codex Skill | | :--- | :--- | :--- | | **Frequência de uso** | Tarefa única e pontual | Cenário recorrente (diário ou antes de cada release) | | **Complexidade do processo** | 1–2 passos simples | Pipeline multi-etapa regulamentado com validação | | **Arquivos adicionais** | Não necessários | Requer scripts auxiliares, referências ou checklists | | **Requisitos de formato** | Resposta livre | Estrutura rígida de relatório (por exemplo, JSON ou tabela fixa) | | **Permissões e restrições** | Configurações atuais da sessão | Ações permitidas e proibidas claramente definidas | ### Cenários típicos para criação de habilidades - **Verificação pré-release do repositório:** Execução de linters, busca por código de debug residual (`console.log`, `TODO`), verificação de compatibilidade de tipos. - **Code review padronizado:** Verificação de conformidade com regras internas de arquitetura da equipe, sem realizar alterações autônomas. - **Geração de notas de release:** Extração da lista de PRs mesclados, categorização e atualização do `CHANGELOG.md`. - **Migração de componentes:** Refatoração passo a passo de padrões obsoletos seguindo um template previamente aprovado. > [!TIP] > **Regra prática do engenheiro:** Se você se pegar explicando pela terceira vez ao Codex a mesma sequência de passos («primeiro leia este arquivo, depois execute este teste, não altere nada, exiba em formato de tabela») — esse fluxo de trabalho merece ser empacotado em um Skill separado. --- ## 3. Mecânica de ativação: chamada explícita via $name versus seleção automática O Codex suporta duas formas complementares de ativar habilidades na sessão: chamada direta determinística pelo usuário e reconhecimento semântico automático. ### Chamada Explícita (Explicit Invocation) O usuário indica diretamente o nome da habilidade desejada através do prefixo de dólar `$`: ```bash $code-review перевір останні зміни у гілці feature/auth ``` Este método garante 100% de previsibilidade: o Codex ativa imediatamente a Skill especificada, adota suas instruções como base de comportamento e as aplica aos argumentos da sua solicitação. ### Ativação Automática (Semantic Auto-Match) Se o prefixo `$name` não for especificado, o Codex analisa a solicitação do usuário e a compara com os campos `description` de todas as habilidades conectadas: ```mermaid flowchart TD Req["Запит: 'Підготуй релізні нотатки для v2.1.0'"] --> Router{"Аналіз семантичного збігу"} Router -->|Match: description release-notes| LoadSkill["Підвантаження .codex/skills/release-notes/SKILL.md"] Router -->|No Match| Standard["Звичайний діалог без підвантаження навичок"] LoadSkill --> Exec["Виконання регламентованого сценарію"] ``` ```text Descrição bem-sucedida (alta probabilidade de ativação precisa): description: Verifica os arquivos alterados do projeto em busca de regressões, erros de tipagem e problemas de estilo antes do lançamento. Use durante a auditoria de PRs. Descrição mal-sucedida (limites vagos): description: Ajuda o desenvolvedor a escrever melhor o código. ``` --- ## 4. Anatomia da habilidade e estrutura do SKILL.md: metadados, regras e recursos Uma Skill mínima consiste em apenas um arquivo — `SKILL.md`. Habilidades mais maduras podem conter scripts de automação anexados, guias de referência e templates. ```text project-review/ ├── SKILL.md # Arquivo principal (metadados + instruções) ├── scripts/ └── check-deps.sh # Script executável para verificações rápidas ├── references/ └── styleguide.md # Referência: guia de estilo de código da equipe └── templates/ └── report-template.md # Modelo do relatório final ``` ### Estrutura do arquivo `SKILL.md` O arquivo é dividido em duas partes funcionais: um bloco YAML Frontmatter no início e instruções em formato Markdown. ```markdown --- name: project-review description: Realizar uma auditoria abrangente do código antes do lançamento, verificando tipos e gerando um relatório de erros sem aplicar alterações. --- Instruções para a auditoria: 1. Executar "npm run typecheck" para identificar erros de TypeScript. 2. Analisar o git diff em relação à branch main. 3. Agrupar as observações encontradas por categorias: Critical, Warning, Suggestion. 4. Não modificar automaticamente nada no código-fonte original. 5. Fornecer um relatório resumido conforme templates/report-template.md. ``` > [!IMPORTANT] > **Princípio da concisão:** Não sobrecarregue o `SKILL.md` com longas explicações filosóficas. Quanto mais curto e claro o texto, menos espaço útil ele ocupa na janela de contexto do modelo e mais rigorosamente o agente segue o regulamento. --- ## 5. Áreas de armazenamento: habilidades de projeto versus globais pessoais O Codex divide as habilidades em dois escopos de visibilidade dependendo de seu propósito: ```mermaid flowchart TD subgraph GlobalScope ["Глобальні навички (~/.codex/skills/)"] G1["Особистий стиль комітів"] G2["Швидкий генератор ліцензій"] end subgraph ProjectScope ["Проєктні навички (.codex/skills/)"] P1["Архітектурний лінтер проєкту"] P2["Генератор DTO та міграцій БД"] P3["Чек-лист релізу сервісу"] end Dev["Розробник"] -->|Власні уподобання| GlobalScope Team["Команда в Git"] -->|Спільні стандарти| ProjectScope ``` ### Habilidades de Projeto (`.codex/skills/` ou `.agents/skills/`) Armazenadas na raiz do repositório do projeto e versionadas no Git. - **Propósito:** Padronizar processos para toda a equipe de desenvolvedores. - **Vantagem:** Qualquer engenheiro (ou runner de CI/CD) que clona o repositório obtém imediatamente o mesmo conjunto de habilidades agênticas. ### Habilidades Pessoais (`~/.codex/skills/`) Localizadas no diretório home do usuário atual do sistema operacional. - **Propósito:** Ferramentas individuais específicas para um determinado desenvolvedor (por exemplo, assistente pessoal para formatar anotações de desenvolvimento). - **Vantagem:** Disponíveis em qualquer terminal, independentemente do projeto ativo. --- ## 6. Workshop prático: criando uma habilidade de verificação de código usando $skill-creator A maneira mais simples e rápida de criar uma nova habilidade é utilizar a meta-ferramenta do sistema `$skill-creator`, embutida no Codex. ### Passo 1. Inicialização do wizard de criação Na interface de diálogo do Codex, invocamos o comando: ```bash $skill-creator ``` Em seguida, descrevemos o fluxo de trabalho desejado em linguagem natural: ```text Crie para mim uma skill de projeto chamada "pr-validator". Objetivo: verificar os arquivos alterados no pull request atual. Regras: 1. Execute npm run lint e npm test. 2. Verifique se foram adicionados testes unitários para novos módulos. 3. Proíba o agente de corrigir autonomamente as falhas encontradas. 4. Apresente o resultado em formato de tabela com as colunas: Arquivo, Linha, Problema, Nível de Risco. ``` ### Passo 2. Verificação do artefato gerado O wizard criará o diretório `.codex/skills/pr-validator/` e gerará o arquivo `SKILL.md`: ```markdown --- name: pr-validator description: Validates pull request changes by running lint and test suites, checking test coverage for new modules, and returning an issue table without modifying code. --- Execution Steps: 1. Identify modified files using git diff against the target branch. 2. Execute "npm run lint" and capture any linter warnings or errors. 3. Execute "npm test" to ensure regression safety. 4. Verify whether newly created source files in src/ have corresponding test files in tests/. 5. Strict constraint: Do NOT modify any project files under any circumstances. 6. Present the audit findings in a markdown table: | File | Line | Issue | Severity | ``` ### Passo 3. Testando a habilidade criada em uma sessão real Abra uma nova sessão no Codex e teste o funcionamento da habilidade criada: ```bash $pr-validator перевір мою поточну гілку перед відкриттям PR ``` Certifique-se de que o agente executou o linter, não tentou editar os arquivos de origem e retornou uma tabela com os resultados. --- ## 7. Tríade de capacidades do agente: Habilidade (Skill), Script e Ferramenta (Tool) Iniciantes frequentemente confundem os conceitos de habilidade, script e ferramenta (Tool / MCP). Eles se complementam, mas resolvem problemas de engenharia fundamentalmente diferentes. ```mermaid flowchart TD subgraph Triad ["Тріада архітектури автономного агента"] Skill["SKILL (Навичка)
'Мозок і регламент'
Пояснює послідовність, контекст та логіку"] Script["SCRIPT (Скрипт)
'Точний алгоритм'
Виконує детерміновану операцію на диску"] Tool["TOOL (Інструмент / MCP)
'Органи чуття та руки'
Надає доступ до API, терміналу, баз даних"] end Skill -->|Керує викликом| Script Skill -->|Використовує| Tool Script -->|Викликається через| Tool ``` ### Matriz comparativa da tríade | Componente | Papel no Sistema | Como é Executado | Exemplo | | :--- | :--- | :--- | :--- | | **Skill (Habilidade)** | **Regulamento e Raciocínio** | Lido e interpretado pelo modelo | Instrução sobre como conduzir uma auditoria de segurança | | **Script** | **Ação Computacional Determinística** | Executado no SO via terminal | Script Bash para parsing de tags git | | **Tool (Ferramenta)** | **Interface de Acesso ao Ambiente** | Invocada via mecanismo Tool Calling | Servidor MCP para conexão à API do GitHub | > [!NOTE] > A Habilidade explica ao agente **o que** e **em que ordem** fazer. O Script executa rapidamente e com garantia operações matemáticas ou de arquivos. A Ferramenta concede permissões de interação com o mundo externo. --- ## 8. Gerenciamento programático via Skills API e versionamento Além do trabalho local com arquivos, a OpenAI fornece uma **Skills API** especializada para gerenciamento programático de habilidades em aplicações cloud e sistemas backend. ```bash # Створення нової навички через HTTP API curl https://api.openai.com/v1/skills \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "schema-migrator", "description": "Автоматична валідація та створення міграцій бази даних", "instructions": "Перевір схему Prisma, переконайся у відсутності drop column..." }' ``` ### Por que o versionamento de Skills é necessário 1. **Imutabilidade do ambiente de produção:** Cada atualização de habilidade cria uma nova versão (`v1`, `v2`). Pipelines de produção vinculam-se a uma versão específica congelada, impossibilitando falhas inesperadas devido a mudanças acidentais. 2. **Rollback seguro:** Se a descrição atualizada causou regressão ou piora na qualidade da geração de código, a equipe pode reverter instantaneamente para o número de versão anterior. 3. **Testes A/B de instruções:** Possibilidade de comparar simultaneamente o desempenho de duas edições alternativas da habilidade em tarefas reais. --- ## 9. Segurança, limites de autonomia e regras de confirmação de ações Uma Skill influencia diretamente quais operações o agente executa no seu sistema. Portanto, no corpo da habilidade, deve haver uma separação clara entre ações autônomas e controladas. ```mermaid flowchart LR Action["Дія агента"] --> Decision{"Тип операції"} Decision -->|Безпечна: Read-Only| Auto["Автономне виконання без пауз
(Читання коду, запуск лінтера)"] Decision -->|Критична: Write / Network| Confirm["Запит підтвердження в інженера
(Видалення файлів, деплой)"] ``` ### Matriz de níveis de confiança :::tabs @tab Permitido sem confirmação - Leitura de arquivos de código-fonte e documentação. - Análise de logs de build e erros no terminal. - Execução de testes unitários isolados em modo somente leitura. - Geração de relatórios analíticos e tabelas. @tab Requer confirmação obrigatória - Modificação de arquivos de configuração global (`package.json`, `.env`). - Exclusão ou sobrescrita de arquivos no repositório. - Execução de requisições de rede ou envio de dados para APIs externas. - Criação de commits ou push de alterações para o repositório Git remoto. ::: > [!WARNING] > **Não duplique proibições repetidamente:** Evite repetir frases como «não altere nada» em cada item. É suficiente registrar claramente as operações proibidas uma única vez no início da seção de restrições; caso contrário, o agente tornará excessivamente passivo e começará a pedir confirmação até mesmo antes de ler um arquivo comum. --- ## 10. Resumo final e checklist para criar um Skill robusto Guarde este checklist e use-o como referência durante o design de cada nova habilidade. ### Cheat Sheet rápido do engenheiro ```bash # ─── Робота з навичками в Codex ────────────────────────────────── $skill-creator # Запуск вбудованого майстра створення навичок $ <ваше завдання> # Явний детермінований виклик навички /skills # Перегляд списку доступних навичок у сесії # ─── Файлова структура проєкту ─────────────────────────────────── .codex/skills//SKILL.md # Проєктна навичка (для всієї команди) ~/.codex/skills//SKILL.md # Персональна навичка (для поточної машини) ``` ### Checklist de prontidão da habilidade para release - [ ] **Nome claro:** Até 64 caracteres, minúsculas latinas, com hífen (`kebab-case`). - [ ] **Descrição informativa:** O campo `description` contém uma fórmula clara de «o que a habilidade faz» e «quando ela deve ser executada». - [ ] **Corpo conciso:** O texto não ultrapassa o essencial, mantendo eficiência no contexto.