TAI BUI
Back to curriculum
LearnPython

Skills and Agent SDKs — Anthropic Skills, AGENTS.md, OpenAI Apps SDK

MCP says what tools exist. Skills say how to do a task. The 2026 stack layers both. Anthropic's Agent Skills (open standard, December 2025) ship as SKILL.md with progressive disclosure, OpenAI's Apps SDK is MCP plus widget metadata, and AGENTS.md (now in 60,000+ repos) sits at the repo root as project-level agent context. This lesson names what each covers and builds a minimal SKILL.md and AGENTS.md bundle that travels across agents.

TIME: ~45 minutesPREREQUISITES: Phase 13 · 07 (MCP server)

Learning Objectives

  • Distinguish the three layers: AGENTS.md (project context), SKILL.md (reusable know-how), MCP (tools).
  • Write a SKILL.md with YAML frontmatter and progressive disclosure.
  • Load skills filesystem-style into an agent runtime.
  • Compose a skill with an MCP server and an AGENTS.md so one package works in Claude Code, Cursor, and Codex.

The Problem

Say you distill a release-notes workflow into a multi-step prompt: "Read the latest merged PRs. Group by area. Summarize each. Write a changelog entry following the team's style. Post to Slack draft." You put it in a Notion doc for your team.

Now you want to run that workflow from Claude Code, Cursor, and Codex CLI, and each one loads instructions differently: Claude Code slash-commands, Cursor rules, Codex .codex.md. So you copy the workflow three times and keep three copies in sync by hand.

AGENTS.md and SKILL.md together fix this:

  • AGENTS.md sits at the repo root. Compatible agents read it on session start. "How does this project work? What are the conventions? Which commands run tests?"
  • SKILL.md is a portable bundle: YAML frontmatter (name, description) + markdown body + optional resources. Agents that support skills load them by name on demand.
  • MCP (Phase 13 · 06-14) handles the tools the skill needs to invoke.

Three layers, and the workflow lives in one portable file.

Warm-up0/2
1. What does an MCP server expose to an agent?Warm-up
An agent box on the left joined by two arrows to an MCP server box on the right. Inside the server box is a dashed box with a question mark.
Typed schematic.
2. How does an agent learn which tools an MCP server offers?Warm-up
An agent box and an MCP server box joined by a dashed arrow with a question mark on it, captioned how does it find out which tools exist.
Typed schematic.
Check: The Problem0/1
1. Every new session, an agent asks which command runs the tests, even though a skill called dev-conventions documents it. Which ingredient is missing?Analyze
Three agent sessions each asking which command runs the tests, next to a card for the dev-conventions skill that documents the test command.
Typed schematic; the number of sessions is illustrative.

The Concept

AGENTS.md (agents.md)

Launched late 2025, adopted by 60,000+ repos by April 2026. One file at repo root. Format:

