@skills: Attention Is All You Have

TL;DR

Agent “skills” are folders of Markdown instructions (a SKILL.md file) that teach an agent how to do something: deploy a service, write a changelog, drive Stripe. Today the only way to keep one around is to install it, which drops its one-line description permanently into the system prompt, where it competes for the model’s attention on every single message. There are 56,804 public skills and, the paper argues, fewer than a hundred reliable “attention slots” per agent, so the math is hopeless: the vast majority of skills have no way to reach you. The fix is not more tooling. It is noticing that installing does three separable things — delivering content, persisting it, and auto-triggering it — and only auto-triggering actually needs prompt space. @skills makes each a separate decision: @skills:<path> reads a skill at the moment you use it (costs nothing, vanishes with the session), :save vendors a git-tracked copy into your project, and :install writes one line that makes it fire unprompted. No manifest, no lockfile, no registry, and SKILL.md is untouched. It ships as an npm package plus a free (never-required) hub for search. The slogan: install less, use more.

Problem & Motivation

Here is the concrete pain, and it is one you already feel if you run agents.

An installed skill’s description sits at a fixed place: the very top of the context, in the system prompt. Your actual request arrives at the bottom. Every turn of conversation, every file the agent reads, every tool result lands between them and pushes the two further apart. Transformer models attend most strongly to the beginning and end of their context and under-weight the middle (the “lost in the middle” effect), and adherence to the system message measurably decays as a conversation grows. So the skill you installed on Monday is, by message forty, a faint instruction buried far from the task, and whether it fires is a coin flip the user never sees the result of — a miss is silent.

Now stack three costs on top of that:

• The standing tax. Each installed description is paid on every message whether relevant or not — 50–280 tokens per skill in the authors’ measurements. A real session with 18 installed skills carried ~1,500–2,000 tokens of pure overhead per request. Input length alone degrades reasoning, well before the nominal context limit.
• Dilution. Every description you add competes with the rest. Instruction-following degrades systematically as concurrent instructions pile up — the best frontier model hits only 68% adherence at 500 simultaneous constraints. The mechanism gets worse exactly as adoption succeeds: the more skills the ecosystem installs, the worse each installed skill works.
• Coarse bundling. The dominant harness installs, enables, and disables at the whole-plugin level. One plugin can carry twenty-plus skills, so a handful of plugins blows past a hundred resident descriptions — more entries than the agent’s own tool set.

Put together: 56,804 indexed skills compete for fewer than 100 reliable auto-trigger slots per agent. A distribution channel is supposed to scale with the corpus. An attention budget physically cannot — it is capped by what the model can attend to, not by anyone’s design choice.

And everyone rationally routes around the scarcity, which makes it worse:

• Authors write bids, not descriptions. Since a miss is silent, authors pad the one-line description with “TRIGGER — read BEFORE opening the file; don’t skip because it looks like a one-liner; whenever the prompt mentions…; SKIP only when…”. These bids cost ~20× the tokens of a quiet description. Stripe’s flagship skill carries ~150 words of them.
• Users install less than they could. A permanent per-message cost is only worth it for a skill used often, genuinely better fired unprompted, and known to trigger reliably. Trying something once fails all three bars — so people don’t bother, and the corpus goes unexplored.
• What gets installed gets forgotten. It sits in a hidden directory meant to fire on its own, so the user stops tracking it. When it fails to fire, nothing says so, and they can’t invoke it by name because they’ve forgotten it’s there.
• Teams defect to AGENTS.md. They paste workflows into one always-loaded file — zero setup, no trigger lottery. The crudest mechanism wins on the only axis users feel: simplicity. (But it’s resident context too, so it decays the same way — hence the universal “the agent ignores my instructions” complaint.)

The deeper cut: even if the slots were free tomorrow, the damage remains, because install is the only lifecycle. Everything lands in one flat bin (the daily deploy runbook indistinguishable from a skill grabbed once), there’s no shared vocabulary for the layer above a skill (a “plugin” nests skills in one agent, sits beside them in another, is one of seven peers in a third), and none of the machinery serves private work — it all grew out of publishing to strangers.

