Phase 13 - Lesson 22

Skills e SDKs de Agentes — Anthropic Skills, AGENTS.md, OpenAI Apps SDK

This lesson includes a graded coding exercise that runs in your browser, unlocked with lifetime access.

O MCP diz "quais ferramentas existem". As Skills dizem "como fazer uma tarefa". A pilha de 2026 sobrepõe ambos. As Agent Skills da Anthropic (padrão aberto, dezembro de 2025) são distribuídas como SKILL.md com divulgação progressiva. O Apps SDK da OpenAI é o MCP mais metadados de widget. O AGENTS.md (agora em mais de 60.000 repositórios) fica na raiz do repositório como contexto do agente em nível de projeto. Esta lição nomeia o que cada um cobre e constrói um pacote minimalista SKILL.md + AGENTS.md que viaja entre agentes.

Tipo: Learn Linguagens: Python (stdlib, leitor e analisador de SKILL.md) Prerrequisitos: Fase 13 · 07 (servidor MCP) Tempo: ~45 minutos

Objetivos de Aprendizagem

• Distinguir as três camadas: AGENTS.md (contexto do projeto), SKILL.md (conhecimento reutilizável), MCP (ferramentas).
• Escrever um SKILL.md com frontmatter YAML e divulgação progressiva.
• Carregar skills no estilo sistema de arquivos em um runtime de agente.
• Compor uma skill com um servidor MCP e um AGENTS.md para que um único pacote funcione no Claude Code, Cursor e Codex.

O Problema

Um engenheiro destila um fluxo de trabalho de escrita de notas de lançamento (release notes) em um prompt de várias etapas: "Leia os PRs mesclados mais recentes. Agrupe por área. Resuma cada um. Escreva uma entrada de changelog seguindo o estilo da equipe. Publique no rascunho do Slack." Eles o colocam em um documento do Notion para a equipe.

Agora eles querem usar esse fluxo de trabalho no Claude Code, Cursor e Codex CLI. Cada agente tem uma maneira diferente de carregar instruções: comandos de barra do Claude Code, regras do Cursor, .codex.md do Codex. O engenheiro copia o fluxo de trabalho três vezes e mantém três cópias.

O AGENTS.md e o SKILL.md juntos resolvem isso:

• AGENTS.md fica na raiz do repositório. Todo agente compatível o lê no início da sessão. "Como este projeto funciona? Quais são as convenções? Quais comandos executam os testes?"
• SKILL.md é um pacote portátil: frontmatter YAML (nome, descrição) + corpo em markdown + recursos opcionais. Agentes que suportam skills as carregam pelo nome sob demanda.
• MCP (Fase 13 · 06-14) lida com as ferramentas que a skill precisa invocar.

Três camadas, um artefato portátil.

O Conceito

AGENTS.md (agents.md)

Lançado no final de 2025, adotado por mais de 60.000 repositórios até abril de 2026. Um único arquivo na raiz do repositório. Formato:

# Project: my-service

## Conventions
- TypeScript with strict mode.
- Use Pydantic for models on the Python side.
- Tests run with `pnpm test`.

## Build and run
- `pnpm dev` for local dev server.
- `pnpm build` for production bundle.

Os agentes leem isso no início da sessão e o usam para calibrar seu comportamento para aquele projeto. Todos os agentes de codificação em 2026 suportam AGENTS.md: Claude Code, Cursor, Codex, Copilot Workspace, opencode, Windsurf, Zed.

Formato SKILL.md

As Agent Skills da Anthropic (lançadas como um padrão aberto em dezembro de 2025):

---
name: release-notes-writer
description: Write a changelog entry for the latest merged PRs following this project's style.
---

# Release notes writer

When invoked, run these steps:

1. List PRs merged since the last tag. Use `gh pr list --base main --state merged`.
2. Group by label: feature, fix, chore, docs.
3. For each PR in each group, write one line: `- <title> (#<num>)`.
4. Draft the release notes and stage them in CHANGELOG.md.

If the user says "ship", run `git tag vX.Y.Z` and `gh release create`.

## Notes

- Never include commits without a PR.
- Skip "chore" entries from the public changelog.

O frontmatter declara a identidade da skill. O corpo é o prompt exibido ao modelo quando a skill é carregada.

Divulgação progressiva

As skills podem referenciar sub-recursos que o agente busca apenas quando necessário. Exemplo:

