Jonathon's AI Wiki

Building Agents with Skills (Progressive Disclosure, Skill Types, Open Standard)

6 min read

Source: Anthropic Blog Building Agents With Skills 2026 01 22 (Anthropic blog, Jan 22 2026 — https://claude.com/blog/building-agents-with-skills-equipping-agents-for-specialized-work)

Anthropic’s argument for why skills — not specialized agents — are the right primitive for domain expertise. Introduces progressive disclosure (three-tier context architecture), three skill types (Foundational/Partner/Enterprise), and the “code is all you need” design philosophy. Also announces Agent Skills as an open standard, portable across AI platforms.

Key Takeaways

  • “Code is all you need.” Rather than separate specialized agents for coding, research, finance, etc., treat code as the universal interface. Claude Code is “both a coding agent and general-purpose agent operating through code infrastructure.” API calls, filesystem storage, Python analysis — all happen through code.
  • The tax-professional analogy. Raw model intelligence is a “math genius figuring it out from first principles.” Skills add “an experienced tax professional who’s filed thousands of returns.” General reasoning ≠ accumulated domain expertise. Skills bridge that gap.
  • Three-tier progressive disclosure. Skills use layered context to fit hundreds of skills without blowing context budgets:
    1. Metadata (~50 tokens) — name + description from YAML frontmatter
    2. Full SKILL.md (~500 tokens) — full documentation, loaded when needed
    3. Reference files (2,000+ tokens) — supporting docs, loaded on demand
  • Skills are file collections, not plugins. Folder with SKILL.md, reference docs, and executable scripts. “Files are a universal primitive that works with what you already have.” Git-versionable, cloud-storable, team-shareable.
  • Skills can embed executable scripts. Rather than describing a tool in prose, ship a Python script in the skill folder. Self-documenting, modifiable, doesn’t need constant context presence.
  • Three emerging skill types:
    • Foundational Skills — core capabilities (document/spreadsheet/presentation manipulation, document generation best practices)
    • Partner Skills — built by companies (K-Dense, Browserbase, Notion) to integrate their services
    • Enterprise Skills — proprietary, encode internal processes, compliance, institutional knowledge
  • Complexity spans two orders of magnitude. Simple skills ~100 lines (templates). Intermediate ~800 lines (data retrieval, modeling). Complex 2,500+ lines (multi-step scientific pipelines).
  • Non-engineers can author skills. “Skill creation is expanding beyond engineers…they can create and test their first skill in under 30 minutes.” PMs, analysts, domain experts.
  • Agent Skills is becoming an open standard. Like MCP. “The same skill should work whether you’re using Claude or other AI platforms.” Portability matters.
  • Complete agent architecture = 4 layers. Agent loop (reasoning) + Agent runtime (code/filesystem execution) + MCP servers (external access) + Skills library (domain expertise). Each layer is distinct; skills are the domain-knowledge layer.

Skill folder anatomy

anthropic_brand/
├── SKILL.md              ← progressive disclosure metadata + full docs
├── docs.md               ← reference file, loaded on demand
├── slide-decks.md        ← reference file, loaded on demand
└── apply_template.py     ← executable script, callable by the agent

A skill is a folder with at least one SKILL.md. Everything else is optional. Scripts make the skill active — the agent can run them rather than re-derive their logic.

Vertical deployment examples (from the blog)

Financial Services

  • DCF model builder
  • Comparable company analysis
  • Earnings analysis
  • Initiation coverage reports
  • Due diligence frameworks
  • Pitch materials

Healthcare & Life Sciences

  • Bioinformatics bundles (scVI-tools, Nextflow)
  • Clinical trial protocol generation
  • Scientific problem selection
  • FHIR development
  • Prior authorization review

The four-layer agent architecture

LayerPurposeExample
Agent loopCore reasoningClaude model deciding what to do next
Agent runtimeExecution environmentCode execution, filesystem access
MCP serversExternal connectivitySlack, Notion, S&P Capital IQ
Skills libraryDomain expertise + proceduresDCF model builder skill

The layers compose. Skills + MCP sit at different layers but work together — skills orchestrate, MCP provides access, runtime executes, loop decides.

Why this matters for skill adoption

  • Git-native workflow. Skills live in folders; they version, diff, and review like code. Teams already know how to ship files.
  • Discovery scales. Progressive disclosure means an agent can see names of hundreds of skills cheaply (~50 tokens each) and only load full content when needed. This is the architectural answer to “how do I add 200 skills to my agent without destroying the context window?”
  • Cross-platform portability. As skills become standardized, a skill written for Claude should run on other AI platforms. Investment in a skills library becomes portable capital, not vendor lock-in.

Implementation

  • Tool/Service: Claude (desktop, web, Code, API)
  • Setup: Create a folder with SKILL.md. Use YAML frontmatter for metadata. Add reference docs and scripts as needed. Place under .claude/skills/ for Claude Code or distribute via the skills library.
  • Cost: Free to author. Runtime cost is the token cost of loading the skill (metadata → full → reference, per progressive disclosure).
  • Integration notes: Skills compose with MCP servers (access), plugins (distribution bundles), and subagents (parallel execution). The skills ecosystem article covers discovery and distribution.

Open Questions

  • Open standard governance. “Agent Skills is becoming an open standard” — who governs it, where does the spec live, how are breaking changes handled?
  • Runtime for scripts. Skills embed Python and other executables. What runtime provides the execution environment — the user’s local machine, Claude Code’s sandbox, Managed Agents infrastructure, or all three?
  • Skill-to-skill composition. Can skill A invoke skill B? The blog implies yes (Notion Meeting Intelligence + Notion MCP), but the mechanism isn’t specified.
  • Partner-skill discovery. The blog names partners (K-Dense, Browserbase, Notion). Where does the canonical partner-skill catalog live?
  • Versioning + compatibility. If a skill expects a specific Claude version or MCP version, how is that declared?

Try It

  1. Author a minimal skill. Pick a workflow you repeat — weekly report, code review checklist, email template. Create a folder with a SKILL.md containing YAML frontmatter (name, description) and the procedure. Drop it in .claude/skills/ and run Claude Code. Under 30 minutes start to finish.
  2. Install one foundational + one partner skill from https://github.com/anthropics/skills. Use them both on a real task. Observe how progressive disclosure keeps context manageable.
  3. Layer a skill on top of an MCP. Find an MCP you use (Notion, Linear, GDrive). Write a skill that encodes a standard workflow on top of it. This is the core composition pattern the Dec 19 blog argues is the real leverage point.
  4. Identify enterprise-skill candidates. Walk the team and list procedures currently living in runbooks, Notion pages, or tribal knowledge. Each is a candidate enterprise skill.
  5. Watch the “Don’t Build Agents, Build Skills Instead” talk at https://youtu.be/CEvIs9y1uog for Anthropic’s own framing.

Graph View

Backlinks