Skip to content
Clawdemy

Summary: Agent Skills and Claude Code

The durable-instructions layer for the L9 patterns and a worked agent harness that reads it. Agent Skills (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. Different from a prompt: 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. On-disk: a directory with SKILL.md at the root. YAML frontmatter (required name max 64 chars lowercase-alphanumeric-hyphens; required description max 1024 chars describing both WHAT the Skill does AND WHEN to use it). Body is markdown. Optional bundled files (additional .md, scripts/ with executable code) referenced from SKILL.md and loaded on demand. Progressive disclosure (the architecture trick): Level 1 metadata always loaded in system prompt (around 100 tokens per Skill); Level 2 SKILL.md body loaded when triggered (under 5K tokens); Level 3 bundled resources loaded as needed via bash (effectively unlimited; scripts run with only output entering context). The description is the router. Three surfaces: Claude API (upload via /v1/skills; pre-built via skill_id in container; three beta headers code-execution-2025-08-25 + skills-2025-10-02 + files-api-2025-04-14; workspace-shared; NOT ZDR eligible); Claude Code (filesystem at ~/.claude/skills/ personal or .claude/skills/ project; auto-discovery; no upload); claude.ai (zip upload through Settings > Features; per-user). Custom Skills DO NOT sync across surfaces. Claude Code (verbatim): 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. Worked example of the L8 loop in production; surfaces share the same engine + CLAUDE.md + Skills + MCP configuration; tools span L4 (custom via Agent SDK) + L5 (built-in bash, text_editor) + L6 (MCP). Skills + Claude Code = L9 patterns as durable team artifacts: routing becomes a directory of branch Skills; chaining becomes a chain of Skills; orchestrator-workers becomes an orchestrator Skill calling worker Skills; autonomous agent becomes Claude Code reading your domain Skills. Git-tracked, code-reviewable, team-shareable, auto-discoverable. Security (verbatim): Use Skills only from trusted sources: those you created yourself or obtained from Anthropic. Lesson 11 covers Subagents + Claude Managed Agents (focused inner loops for patterns 4 + 6); Lesson 12 ships the result.

Core ideas

Section titled “Core ideas”
  • Agent Skills are the on-disk durable-instructions layer. A directory with SKILL.md at the root + YAML frontmatter (name + description) + optional bundled .md files and scripts. Verbatim: modular capabilities that extend Claude’s functionality… Claude uses automatically when relevant.
  • Frontmatter rules: name max 64 chars lowercase-alphanumeric-hyphens (cannot be “anthropic”/“claude”); description max 1024 chars, must say BOTH what the Skill does AND when to use it. The description is the router.
  • Progressive disclosure: L1 metadata always loaded (~100 tokens/Skill; in system prompt); L2 SKILL.md body loaded when triggered (under 5K tokens; read via bash); L3 bundled resources loaded as needed (effectively unlimited; scripts run with only output entering context). Many Skills installable without context penalty; bundled content has effectively zero context cost until accessed.
  • Three surfaces, no sync. Claude API (upload + skill_id; 3 beta headers; workspace-shared; NOT ZDR). Claude Code (filesystem; auto-discovery; no upload; ~/.claude/skills/ personal or .claude/skills/ project). claude.ai (zip upload; per-user). Manage per surface.
  • How Claude finds and invokes a Skill: discovery via description match in the system prompt at L1; invocation via the bash tool reading SKILL.md (L5 Anthropic-schema client tool) at L2; bundled files and scripts read/run via further bash calls at L3.
  • Claude Code (verbatim): an agentic coding tool that reads your codebase, edits files, runs commands, and integrates with your development tools. Surfaces: terminal CLI, VS Code, JetBrains, desktop, web, iOS. All share the same engine.
  • Claude Code maps to T22: L4 (custom via Agent SDK) + L5 (built-in bash/text_editor + web search) + L6 (native MCP via config) + L7 (CLAUDE.md auto-cached; auto memory across sessions) + L8 (Claude Code IS an L8-style loop, productionized).
  • Composition (Skills + Claude Code = L9 patterns durable): routing → directory of branch Skills; chaining → chain of Skills; orchestrator-workers → orchestrator Skill naming worker Skills; autonomous agent → Claude Code + domain Skills. Git history, code review, team-shareability, surface portability, auto-discovery by description.
  • Security (verbatim): Use Skills only from trusted sources: those you created yourself or obtained from Anthropic. Four named risks: tool misuse, data exposure, external-source compromise, Skills that fetch external URLs (fetched content may carry instructions). Audit before installing.
  • Where this fits: Phase 3 third lesson. L11 (next) covers Subagents + Claude Managed Agents (focused inner loops for patterns 4 + 6). L12 ships.

What changes for you

Section titled “What changes for you”

Before this lesson, every prompt and every pattern from L9 lived in your application code as strings; no version history, no code review, no auto-discovery, no reuse across applications. After this lesson, the same patterns can live as Skills on disk: Git-tracked, PR-reviewable, auto-discovered by description, surface-portable (modulo per-surface upload). The two highest-leverage moves this week: (1) for any in-application agent you maintain, identify the three or four prompts that get edited most and convert them to Skills (immediate version history; A/B-able; team-reviewable; zero token cost when not relevant thanks to progressive disclosure); (2) if you code professionally, install Claude Code (curl https://claude.ai/install.sh | bash; then claude in any project), write a project CLAUDE.md with your team’s coding conventions, and add a .claude/skills/ directory under version control so your team’s domain expertise travels with the repo. Lesson 11 picks up the orchestrator-workers + autonomous-agent threads directly: how Sub-agents (the Anthropic primitive Claude Code surfaces) and Claude Managed Agents make patterns 4 and 6 production-ready. Lesson 12 ships the result.