markdown
# Project: my-service
Check: The Concept0/21
1. What is a SKILL.md file?Define
A folder tree: skills with release-notes-writer containing SKILL.md and style-guide.md, and pr-reviewer containing SKILL.md. An arrow from a SKILL.md points to a dashed box asking what kind of file it is.
Folder layout written by the lesson's setup_fixtures().
2. What is AGENTS.md, and when do compatible agents read it?Define
A timeline of one agent session with four points: session starts, user sends first prompt, agent makes first tool call, user invokes a workflow by name. A dashed card for the AGENTS.md file asks when it is read.
Typed schematic. The session events are generic.
3. Which two fields does a SKILL.md's YAML frontmatter declare in the release-notes-writer example?Define
The top of the release-notes-writer SKILL.md between two --- lines. Two frontmatter lines show their values with the field names replaced by key 1 and key 2.
Real fixture text from main.py; the field names are hidden and the long value is shortened.
4. What does "progressive disclosure" mean for a SKILL.md bundle?Define
A folder tree for release-notes-writer with SKILL.md, style-guide.md, template.md and scripts/generate.sh, and a note that SKILL.md refers to style-guide.md. Beside it a model prompt box holds a dashed slot asking about style-guide.md.
Layout and reference from the lesson; typed schematic.
5. What does skill discovery do in an agent runtime?Define
A folder tree with two skills, release-notes-writer and pr-reviewer, each holding a SKILL.md. A dashed arrow labelled discovery points to a dashed box for the agent runtime's skill registry marked with a question mark.
Folder layout written by the lesson's setup_fixtures().
6. What does the Anthropic Claude Agent SDK do?Define
Two package cards, @anthropic-ai/claude-agent-sdk for TypeScript and claude-agent-sdk for Python, with an arrow to a dashed box asking what the SDK does.
Package names from the lesson.
7. What is the OpenAI Apps SDK built directly on top of?Define
A box for the OpenAI Apps SDK, launched October 2025, sitting above a dashed box that asks what it is built directly on.
Typed schematic.
8. What did OpenAI's Apps SDK unify?Define
A dashed box labelled unified with a question mark, an arrow labelled unified into, and a box for the Apps SDK, launched October 2025.
Typed schematic.
9. What does cross-agent portability mean for a skill?Define
A release-notes-writer SKILL.md box on the left and three agent boxes on the right: Claude Code, Cursor and Codex CLI. Dashed arrows join the skill to each agent.
Typed schematic. Agent names are the ones the lesson uses.
10. What is an Agent Skill?Define
A card for the release-notes-writer task with four steps: list PRs, group by label, one line each, stage CHANGELOG.md. A line at the bottom reads Agent Skill with a question mark.
Steps shortened from the lesson's SKILL.md example.
11. Which statement correctly separates the three layers by when each one is loaded?Explain
Three cards: AGENTS.md, SKILL.md and MCP server. Each has a dashed slot asking when it is loaded.
Typed schematic.
12. Which of these is NOT a filesystem location for skill discovery?Explain
An agent runtime box with an arrow to a card showing the path pattern dir slash star slash SKILL.md and an example under it for release-notes-writer.
Typed schematic. The placeholder dir stands for each location.
13. Why does a skill point to style-guide.md instead of pasting the style rules into the SKILL.md body?Explain
The last lines of the release-notes-writer SKILL.md, ending in a line that refers to style-guide.md, above the contents of style-guide.md: three bullet lines of style rules.
Real fixture text from main.py (lines 14 to 16 omitted).
14. In a SKILL.md, how is the work divided between the frontmatter and the body?Explain
The top of the release-notes-writer SKILL.md with its frontmatter fields hidden, next to two dashed boxes asking about the lines between the --- markers and the text after the second ---.
Real fixture text from main.py; fields hidden, long lines shortened.
15. What problem does a tool like SkillKit solve?Explain
A team workflow box, a SkillKit box, and a list of agents: Claude Code, Cursor, Codex, Gemini CLI, OpenCode and others. A dashed arrow with a question mark links SkillKit to the agent list.
Typed schematic. Agent names are from the lesson.
16. How does an Apps SDK app differ from a plain MCP server?Explain
A plain MCP server box and next to it a dashed box asking what an Apps SDK app is.
Typed schematic.
17. You want every agent that opens the repo to know that tests run with `pnpm test` and that TypeScript uses strict mode. Which file holds this?Apply
A card with two facts, tests run with pnpm test and TypeScript uses strict mode, and a dashed arrow to a box asking which file holds them.
Facts from the stem.
18. A skill embeds a very long style reference in its SKILL.md body. Every invocation produces a huge prompt, though most tasks touch only a few rules. Which fix addresses the cause?Analyze
A SKILL.md with a short frontmatter and a very long body holding a style reference, with a few small rules highlighted as the ones the task uses. An arrow leads to a prompt that contains the whole body plus the task.
Typed schematic; the proportions are illustrative, not measured.
19. Your team's release-notes workflow must run in Claude Code, Cursor and Codex, and it posts a draft to Slack. Which design fits the three-layer stack?Design
A release-notes workflow box that lists PRs, groups them and drafts notes, with an arrow to Slack for posting a draft, and dashed arrows to three agents: Claude Code, Cursor and Codex. A line reads design with a question mark.
Typed schematic from the stem.
20. You already run an MCP server that returns sales figures, and you want ChatGPT to show them as an interactive chart. What do you add?Design
An MCP server box that returns sales figures, a dashed arrow labelled add with a question mark, and a ChatGPT window with a dashed area for an interactive chart.
Typed schematic from the stem.
21. Your company runs five coding agents with different native rule formats, and you can only maintain one source file for a triage workflow. Which approach fits?Design
A dashed box for one source file with dashed arrows to five boxes, agent 1 to agent 5, each of which has its own native rule format.
Typed schematic from the stem.

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.

