Agent Skills

Tanvi Singhal, Gabriela Hernandez Larios, Debanshu Dus, Lavi Nigam, and Smitha Kolan · pdf · 2026-06-10 Reader 🖥️

Agent Governance (Internal)Agent Skills Context Rot & Context Limits Evals Meta-Skills & Contextual Judgment Progressive Disclosure

Agent Skills are the engineering primitive that gives AI agents testable procedural memory — how to do things, not just what is true — and because the format is deliberately thin (a folder, a markdown file, optional scripts), the real and still-unsettled work is everything built around it: evaluating skills under realistic co-loaded conditions, governing who may author and promote them, and composing them into production systems — work that is organizational and engineering discipline, not a model capability.

practical · expository/prescriptive — A vendor-adjacent (Google-curated, multi-author) technical whitepaper aimed at two personas — Builders and Developers. Mostly exposition of an emerging standard (agentskills.io) plus prescriptive engineering and governance practice, grounded throughout in cited benchmarks and production postmortems rather than pure opinion.

Structure

Part	Role
Sec. 1-2: What a Skill is, its anatomy, and the two authoring paths (translating existing knowledge vs. crystallizing a successful agent run)	definition + onboarding
Sec. 3: Why Skills displaced reflexive multi-agent architecture, with explicit scope limits on that claim	architectural argument
Sec. 4: The Evaluation Toolkit — four failure modes, five testing patterns, the read/draft/act authority ladder, pass^k reliability	evidence + methodology — the paper's most rigorous, benchmark-heavy section
Sec. 5: From prototype to production — token economics, the Google Agents CLI worked example, why skills (not models) are the unit of improvement	evidence + case study
Sec. 6: Meta-skills and self-improving skills, with explicit failure-mode warnings	frontier practice + risk discussion
Sec. 7: Composition (DAG orchestration, capability profiles) and 'Context Debt'	systems-architecture extension
Sec. 8 + Appendices: Trust tiers for skill sources, the practical cheatsheet, and a retail vertical case study arguing the skills library (not the agent) is the durable strategic asset	governance guidance + worked example — reframes the unity in organizational/strategic terms

Key terms

procedural memory
A missing memory type for LLM agents — remembering how to execute a task step-by-step — distinct from episodic memory (what happened) and semantic memory (facts); Skills are framed as the first credible primitive supplying it.
progressive disclosure Progressive Disclosure
A specific three-level loading architecture: skill metadata (name+description, ~50-80 tokens) always in context; the SKILL.md body loaded only when triggered; bundled scripts/references/assets loaded only as referenced — keeping active context small while available capability stays large.
pass^k
A reliability metric requiring success on every one of k repeated runs of an evaluation (not just one lucky pass), used to distinguish occasional from consistent success before an action-allowed skill graduates.
Context Debt
The accumulating cost of trying to force deterministic behavior at runtime via bloated, capitalized imperatives in a skill description ('ALWAYS DO X') that models learn to ignore, exactly as developers ignore unreadable warning walls — the fix is pushing logic into testable scripts instead ('Shift Intelligence Left').
Capability Profile
A versioned, swappable bundle of active skills, tool access, system instructions, guardrails, and model parameters that the orchestration layer tears down and rebuilds between execution states, functioning like a modular persona rather than a single static system prompt.
read / draft / act ladder
A three-tier authority model for skills (Read-Only; Draft-Only, human-reviewed; Action-Allowed, requiring adversarial red-teaming and sustained pass^k) that gates how much autonomy a skill earns, applied identically to human-written and agent-drafted skills.

Propositions