skills/
  release-notes-writer/
    SKILL.md
    style-guide.md
    template.md
    scripts/
      generate.sh

O SKILL.md diz "consulte style-guide.md para as regras de estilo". O agente busca o style-guide.md apenas quando a skill está sendo executada ativamente. Isso evita inflar o prompt com detalhes que o modelo pode não precisar.

Descoberta no sistema de arquivos

Os runtimes dos agentes varrem diretórios conhecidos em busca de arquivos SKILL.md:

• ~/.anthropic/skills/*/SKILL.md
• ./skills/*/SKILL.md do projeto
• ~/.claude/skills/*/SKILL.md

O carregamento é feito pelo nome da pasta e pelo campo name do frontmatter. Claude Code, Anthropic Claude Agent SDK e SkillKit (cross-agent) seguem esse padrão.

Anthropic Claude Agent SDK

O @anthropic-ai/claude-agent-sdk (TypeScript) e o claude-agent-sdk (Python) carregam skills no início da sessão, expondo-as como "agentes" chamáveis dentro do runtime. O loop do agente despacha para uma skill quando o usuário a invoca.

OpenAI Apps SDK

Lançado em outubro de 2025; construído diretamente sobre o MCP. Unifica os Connectors anteriores da OpenAI e as Custom GPT Actions sob uma única superfície de desenvolvimento. Um aplicativo do Apps SDK é:

• Um servidor MCP (ferramentas, recursos, prompts).
• Mais metadados de widget para a interface do ChatGPT.
• Mais um recurso opcional do MCP Apps ui:// para superfícies interativas.

Mesmo protocolo, experiência mais rica.

Portabilidade cross-agent via SkillKit

Ferramentas como o SkillKit e camadas de distribuição cross-agent semelhantes traduzem um único SKILL.md para o formato nativo de cada um de mais de 32 agentes de IA (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, etc.). Uma fonte da verdade; muitos consumidores.

A pilha de três camadas

Todos os três se compõem: o agente lê o AGENTS.md no início da sessão, o usuário invoca uma skill, as instruções da skill incluem chamadas de ferramentas MCP, e o agente despacha por meio de um cliente MCP.

Use It

code/main.py fornece um analisador (parser) e carregador de SKILL.md usando apenas a biblioteca padrão (stdlib). Ele descobre skills em ./skills/, analisa o frontmatter YAML mais o corpo em markdown, e produz um dicionário indexado pelo nome da skill. Em seguida, ele simula um loop de agente que invoca release-notes-writer pelo nome.

O que observar:

• O frontmatter YAML é analisado com um analisador minimalista da stdlib (sem dependência do pyyaml).
• O corpo da skill é armazenado textualmente (verbatim); o agente o prefixa no prompt do sistema na invocação.
• A divulgação progressiva é demonstrada por meio de uma função read_subresource que busca arquivos referenciados sob demanda.

Ship It

Esta lição produz outputs/skill-agent-bundle.md. Dado um fluxo de trabalho, a skill produz o pacote combinado SKILL.md + AGENTS.md + modelo de servidor MCP, portátil entre agentes.

Exercícios

1. Execute o code/main.py. Adicione uma segunda skill em skills/ e confirme se o carregador a detecta.
2. Escreva um AGENTS.md para o repositório deste curso. Inclua comandos de teste, convenções de estilo e o modelo mental da Fase 13.
3. Porte um fluxo de trabalho de várias etapas dos documentos internos da sua equipe para um SKILL.md. Verifique se ele carrega no Claude Code.
4. Traduza a skill manualmente para os formatos de regras nativos do Cursor e do Codex. Calcule a diferença entre os formatos — essa é a superfície de tradução que o SkillKit automatiza.
5. Leia a postagem do blog Anthropic Agent Skills. Identifique um recurso no Claude Agent SDK que o carregador desta lição não cobre. (Dica: sub-invocação de agentes.)

Termos-Chave

Leitura Adicional

• Anthropic — Anúncio de Agent Skills — Lançamento em dezembro de 2025
• Anthropic — Documentação de Agent Skills — Referência do formato SKILL.md
• OpenAI — Apps SDK — Plataforma de desenvolvimento baseada em MCP para ChatGPT
• agents.md — Formato e lista de adoção do AGENTS.md
• Anthropic — GitHub anthropics/skills — Exemplos oficiais de skills