Agents read this on session start and use it to calibrate their behavior for that project. Every coding agent in 2026 supports AGENTS.md: Claude Code, Cursor, Codex, Copilot Workspace, opencode, Windsurf, Zed.

### SKILL.md format

Anthropic's Agent Skills (released as an open standard December 2025):

```markdown
---
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.

Frontmatter declares the skill's identity. The body is the prompt the model sees when the skill loads.

### Progressive disclosure

A skill can reference sub-resources that the agent fetches only when it needs them. For example:

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


SKILL.md says "see style-guide.md for the style rules," and the agent pulls style-guide.md only while the skill is running. That keeps detail the model may not need out of the prompt.

### Filesystem discovery

Agent runtimes scan known directories for SKILL.md files:

- `~/.anthropic/skills/*/SKILL.md`
- Project `./skills/*/SKILL.md`
- `~/.claude/skills/*/SKILL.md`

Loading goes by folder name and frontmatter `name`. Claude Code, the Anthropic Claude Agent SDK, and SkillKit (cross-agent) all follow this pattern.

### Anthropic Claude Agent SDK

`@anthropic-ai/claude-agent-sdk` (TypeScript) and `claude-agent-sdk` (Python) load skills at session start and expose them as callable "agents" inside the runtime. The agent loop dispatches to a skill when the user invokes it.

### OpenAI Apps SDK

Launched October 2025 and built directly on MCP, it unifies OpenAI's earlier Connectors and Custom GPT Actions under a single developer surface. An Apps SDK app is:

- An MCP server (tools, resources, prompts).
- Plus widget metadata for ChatGPT's UI.
- Plus an optional MCP Apps `ui://` resource for interactive surfaces.

The protocol is the same, with a richer UI on top.

### Cross-agent portability via SkillKit

Tools like SkillKit and similar cross-agent distribution layers translate a single SKILL.md into the native format of each of 32+ AI agents (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, and others). You keep one source of truth and many agents consume it.

### The three-layer stack

| Layer | File | Loaded when | Purpose |
|-------|------|-------------|---------|
| AGENTS.md | repo root | session start | project-level conventions |
| SKILL.md | skills directory | skill invoked | reusable workflow |
| MCP server | external process | tools needed | callable actions |

The layers compose. The agent reads AGENTS.md on session start, the user invokes a skill, the skill's instructions include MCP tool calls, and the agent dispatches those through an MCP client.

Use It

code/main.py ships a stdlib SKILL.md parser and loader. It writes two fixture skills under /tmp/lesson-21-skills/, discovers them, parses the YAML frontmatter plus markdown body, and produces a dict keyed by skill name. It then simulates an agent loop that invokes release-notes-writer by name and prints the system prompt that would go to the model.

What to look at:

  • YAML frontmatter parsed with a minimal stdlib parser (no pyyaml dependency, flat key: value lines only).
  • Skill body stored verbatim; agent prepends it to the system prompt on invocation.
  • Progressive disclosure through a read_subresource function that pulls a referenced file only when the skill body mentions it.
Check: Use It0/7
1. A fixture's frontmatter contains the line `description: Fix: crash on load`. What does parse_frontmatter store for the description key?Apply
A fixture whose frontmatter contains the line description: Fix: crash on load, an arrow to parse_frontmatter, and a dashed question mark for the value stored under the description key.
Fixture typed from the stem; the body is a placeholder.
2. main.py calls agent_run on the pr-reviewer skill with a task. What does the returned system prompt contain?Apply
The pr-reviewer SKILL.md with its frontmatter hidden and its title, Steps heading and three steps shown, next to a folder listing with only SKILL.md and a call agent_run(skill, task) whose system prompt is a question mark.
Real fixture text from main.py; frontmatter hidden and blank lines left out.
3. A folder skills/notes/SKILL.md has valid frontmatter containing only a description line. What does discover_skills do with it?Apply
A skills folder holding notes/SKILL.md whose frontmatter has only a description line. An arrow leads to discover_skills with a dashed box asking what the registry holds.
Typed from the stem; the description text is a placeholder.
4. What does read_subresource return when the skill body asks for template.md but the fixture only wrote style-guide.md?Apply
A folder listing with SKILL.md and style-guide.md, a note that the skill body asks for template.md, and the call read_subresource(skill, template.md) whose return value is a question mark.
Typed from the stem.
5. A folder named rn contains a SKILL.md whose frontmatter says name: release-notes-writer. In main.py's discover_skills, which lookup finds it?Apply
A folder rn holding a SKILL.md whose frontmatter says name: release-notes-writer, and a lookup on the dict returned by discover_skills with the key left as a question mark.
Typed from the stem; other frontmatter fields hidden.
6. Someone rewrites the last fixture line to "See the house style rules." and the "subresource pulled" output line disappears. What is the cause?Analyze
The last lines of the fixture after the edit, ending in See the house style rules, and the real output of the run: a loading skill line and a progressive disclosure line, with no subresource pulled line.
Real run of main.py with the edited fixture; one blank line omitted.
7. A new skill file has a blank first line before its opening --- marker, and the skill never shows up in discovery output. Why?Analyze
A skill file whose first line is blank, then a --- block with hidden fields, --- and a body. An arrow leads to the discovery output, where the new skill is missing and no error is shown.
Typed from the stem; the frontmatter fields are hidden.

Ship It

This lesson produces outputs/skill-agent-bundle.md. Given a workflow, the skill produces the combined SKILL.md + AGENTS.md + MCP-server-blueprint bundle, portable across agents.

Author's Note

I'd run main.py and read the printed system prompt before anything else. The agent loop never calls a model. It builds the string a runtime would send, so you can see exactly what a skill adds: the skill body, plus style-guide.md appended when the body mentions it.

The progressive-disclosure check is the part worth poking at. Here it is a plain substring test for style-guide in the body, which is crude, but it makes the idea concrete. The sub-resource costs nothing until the skill asks for it. A real runtime lets the model decide when to read the file. Delete the See style-guide.md line from the fixture and the subresource pulled line disappears from the output.

The frontmatter parser splits each line on the first colon, so it handles flat fields like name and description and nothing else. Multi-line values or nested keys would not parse the way a YAML library would. I'd swap in a real parser once skills grow past two fields.

The code also stops short of the other two layers. It never reads an AGENTS.md or talks to an MCP server, and the last lines of the demo only print what the three layers are. Wiring a skill to a real MCP tool call is the next thing I'd build on top of it.

Exercises

  1. Run code/main.py. Add a second fixture skill under /tmp/lesson-21-skills/ and confirm the loader picks it up.

  2. Write an AGENTS.md for this course repo. Include testing commands, style conventions, and the Phase 13 mental model.

  3. Port a multi-step workflow from your team's internal docs into a SKILL.md. Verify it loads in Claude Code.

  4. Translate the skill into Cursor's and Codex's native rule formats by hand. Count the diff between formats. That diff is the translation surface SkillKit automates.

  5. Read the Anthropic Agent Skills blog post. Identify one feature in the Claude Agent SDK that the loader in main.py does not cover. (Hint: agent sub-invocation.)

Key Terms

TermWhat people sayWhat it actually means
SKILL.md"The skill file"YAML frontmatter plus markdown body, loaded by agent runtime
AGENTS.md"Repo-root agent context"Project-level conventions file read on session start
Progressive disclosure"Lazy-load sub-resources"Skill body references files pulled only when needed
Frontmatter"YAML block at top"Metadata (name, description) in --- delimiters
Claude Agent SDK"Anthropic's skill runtime"@anthropic-ai/claude-agent-sdk, loads skills and routes
OpenAI Apps SDK"MCP + widget meta"OpenAI's dev surface built on MCP plus ChatGPT UI hooks
Skill discovery"Filesystem scan"Walk known dirs for SKILL.md, key by name
Cross-agent portability"One skill many agents"Translate one SKILL.md to 32+ agents via SkillKit-style tools
Agent Skill"Portable know-how"Reusable task template outside MCP's tool concept
Apps SDK"MCP plus ChatGPT UI"Connectors and Custom GPTs unified on MCP

Further Reading

Code

Ships With