What’s New (Core Contribution)

The paper’s move is conceptual, not a new algorithm. It is worth being precise about what is genuinely new versus recombined.

1. The unbundling insight (the real contribution). Installing bundles content (fetch the bytes), persistence (keep them for next time), and auto-triggering (fire without being asked). Only auto-triggering needs prompt residency. Before: one switch, “install,” bought all three whether you wanted them or not. Now: two orthogonal, combinable suffixes (:save = own a copy, :install = fire unprompted) plus the bare reference, so a single bundled question becomes two independent decisions and all four combinations are reachable.

2. Three delivery tiers, priced by need. Before: every skill paid the maximal cost (permanent residency) for the same scarce benefit (a shot at triggering), used once a year or every message. Now: Tier 1 Reference (@skills:<path>, 0 resident tokens, reading is using, gone with the session — the whole 56k long tail); Tier 2 Saved (.atskills/, git-tracked, 0 resident tokens, findable — the team’s 10–30 working-set playbooks); Tier 3 Installed (one .autotrigger line, only the frontmatter resident — the <10 essentials that must fire unprompted). Each skill sits in the cheapest tier that meets its activation need.

3. The management model is nothing but the filesystem. Before: registries, manifests, lockfiles, per-agent install databases, an update lifecycle, version pinning. Now: a path, a folder (.atskills/), a .gitignore-style trigger file (.autotrigger), and a two-line provenance stamp (.source). No manifest, no lockfile, no registration — because a file tree needs none. SKILL.md gains zero new fields. Reversal is symmetric: uninstalling deletes the one line installing added.

4. A directory is a menu (composition as a property of the address). Before: a “bundle” was all-or-nothing; the nearest non-installing tool resolves exactly one skill per call. Now: a path with no SKILL.md loads as a menu — one line per skill beneath it, each line itself a valid path. Five references can load in one message, from four different sources, each injected at its own point of use. Co-firing N skills is deterministic instead of a compounding N-way lottery.

The honest framing from the authors: “the most useful thing to say about this protocol is how little of it is new.” The @ gesture, .gitignore semantics, git as transport, Go-style vendoring, the SKILL.md format — all already existed. The contribution is subtraction: removing the install lifecycle and using pieces you already have for delivery.

The unbundling, made clickable (after Fig. 2). Installation forces one bundled switch and only ever gives you the top-right cell. Toggle the two real questions — "own a copy?" and "fire unprompted?" — to see all four reachable cells and what each costs in resident tokens. Only the right column (firing unprompted) ever spends the prompt.

How It Works (Technically)

There is almost no math in this paper — the “budget” is an argument from the positional-attention literature, not an equation. The mechanism is a small protocol. Let’s trace one real request end to end, then look at the two algorithms that matter.

The trace. You (or the agent itself) type a message containing @skills:gh:stripe/agent-toolkit/payments ship the release. Here is what happens:

1. Parse identity. The token after @skills: is the identity. gh: means GitHub; stripe/agent-toolkit/payments is the path within it. The prefix decides resolution — a bare path is the project’s own and never touches the network; hub: and gh: name the cloud. There are two orthogonal suffixes: :save and :install. Here there are none, so this is a plain reference.
2. Resolve, local-first. Look for a folder at .atskills/gh/stripe/agent-toolkit/payments (colons become slashes on disk). If it exists, that’s the project’s own saved copy — read it, done, no network. This is vendoring: a saved copy sits at its ID’s own path, so it answers its own address. If there’s no local folder, the path means the cloud.
3. Validating cache (browser semantics). Cloud content lives in one machine-wide cache (~/.cache/atskills/). Each use fires a single revision probe — a git ls-remote, which is a question (“did this change?”), never a download. Unchanged → serve the cache instantly. Changed → fetch fresh. Offline but cached → serve the cache, marked stale. Offline and nothing cached → fail and say exactly why.
4. Fetch, in three phases (if needed). Phase 1: a shallow, blob-filtered, no-checkout git clone pulls the directory structure but not one file body. Phase 2: git ls-tree counts the skills from tree metadata alone and enforces the cap (K=128) before any content downloads — a whole marketplace repo as one path is refused, with the loadable sub-collections named. Phase 3: sparse-checkout materializes just the sub-path; repo cruft (README, LICENSE, .git, symlinks) never lands.
5. Inject at the point of use. The full SKILL.md body streams into the context at the end, right next to your task — the position where model attention is highest. This is the whole point: an installed skill decays because it’s stuck at the top; a referenced skill lands where compliance is most reliable.

