The Nature of Skills & SKILL.md Architecture

A skill packages how work gets done

Day 2 gave the agent reach through tools and protocols. Reach is not the same as expertise. An MCP server can expose inventory, customer history, or a document store, but it does not teach the agent how an experienced merchandiser plans a project or how a support lead handles an exception.

An Agent Skill packages that know-how as a focused, portable procedure. It normally begins with a SKILL.md file and can include scripts, references, and assets. The agent sees a short description first, loads the procedure only when the request matches, and retrieves supporting material only when needed.

The canonical package makes progressive disclosure concrete:

refund-duplicate-charge/
├── SKILL.md                 # Required: metadata + control flow
├── scripts/                 # Deterministic parsing, math, and formatting
├── references/              # Policies and edge-case knowledge, loaded on demand
└── assets/                  # Templates, schemas, and output resources

The runtime loads it in three levels. Level 1 is the name and description, which are always visible and therefore form the routing interface. Level 2 is the SKILL.md body, loaded only after a match. Level 3 is a specific reference or asset loaded only when the active procedure needs it; scripts can execute without placing their source in the prompt. Only SKILL.md is mandatory.

This anatomy creates a simple product rule: keep the decision path and exceptional conditions in SKILL.md; move repeated deterministic work into scripts/, deep domain material into references/, and reusable output shapes into assets/. If every turn needs an instruction, it belongs in global or project guidance rather than a skill.

Follow the refund-duplicate-charge example through the mechanism. At session start, the agent sees only a description such as “Investigate duplicate card charges for a known order; do not use for delivery status or declined payments.” When the user says “I was billed twice,” the description matches and the body loads. The body tells the agent to identify the order, check the ledger, explain eligibility, and stop before any write. It then loads the return-policy reference for the relevant market, calls a tested script to normalize transaction timestamps, and renders its result with the receipt template. The deep policy, code, and template did not consume attention before the intent was known.

Now consider the failure trade-off. Put the market policy in metadata and every turn pays for it; hide the “do not use for declined payments” boundary in a reference and the correct skill may never load; encode timestamp math as prose and the model may implement it differently each time. The PM's anatomy review should therefore trace one positive request and one adjacent negative request through all three levels, recording what enters context, what executes outside context, and what artifact comes out.

Two build paths, one governed artifact

Teams usually create skills through one of two paths. Path A translates existing expertise: a compliance runbook, onboarding guide, or expert interview becomes a focused procedure. The domain expert supplies the truth; the builder decomposes it and makes each rule verifiable. Path B crystallizes a successful trajectory: after the agent completes a difficult repeated task several times, a meta-skill proposes the reusable steps, scripts, and eval cases. A human still reviews the draft because one successful trace may contain a workaround rather than a durable business rule.

Both paths must end in the same product artifact: a versioned folder, accountable owner, trigger contract, permission scope, eval suite, and release tier. Path A can fail by copying a 30-page runbook wholesale; Path B can fail by overfitting to one lucky trace. The design review should therefore ask which evidence supports every step and what production case would falsify it.

Keep the layers distinct:

Skills and MCP compose. The skill knows the procedure; the MCP tool supplies the data or action. Skills also differ from a broad project instruction file because they load only when relevant. This makes them a useful product primitive for a general agent that needs to become a specialist on demand.

The same folder can be portable while its activation path is not. A local coding agent may scan a project directory after restart, an enterprise chatbot may require an admin to enable a registry entry, and an ADK runtime may expose a generated load_skill tool. In all three cases, installation is complete only when a natural positive request loads the skill, a negative request does not, the tool permissions are correct, and the trace identifies the installed version.

The following table recaps the three installation paradigms:

The open format does not standardize install paths, activation details, allowed-tools, or enterprise provisioning. A portability claim therefore needs a cross-runtime install matrix rather than “it is Markdown, so it works everywhere.”

The source's Agents CLI example packages seven skills around ADK, spanning workflow guidance, code, scaffolding, evaluation, deployment, publishing, and observability, then installs them into an existing compliant coding agent. The PM lesson is not the command: capability packaging should cover the complete lifecycle and compose with the user's current surface. Add a lifecycle coverage map to the install matrix so “portable” includes build, eval, deploy, and observe, not only discovery.

Skills became popular because they address four different frictions: context bloat from too many instructions, missing procedural memory for how work is performed, operational overload from creating a subagent for every specialist role, and portability across agent runtimes. Public adoption began with chatbot document skills, spread quickly to coding agents, and now composes with enterprise multi-agent systems through scoped skill libraries.

Use the smallest adequate primitive:

For example, 100 logistics runbooks in one prompt create immediate context rot; 100 subagents create 100 deployment and evaluation surfaces; RAG retrieves fragments but does not guarantee procedural ordering. A library of 100 narrow skills keeps routing metadata available and loads only the matching procedure. At the source's rough estimate of 50 metadata tokens each, 100 skills cost about 5,000 always-loaded tokens before an active body is loaded. The PM decision record should name the boundary that justifies the chosen primitive and include this fixed routing tax.

Before creating a second agent, ask whether the new capability truly needs a separate identity, runtime, permission boundary, or parallel execution. If not, one agent with a scoped skill can reduce deployment, routing, and evaluation overhead.