Agent Skills and Claude Code

What you’ll learn

Phase 3 continues. Lesson 8 built the loop substrate; lesson 9 catalogued the six canonical patterns. Each pattern lives or dies by the instructions you put in front of each LLM call; until now those instructions have lived in your application code as strings. This lesson is what happens when they become durable artifacts on disk: reusable, shareable, version-controllable, and auto-discovered by an agent harness when relevant. The single capability this lesson builds: explain what Agent Skills are, how Claude Code reads them, and the durable-instructions pattern they enable.

Concretely, you will know what an Agent Skill is (Anthropic verbatim: modular capabilities that extend Claude’s functionality. Each Skill packages instructions, metadata, and optional resources (scripts, templates) that Claude uses automatically when relevant), the contrast with prompts (verbatim: Unlike prompts (conversation-level instructions for one-off tasks), Skills load on-demand and eliminate the need to repeatedly provide the same guidance across multiple conversations), the on-disk shape (a directory with SKILL.md at the root; YAML frontmatter with required name and description; markdown body; optional bundled .md files and scripts/ subdir), the frontmatter constraints (name max 64 chars, lowercase-alphanumeric-hyphens, no XML, not “anthropic”/“claude”; description non-empty, max 1024 chars, no XML, must describe BOTH what and when), the progressive-disclosure architecture (Level 1 metadata always loaded around 100 tokens per Skill in the system prompt; Level 2 SKILL.md body loaded when triggered under 5K tokens via the bash tool; Level 3 bundled resources loaded as needed via further bash calls with effectively unlimited capacity), the three surfaces (Claude API with the /v1/skills upload endpoint or pre-built skill_id in container plus the three beta headers code-execution-2025-08-25 + skills-2025-10-02 + files-api-2025-04-14; Claude Code via the filesystem at ~/.claude/skills/ personal or .claude/skills/ project with auto-discovery; claude.ai via zip upload through Settings > Features), the no-sync-across-surfaces rule, the NOT-ZDR-eligible note for the API surface, Claude Code as the worked agent harness (verbatim: Claude Code is an agentic coding tool that reads your codebase, edits files, runs commands, and integrates with your development tools. Available in your terminal, IDE, desktop app, and browser) with surfaces (terminal CLI, VS Code, JetBrains, desktop, web, iOS), the CLAUDE.md project-context pattern, hooks, sub-agents, the Agent SDK, and how Skills + Claude Code together let any of the L9 patterns become durable, shareable, version-controlled team artifacts (routing as a directory of branch Skills; chaining as a chain of Skills; orchestrator-workers as orchestrator naming worker Skills; autonomous agent as Claude Code reading domain Skills).

Every substantive claim verifies against the public Anthropic Claude documentation at platform.claude.com/docs/en/agents-and-tools/agent-skills/ and the Claude Code documentation at code.claude.com/docs/en/overview.

Where this fits

This is lesson 10 of 12 of Track 22, the third lesson of Phase 3 (agent patterns). Lesson 8 built the loop substrate; lesson 9 catalogued the canonical patterns; this lesson adds the durable-instructions layer plus a worked agent harness that reads it. Lesson 11 (next) covers Subagents and Claude Managed Agents, the Anthropic-managed primitives that let patterns 4 (orchestrator-workers) and 6 (autonomous agent) spawn focused inner loops. Lesson 12 closes the track by shipping any of this to production.

The cross-track companion is Track 20 (AI Agents and Tool Use) for the deeper engineering discipline of harness design and Skill governance over time.

Before you start

Prerequisites: lessons 1-9 of this track. Lesson 8 is load-bearing (Claude Code is an L8-style loop in production). Lesson 9 is load-bearing (Skills + Claude Code make the L9 patterns durable). Lesson 5 supplies the bash tool that the agent uses to read SKILL.md files. Lesson 6 (MCP) shows up because Claude Code integrates MCP servers natively via configuration. Lesson 7 (caching) shows up because CLAUDE.md is the cached project system prompt and progressive disclosure is a complementary context-engineering pattern.

Soft recommended: an Anthropic Console account at https://platform.claude.com/ and an API key (lesson 1). For the try-it-yourself: optionally install Claude Code (curl -fsSL https://claude.ai/install.sh | bash on macOS / Linux / WSL; Homebrew, WinGet, or apt/dnf/apk available too) so you can create a Skill on disk and watch it auto-discover. If you do not have Claude Code, you can still author a Skill and upload it through claude.ai Settings > Features.

About the math

None. This lesson is taxonomic and architectural: the on-disk format, the load-order architecture (progressive disclosure), the three surfaces, and the Claude Code surface map. The token costs surfaced (around 100 tokens per Skill at Level 1; under 5K at Level 2; effectively unlimited at Level 3) are descriptive, not derived.

By the end, you’ll be able to

The single capability this lesson builds: explain what Agent Skills are, how Claude Code reads them, and the durable-instructions pattern they enable (per the Phase 0 lesson 10 capability mapping). Concretely, you will be able to:

State what an Agent Skill is verbatim (modular capabilities packaging instructions + metadata + optional resources that Claude uses automatically when relevant) and how it differs from a prompt (load-on-demand vs conversation-level one-off)
Compose a valid Skill on disk (SKILL.md with required name + description frontmatter; markdown body; optional bundled .md files and scripts/ subdir), respecting the frontmatter constraints (name max 64 chars, lowercase-alphanumeric-hyphens, not “anthropic” or “claude”; description max 1024 chars describing BOTH what and when)
Explain progressive disclosure (Level 1 metadata always loaded around 100 tokens per Skill; Level 2 SKILL.md body loaded when triggered under 5K tokens; Level 3 bundled resources loaded as needed effectively unlimited) and the two operational consequences (many Skills installable without context penalty; bundled content has zero context cost until accessed)
Choose the right surface for Skill deployment (Claude API with three beta headers + skill_id; Claude Code via filesystem; claude.ai via zip upload), knowing custom Skills do NOT sync across surfaces
Recognize Claude Code as a worked L8-loop-in-production (verbatim: an agentic coding tool … available in your terminal, IDE, desktop app, and browser), map its features back to L4 / L5 / L6 / L7 / L8, and compose Skills + Claude Code to make the L9 patterns durable team artifacts

Time and difficulty

Read time: about 15 minutes
Practice time: about 15 minutes (the try-it-yourself converts a repeated prompt into a Skill on disk, validates the frontmatter, and installs it in Claude Code or claude.ai, plus flashcards for retrieval)
Difficulty: standard. The Skill format is small (one SKILL.md, two required frontmatter fields, optional bundled content); the discipline is writing the description tightly enough that the description-as-router judgment lands reliably. The hardest skill is recognizing the per-surface mechanics and constraints (especially the three beta headers and NOT-ZDR-eligible status on the API surface); the easiest is recognizing the composition opportunity (most production agents have three to five recurring prompts that are obvious Skill candidates).