That is Tier 1. Nothing was stored; the skill evaporates with the session.

Add a suffix and you change tier, not mechanism:

• :save runs a fetch, then copies the result to .atskills/<path>/ and writes a two-line .source stamp (origin ID; date + upstream revision). At that instant the copy detaches — it’s now an ordinary project file, not a subscription. There is deliberately no “update” command: to refresh, you save again (safe by construction — see below); to control it, you own it and edit it.
• :install appends one line to .atskills/.autotrigger. That line, and only that line, buys residency — the skill’s frontmatter (~50–100 tokens) now loads at session start, and its body still loads only when it fires.

The residency algorithm — what actually reaches the model. At session start, the client reads .autotrigger (a .gitignore-style file: plain line = your own skill, @ line = a followed cloud skill, trailing / = a whole directory), resolves each line local-first, dedupes to one entry per skill, and emits one string: a block of - name: description (path) rows, frontmatter only. The host’s prompt-assembly step splices that string in verbatim. That’s the architectural trick that makes adoption trivial — the serving backend contains zero protocol logic; it stores one string. The management surface (/skills) can therefore never disagree with what the model receives, because both are the same computation.

Architecture & data flow

flowchart LR
  U["User or agent types<br/>@skills:path[:save][:install]"] --> P[Parse: identity + suffixes]
  P -->|bare path| L{"folder at<br/>.atskills/path ?"}
  P -->|"hub: / gh:"| L
  L -->|yes: the project's own| INJ[Inject full SKILL.md<br/>at end of context]
  L -->|no| CACHE["Validating cache<br/>~/.cache/atskills"]
  CACHE -->|"one revision probe"| SRC[(git / hub source)]
  SRC -->|unchanged| INJ
  SRC -->|changed: 3-phase fetch| INJ
  P -.->|":save"| SAVE[".atskills/path/ + .source<br/>(detached copy)"]
  P -.->|":install"| TRIG[".autotrigger<br/>one line"]
  SAVE -.-> L
  TRIG --> RES["Residency: frontmatter only<br/>-> spliced into system prompt"]

Why position is the whole game (schematic, after Fig. 5). Drag the slider to grow the conversation. The installed skill's description is pinned at the top of the context, so a growing session pushes it away from the task and its attention drops. The `@skills` reference is injected at the bottom, adjacent to the task, where attention stays highest. This is intuition, not the paper's measured data.

The algorithm, simplified

The one central idea, as runnable-looking Python. resolve() is the heart — local-first, then a validating cache — and resident_block() is what turns “install” into a single string.

# Stubs: git_head_rev(id) -> str|None (one ls-remote probe), git_fetch(id, dest, rev),
#        read_dir(path) -> Skill|Menu, cache_meta(id) -> (rev, when)|None

K = 128  # collection cap: refuse a whole-marketplace reference before downloading it

def resolve(path):                          # Algorithm 1, simplified
    ident = normalize(path)                 # fold hub case; gh: keeps casing; URLs -> gh:
    local = ".atskills/" + on_disk(ident)   # gh: spelled gh/ ; colons can't be folder names
    if is_dir_with_content(local):
        return describe(ident, local)       # LOCAL FIRST -- .source is never read to resolve
    return read_through_cache(ident)        # no local folder => the path means the cloud

def read_through_cache(ident):              # browser semantics over git
    cache = "~/.cache/atskills/" + on_disk(ident)
    rev   = git_head_rev(ident)             # a QUESTION, not a download
    meta  = cache_meta(ident)
    if cached(cache) and rev == meta.rev:   return describe(ident, cache)   # unchanged: instant
    if cached(cache) and rev is None:       return describe(ident, cache, stale=True)  # offline
    git_fetch(ident, cache, rev)            # changed (or first time): 3-phase fetch, enforce K
    return describe(ident, cache)