explicitAgent Skills are a procedural-memory primitive: a folder (minimally just a SKILL.md) that teaches a general-purpose agent how-to-do-it knowledge, loaded only when its description matches the task, keeping active context small while total available capability stays effectively unbounded.conf: high
explicitConverting a 50-workflow system prompt into a skills library can cut active context from roughly 150,000 tokens to about 2,000 (a 98%+ reduction), because only the matching skill's body loads per turn instead of every workflow's instructions loading every turn.conf: high
supportsAgent Skills · p11 — Osmani asserts every token loaded into context degrades performance somewhere, requiring progressive disclosure at scale; this whitepaper supplies the concrete measurement (150,000 to ~2,000 tokens, a 98%+ reduction) behind that same claim.
explicitSkills fail in four distinct, independently-testable ways — wrong/missed trigger, incorrect execution once triggered, token-budget degradation under co-loading, and regression when a new skill overlaps an existing one — and a skill is not 'evaluated' unless all four are checked.conf: high
explicitIn a 2025 benchmark of 84 real-world agent tasks (SkillsBench), 19% of tested skills made the agent perform worse than having no skill at all — a poorly designed skill is not neutral, it actively subtracts capability.conf: high
explicitVercel's production analysis found a 56% non-invocation rate for skills expected to activate consistently, and — more strikingly — a skill stripped of its instructions scored 58% on a task while the agent with no skill at all scored 63%, meaning the bare presence of an unused skill can itself subtract five points of capability.conf: high
explicitSingle-run evaluation success is a poor predictor of production reliability: on tau-bench, GPT-4o scored 61% on pass^1 but dropped below 25% on pass^8 (succeeding on every one of eight repeated runs), so action-allowed skills should be gated on sustained, not occasional, success.conf: high
explicitSkill authorship should be distributed to the domain team that already owns the underlying expertise — compliance officers, HR managers, merchandisers — rather than centralized in an AI/platform team, because adding a new skill takes hours to days and is owned by any domain team, whereas a model swap takes an ML/platform team days to weeks.conf: high
extendsHow Claude Code works in large codebases: Best practices and where to start · p5 — That extraction notes skills can be path-scoped so they activate only for the team that owns that part of the codebase; this whitepaper generalizes the same idea into an explicit organizational principle (domain teams author and own domain skills, hours-to-days cycle) with a concrete comparison against centralized model-swap cycles (days-to-weeks).
explicitSkills should be governed as code dependencies — versioned, pinned, reviewed in PRs, security-scanned before adoption — with explicit trust tiers (trust-by-default for first-party vendor skills, org-review for internally-curated skills, audit-before-adopting for community skills from marketplaces now exceeding a million listings).conf: high
explicitA reverse-engineering of Claude Code's codebase found that 98.4% of it is operational infrastructure (permission classifiers, context compaction, subagent delegation, session storage) and only 1.6% is the agent reasoning loop itself — as foundation models converge on baseline reasoning, the deterministic engineering around the model, not the model, becomes the differentiator for reliability.conf: high
extendsAgent Skills: Google-Backed AI Coding Agent Workflow · p2 — That extraction claims senior-engineer workflows can be encoded as reusable skill packages for agents to execute; this whitepaper's reverse-engineering finding (98.4% of a real coding-agent codebase is non-reasoning operational infrastructure) supplies independent evidence for exactly where that encoded discipline has to live — in the harness and skill layer, not the model.
explicitAgent-drafted skills (meta-skills authoring, trace-harvesting, metric-driven optimization) must always enter the library at the draft tier regardless of how confident the drafting agent is, with a human scanning the diff for the first several edits, because an agent permitted to edit its own skills will optimize for whatever metric it is given, including metrics that are easy to game.conf: high
extendsAgent Skills: Google-Backed AI Coding Agent Workflow · p6 — That extraction frames the agent problem as discipline, not capability; this whitepaper operationalizes the governance fix for the one place discipline most plausibly breaks down unsupervised — agents editing their own skill library — with a concrete, low-cost control (mandatory draft tier, human diff review).
explicitContext Rot and 'Lost in the Middle' research (across 18 frontier models) shows every model's performance degrades as input grows — even holding task difficulty constant — so a model's raw context-window capacity is the wrong metric for how much can safely be loaded; active context must be treated as a deliberately allocated budget, the way infra teams treat memory.conf: high
explicitA retailer's durable competitive asset is its skills library, not its custom agent or its runtime, because the runtime is commoditized (any competitor on the same generic agent runtime starts from the same baseline) while the skills library encodes the retailer's own accumulated merchandising, trades, and compliance expertise.conf: high
explicitA skill's description field is effectively the entire routing algorithm — the only thing the model sees to decide whether to load it — so it must state what it does and when (and when not) to use it, front-load trigger keywords, and be validated against a 90% trigger-accuracy target using explicit positive and negative test cases.conf: high
explicitSkills and multi-agent architectures are not competitors — multi-agent remains correct when there is genuine parallelism, real capability/security boundaries, or heterogeneous models — but many systems built multi-agent by default (one sub-agent per process variant) can be elegantly collapsed to a single agent with many skills, cutting the operational surface from N deployments to N folders.conf: high
implicitThe whitepaper's own trust-tier and governance framework is itself a skill-adoption artifact of a specific moment (early 2026, 40,000+ marketplace listings and climbing) rather than a timeless design, which the authors implicitly acknowledge by distinguishing what is 'settled' (the file format, the open standard) from what is 'still emerging' (evaluation practice, governance patterns, agent-driven authoring).conf: medium

Arguments

Teams should default to a single general-purpose agent with a skills library rather than a bespoke multi-agent architecture, for workflows that don't require genuine parallelism or capability isolation. strength: medium

Explicit premises:

Progressive disclosure keeps the token cost of N skills roughly proportional to log(N), not N, because only metadata is always loaded.
A skills library of N variants is N folders to maintain; a one-subagent-per-variant architecture is N deployments, N evaluation surfaces, and a routing layer.
Logistics/retail-style domains carry strong activation cues (SKU, order id, location) that make skill-description routing reliable in practice.

Implicit premises:

Operational maintenance cost (deployments, CI/CD surfaces) is a dominant driver of architecture choice, at least as important as raw task performance.
Routing reliability generalizes across domains with less distinctive activation cues than the logistics example chosen.

Inferences:

Domains where task-to-skill mapping is ambiguous (overlapping, non-distinctive trigger phrases) would see the skills-routing advantage erode faster than the paper's chosen example suggests.

Meta-skills (agents that author or edit other skills) should never bypass the draft tier or human review, even once the automation is demonstrably confident. strength: high