Phase 13 - Lesson 22

Skills y 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.

MCP dice "qué herramientas existen". Skills dice "cómo hacer una tarea". La pila de 2026 superpone ambos. Las Agent Skills de Anthropic (estándar abierto, diciembre de 2025) se distribuyen como SKILL.md con divulgación progresiva. El Apps SDK de OpenAI es MCP más metadatos de widget. AGENTS.md (ahora en más de 60,000 repositorios) se encuentra en la raíz del repositorio como contexto de agente a nivel de proyecto. Esta lección nombra lo que cubre cada uno y construye un paquete minimalista SKILL.md + AGENTS.md que viaja a través de los agentes.

Tipo: Learn Lenguajes: Python (stdlib, parser y cargador de SKILL.md) Prerrequisitos: Fase 13 · 07 (servidor MCP) Tiempo: ~45 minutos

Objetivos de Aprendizaje

• Distinguir las tres capas: AGENTS.md (contexto del proyecto), SKILL.md (conocimiento reutilizable), MCP (herramientas).
• Escribir un SKILL.md con frontmatter YAML y divulgación progresiva.
• Cargar skills al estilo de sistema de archivos en un runtime de agente.
• Componer una skill con un servidor MCP y un AGENTS.md para que un solo paquete funcione en Claude Code, Cursor y Codex.

El Problema

Un ingeniero destila un flujo de trabajo de escritura de notas de lanzamiento (release notes) en un prompt de varios pasos: "Lee los PRs fusionados más recientes. Agrupa por área. Resume cada uno. Escribe una entrada de changelog siguiendo el estilo del equipo. Publica en el borrador de Slack". Lo ponen en un documento de Notion para su equipo.

Ahora quieren usar este flujo de trabajo desde Claude Code, Cursor y Codex CLI. Cada agente tiene una forma diferente de cargar instrucciones: comandos de barra inclinada de Claude Code, reglas de Cursor, .codex.md de Codex. El ingeniero copia el flujo de trabajo tres veces y mantiene tres copias.

AGENTS.md y SKILL.md juntos solucionan esto:

• AGENTS.md se encuentra en la raíz del repositorio. Cada agente compatible lo lee al inicio de la sesión. "¿Cómo funciona este proyecto? ¿Cuáles son las convenciones? ¿Qué comandos ejecutan las pruebas?"
• SKILL.md es un paquete portátil: frontmatter YAML (nombre, descripción) + cuerpo en markdown + recursos opcionales. Los agentes que admiten habilidades las cargan por nombre bajo demanda.
• MCP (Fase 13 · 06-14) maneja las herramientas que la habilidad necesita invocar.

Tres capas, un artefacto portátil.

El Concepto

AGENTS.md (agents.md)

Lanzado a finales de 2025, adoptado por más de 60,000 repositorios para abril de 2026. Un solo archivo en la raíz del repositorio. 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.

Los agentes leen esto al inicio de la sesión y lo usan para calibrar su comportamiento para ese proyecto. Todos los agentes de codificación en 2026 admiten AGENTS.md: Claude Code, Cursor, Codex, Copilot Workspace, opencode, Windsurf, Zed.

Formato SKILL.md