def describe(ident, d):                      # a single skill, OR a directory-as-menu
    if has_file(d, "SKILL.md"):
        return Skill(body=read(d))           # inject full text at the point of use
    skills = walk_leaf_rule(d)               # a folder holding SKILL.md is a skill; stop there
    assert len(skills) <= K                  # else refuse, naming the sub-collections that fit
    return Menu([(ident + "/" + rel, frontmatter(s)) for rel, s in skills])

def resident_block():                        # Algorithm 3: what "install" actually costs
    entries = parse_autotrigger(".atskills/.autotrigger")   # gitignore syntax
    resident = dedupe(resolve_each(entries))                # local-first per line, one skill once
    # ONLY frontmatter is resident; bodies load on trigger. Host splices this string verbatim.
    return "\n".join(f"- {s.name}: {s.description} ({s.path})" for s in resident)

Save is conflict-safe by construction (Algorithm 2), and it’s worth seeing why it needs no stored state. To refresh a saved copy you save again. The protocol re-fetches upstream at the revision recorded in .source (git content is immutable and fetchable by hash) and compares bytes. If your copy is byte-identical to what you originally took, it’s “unedited” → safely replaced. If it differs (you adapted it) or can’t be verified → it’s a conflict, nothing is touched, and you’re offered keep / refetch / ask-the-agent-to-merge. No digests, no lockfile — git’s content-addressing is the merge base.

Built on Prior Work

The paper’s own claim is lineage-heavy, so this table is the honest map of what’s borrowed versus new.

Results & Evidence

This is a design paper grounded in measurement, not an experiment paper. Be clear-eyed about what it does and doesn’t establish.

What they measured (real):

• A July 2026 crawl resolved 56,804 SKILL.md directories across 1,133 public repos; 99% of bodies were fetched and analyzed. This corpus size is the paper’s anchor number.
• Provider migration is real and structural: 21 major-provider orgs publish 958 first-party skills (AWS 138, Google 92, Elastic 70, Anthropic’s collections 379…). Of 569 skills in 15 provider product repos, 79% name the provider’s own CLI/API and 60% contain executable shell blocks. 42% of a classified sample require an external account.
• Skills are too big to be resident, small enough to fetch: median body 921 words (~1.2k–3.7k tokens), 90th percentile 2,207 words. Keeping a working set resident is impossible; fetching one on demand is cheap.
• Fragmentation is measured: one format lives in 54 distinct project-level directories across 75 agents (and 58 home-directory locations). Pure accident — same files, different namespaces.
• The long tail already lives in registries: the top 15 repos hold 51% of the corpus; it’s one HTTP request away, gated only by per-user install.
• Token costs (50–280/skill description, ~20× for trigger-engineered ones) come from one real working setup.

What it does NOT establish (the caveats the authors themselves flag):

• The central number — “fewer than 100 reliable auto-trigger slots” — is not measured. It’s bounded by argument and by the instruction-following literature. The strongest cited experiment (68% adherence at 500 constraints) measures concurrent constraints, not trigger descriptions, so it’s suggestive, not direct. The authors correctly propose measuring trigger reliability vs. install count as future work.
• Classification figures come from a 100-skill sample (~±10 points at 95% confidence).
• Token measurements are one setup, not a survey.
• The whole protocol is implemented and in production in AdaL (the authors’ own agent) — so it works, but there’s no independent comparison, no user study, no A/B on adoption or task success.
• Conflict of interest, disclosed: the lead author founded SylphAI, which builds AdaL and runs the hub. The format and protocol are open precisely so neither is required — gh: and local paths work with no hub at all. Read the hub sections as advocacy for infrastructure the authors operate.

The evidence strongly supports the problem (install-only delivery cannot scale to 56k skills, and everyone routes around it). The solution’s superiority is argued and demonstrated in one production system, not proven comparatively. That’s an honest state for a protocol proposal — protocols win by adoption, not benchmarks.

How You’d Use It

This one lands directly in your world — you run an AI services company and you literally maintain a large skill library (169 local skills, per your own setup). Three concrete angles:

1. Fix your own context bloat first. If your agents install skills whose descriptions sit resident, you’re paying the standing tax and the dilution on every client call. The paper’s practical prescription is a triage:

• Keep < 10 truly-must-fire-unprompted skills installed (formatter conventions, security guardrails). Everything else comes off the resident budget.
• Move your team’s daily playbooks (deploy runbook, review checklist, migration steps) to Tier 2 — a git-tracked .atskills/-style folder, loaded by explicit reference at the point of use. This is your CLAUDE.md/AGENTS.md factored into per-procedure files that stop taxing every message. Worth noting: your own global config already contains the exact “TRIGGER — read BEFORE opening the target file; don’t skip because it looks like a one-liner” pattern the paper quotes as the trigger-engineering pathology. That’s the tell that you’re bidding for scarce slots. Reference delivery removes the need to bid.
• Everything occasional or one-off → Tier 1, referenced by name, zero residency.

2. A client offering: “skill hygiene / context engineering.” Most teams running coding agents have silently drifted into 100+ resident descriptions and don’t know it. A concrete, sellable engagement: audit a client’s resident prompt (the paper’s view prompt idea — show them the exact text and token count the model receives), then re-tier it. You’re selling measurable prompt-cost reduction and more reliable triggering. The deliverable is a .autotrigger-style file of one-line diffs any reviewer understands.

3. Ship skills as a product/integration channel. The corpus data shows providers (AWS, Stripe, Google) are moving from “maintain an MCP server per client” to “ship one CLI + one skill that teaches any agent to drive it.” If you build tools for clients, a SKILL.md that drives your product reaches every agent with a shell, no per-agent server to maintain. Publish it on GitHub (gh: identity is permanent and hub-independent) and it’s addressable by anyone via @skills:gh:you/skills/....

The realistic effort: adopting the consumer side is near-zero — the protocol ships as one instruction file (SKILLS.md) that turns any file-reading, shell-running agent into a client, or a small reference CLI you shell out to. Re-tiering an existing skill library is a day of triage, not an engineering project.

Build Your Own (Minimal Recipe)

You can build a useful subset in an afternoon; ~80% of the value is Tier 1 + Tier 2 with a validating cache. Build order:

1. Reference resolver (Tier 1). Parse @skills:<path> out of a message. Bare path → look in a local .skills/ folder; gh:owner/repo/sub → shell out to git. Inject the SKILL.md body at the end of the prompt you send the model. This alone gives you deterministic, zero-residency skill loading. Hard part: nothing — it’s string parsing plus a git clone.
2. Directory-as-menu. If the path has no SKILL.md, walk it with the leaf rule (a folder containing SKILL.md is a skill; stop descending) and return path: description lines. Cap the walk (K≈128) so a giant repo can’t dump thousands of skills. This gives you subtree/collection references for free.
3. Validating cache. Cache clones under ~/.cache/yourtool/. Before serving, do git ls-remote to get the head revision; compare to what you stored. Match → serve instantly; differ → re-fetch; offline → serve stale. This is the one piece with real subtlety — get the “probe, don’t download” discipline right and repeated use is one round trip.
4. Save (Tier 2). Copy a resolved skill to .skills/<path>/ and write a two-line .source (origin ID; date + git rev-parse HEAD). To “refresh,” re-fetch at the recorded rev, byte-compare, and only overwrite if unedited. No lockfile needed — git’s hashes are your ground truth.
5. Residency (Tier 3), optional. A .autotrigger file with .gitignore semantics; at session start, emit one string of frontmatter rows and splice it into the system prompt. Keep the list short by policy.

Libraries/tools to reach for: plain git (shallow --filter=blob:none --sparse clone for the phased fetch), your language’s .gitignore matcher for .autotrigger, and — if you want the real thing instead of a toy — npm i atskills, which ships the spec, a TypeScript core, and the reference CLI (atskills get / save / triggers / prompt). The two genuinely hard parts are the cache validation discipline (probe vs. download; stale/offline handling) and the save-again conflict logic (verifying “unedited” against upstream at the recorded revision rather than a stored hash).

How to Improve It