Las Agent Skills de Anthropic (lanzadas como un estándar abierto en diciembre 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.

El frontmatter declara la identidad de la skill. El cuerpo es el prompt que se muestra al modelo cuando se carga la skill.

Divulación progresiva

Las habilidades pueden hacer referencia a subrecursos que el agente obtiene solo cuando es necesario. Ejemplo:

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

SKILL.md dice "consulte style-guide.md para las reglas de estilo". El agente obtiene style-guide.md solo cuando la habilidad se está ejecutando activamente. Esto evita saturar el prompt con detalles que el modelo puede no necesitar.

Descubrimiento en el sistema de archivos

Los runtimes de los agentes escanean directorios conocidos en busca de archivos SKILL.md:

• ~/.anthropic/skills/*/SKILL.md
• ./skills/*/SKILL.md del proyecto
• ~/.claude/skills/*/SKILL.md

La carga se realiza por el nombre de la carpeta y el campo name del frontmatter. Claude Code, Anthropic Claude Agent SDK y SkillKit (cross-agent) siguen este patrón.

Anthropic Claude Agent SDK

El @anthropic-ai/claude-agent-sdk (TypeScript) y claude-agent-sdk (Python) cargan habilidades al inicio de la sesión, exponiéndolas como "agentes" invocables dentro del runtime. El bucle del agente despacha a una habilidad cuando el usuario la invoca.

OpenAI Apps SDK

Lanzado en octubre de 2025; construido directamente sobre MCP. Unifica los Connectors anteriores de OpenAI y las Custom GPT Actions bajo una sola superficie de desarrollo. Una aplicación del Apps SDK es:

• Un servidor MCP (herramientas, recursos, prompts).
• Más metadatos de widgets para la interfaz de usuario de ChatGPT.
• Más un recurso opcional de MCP Apps ui:// para superficies interactivas.

Mismo protocolo, experiencia de usuario más rica.

Portabilidad cross-agent a través de SkillKit

Herramientas como SkillKit y capas de distribución cross-agent similares traducen un solo SKILL.md al formato nativo de cada uno de más de 32 agentes de IA (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, etc.). Una sola fuente de verdad; muchos consumidores.

La pila de tres capas

Todos los tres se componen: el agente lee AGENTS.md al inicio de la sesión, el usuario invoca una habilidad, las instrucciones de la habilidad incluyen llamadas a herramientas MCP, y el agente despacha a través de un cliente MCP.

Use It

code/main.py incluye un parser y cargador de SKILL.md usando la biblioteca estándar (stdlib). Descubre habilidades bajo ./skills/, analiza el frontmatter YAML más el cuerpo en markdown, y produce un diccionario indexado por el nombre de la habilidad. Luego simula un bucle de agente que invoca release-notes-writer por nombre.

Qué observar:

• El frontmatter YAML se analiza con un parser minimalista de la stdlib (sin dependencia de pyyaml).
• El cuerpo de la habilidad se almacena textualmente (verbatim); el agente lo antepone al prompt del sistema en la invocación.
• La divulgación progresiva se demuestra mediante una función read_subresource que obtiene los archivos referenciados bajo demanda.

Ship It

Esta lección produce outputs/skill-agent-bundle.md. Dado un flujo de trabajo, la habilidad produce el paquete combinado SKILL.md + AGENTS.md + modelo de servidor MCP, portátil entre agentes.

Ejercicios

1. Ejecuta code/main.py. Agrega una segunda habilidad bajo skills/ y confirma que el cargador la detecte.
2. Escribe un AGENTS.md para el repositorio de este curso. Incluye comandos de prueba, convenciones de estilo y el modelo mental de la Fase 13.
3. Transfiere un flujo de trabajo de varios pasos de los documentos internos de tu equipo a un SKILL.md. Verifica que se cargue en Claude Code.
4. Traduce la habilidad a los formatos de reglas nativos de Cursor y Codex a mano. Calcula la diferencia entre formatos; esta es la superficie de traducción que SkillKit automatiza.
5. Lee la publicación del blog de Anthropic Agent Skills. Identifica una característica en el Claude Agent SDK que el cargador de esta lección no cubre. (Pista: subinvocación de agentes.)

Términos Clave

Lectura Adicional

• Anthropic — Anuncio de Agent Skills — Lanzamiento en diciembre de 2025
• Anthropic — Documentación de Agent Skills — Referencia del formato SKILL.md
• OpenAI — Apps SDK — Plataforma de desarrollo basada en MCP para ChatGPT
• agents.md — Formato y lista de adopción de AGENTS.md
• Anthropic — GitHub anthropics/skills — Ejemplos oficiales de habilidades