Limitations are leverage. Five concrete, testable directions:

1. Actually measure the budget. The load-bearing claim (”< 100 slots”) is unmeasured. Run the experiment the authors punt on: trigger reliability as a function of installed-skill count, for skill-sized descriptions, across models. A clean curve here would turn an argument into a result — and would tell every team exactly how many skills they can safely install.
2. Add a retrieval layer for discovery (the acknowledged gap). Explicit reference is deterministic but you can’t reference a skill you’ve never heard of. Embed all descriptions, retrieve top-k per message, inject at the end of the context (production agents already do this for tool schemas). You’d recover implicit discovery for the long tail while keeping explicit references deterministic. The two compose; the paper calls this natural future work.
3. Attack the security surface concretely. A referenced skill is remote text an agent then acts on — the indirect-prompt-injection channel, and no model-level defense reliably stops it. Build the vetting the protocol enables: a sandboxed single-session trial (isolated worktree / container / restricted-permission run) that watches a skill end-to-end before it’s ever granted persistence, plus digest/provenance checks against typosquatting on catalog slugs. This is a product, not just a paper section.
4. Latency: reference puts a network round trip on the critical path. The validating cache reduces repeats to one probe, but first use and long-session re-referencing still cost. Prefetch on autocomplete, warm the cache from .autotrigger at session start in parallel, and speculatively resolve references the agent is likely to emit.
5. Cross-agent portability test. The pitch is “one store, every agent.” Prove it: take one .atskills/ tree and drive it from three different agents via the SKILLS.md instruction-file path, and measure whether behavior is actually identical. Portability claimed is not portability shown.

Glossary

• Skill / SKILL.md — a directory with a SKILL.md file: YAML frontmatter (name + one-line description) plus Markdown instructions and optional scripts/reference files; procedural knowledge an agent reads.
• Resident / residency — text that occupies the system prompt on every message of a session. The scarce resource this paper is about.
• Auto-triggering — the model matching a user’s message against a skill’s one-line description and loading the skill’s body if it seems relevant. Probabilistic; a miss is silent.
• Frontmatter — the small YAML header (name + description, ~50–100 tokens) at the top of a SKILL.md. The only part an installed skill keeps resident.
• The three tiers — Reference (@skills:<path>, 0 tokens, gone with the session), Saved (.atskills/, git-tracked, 0 resident tokens), Installed (one .autotrigger line, frontmatter resident).
• .atskills/ — the project-root folder holding saved skills, the trigger file, and stamps. The protocol’s only new storage location.
• .autotrigger — a .gitignore-style file; each line makes a skill (or directory) fire unprompted. “Install” = add a line; “uninstall” = remove it.
• .source — a two-line provenance stamp on a saved skill (origin ID; date + upstream git revision). Pure record — never read to resolve anything.
• Vendoring — keeping a copy of a dependency at its own identity path inside your project (as in Go’s vendor/), so it answers its own address and resolves before the network.
• Validating cache — a machine-wide cache with browser semantics: every use asks the source “did this change?” (one revision probe), serving instantly if not, fetching if so, serving stale if offline.
• Leaf rule — when walking a directory, a folder containing a SKILL.md is a skill and you stop descending, so a nested SKILL.md belongs to the bundle above it and repo cruft is never mistaken for a skill.
• Revision probe — a git ls-remote that returns the head commit hash without downloading content; how the cache checks freshness cheaply.
• Lost in the middle — the finding that transformers attend most to the start and end of their context and under-weight the middle, regardless of relevance. The mechanical basis for the “attention budget.”
• Trigger-engineering — padding a skill’s description with “read this BEFORE…”, “TRIGGER whenever…”, “SKIP only when…” to win the auto-trigger lottery; costs ~20× the tokens and dilutes everyone else.
• AGENTS.md / CLAUDE.md — a single always-loaded instructions file at the repo root; the crude but dominant way teams deliver agent knowledge, which Tier 2 aims to replace with per-procedure files.
• Hub — SylphAI’s free (never-required) service for search, hosting, and private/team collections; does the jobs a file tree can’t (finding), while gh: and local paths work with no hub involvement.