Wiki Skills: The Missing Graph Layer in Agent Context

A skill directory is a pile of pages. A wiki is a pile of pages plus links. That difference is the whole argument here.

Anthropic's Agent Skills shipped a genuinely good idea: don't hand the model everything, hand it a way to find things. The post describes three tiers. Tier one puts "the name and description of every installed skill into its system prompt" at startup - "just enough information for Claude to know when each skill should be used." Tier two is the body: "If Claude thinks the skill is relevant to the current task, it will load the skill by reading its full SKILL.md into context." Tier three is everything bundled alongside it - "additional linked files" that the agent "can choose to navigate and discover only as needed."

That is progressive disclosure, and it works. But look at the shape. Tier one is a flat list. Tier three points inward, to files inside the same directory. Nothing in the spec describes one skill pointing at another. The Anthropic post does not mention cross-skill references at all - it is about organizing files within a single skill.

So you get a library of well-structured pages with no links between them. The agent's only navigational move is "scan the flat index of descriptions, pick one." That is a card catalog, not a wiki.

Why the flat list runs out#

The cost is not obvious at ten skills. It shows up at forty.

Anthropic's context engineering post is blunt about the budget. It cites research on "context rot" showing that "as the number of tokens in the context window increases, the model's ability to accurately recall information from that context decreases." Every token spends attention. The goal it states is finding "the smallest set of high-signal tokens that maximize the likelihood of your desired outcome."

Tier one is a fixed tax against that budget. Every skill's description sits in the system prompt for every task, forever, whether or not it is ever relevant. Add a skill, everything gets slightly worse. In our repo the median skill description is 140 characters and the longest is 508. Across 36 skills that is a permanent block of text describing 35 things you are not doing.

The same post points at the fix without quite naming it. It recommends keeping "lightweight identifiers (file paths, stored queries, web links, etc.)" and having agents "dynamically load data into context at runtime using tools." It describes agents that "incrementally discover relevant context through exploration," where "each interaction yields context that informs the next decision."

Incremental discovery through exploration is what you do on a wiki. You do not read the index. You land on a page and follow a link because the page told you the link mattered.

The same conclusion, from three directions#

Three teams got here independently, which is usually a sign the idea is real rather than fashionable.

OpenAI's harness engineering post is the most direct. Three engineers, roughly a million lines of code and about 1,500 merged pull requests over five months, all written by Codex. Their AGENTS.md grew to 800 lines and agents stopped navigating it well. So they cut it to roughly 100 lines and made it a map: a structured docs/ directory became the system of record, and the short file that gets injected into context became pointers to it. Their framing is the good part - treat AGENTS.md as the table of contents, not the encyclopedia. When everything is marked important, nothing is.

That is the same insight as Agent Skills arriving from the opposite side. Anthropic started from "how do we package one capability" and got tiers. OpenAI started from "our one big file stopped working" and got a link graph. Both landed on: entry point stays small, knowledge lives outside it, the agent follows references on demand.

Manus pushes it furthest. They treat "the file system as the ultimate context in Manus: unlimited in size, persistent by nature, and directly operable by the agent itself." Their compression rule is the one worth stealing: drop content, keep the pointer. As they put it, "the content of a web page can be dropped from the context as long as the URL is preserved." That only works if the pointer is meaningful on its own - which is exactly what a good wiki link is and what a bare filename is not.

Put the three together and the missing piece names itself. We have tiers. We have pointers. What we do not have is a spec for edges between skills, and for what an edge is supposed to tell the agent.

What a wiki skill adds#

A link on a wiki carries more than an address. It carries a claim about relevance: this is the thing you want next, and here is why. Strip that and you have a filesystem.

So the layer on top of Agent Skills is small, and it is strictly additive. Keep the three tiers exactly as they are. Every existing SKILL.md stays valid. Add three optional frontmatter fields, which is what we settled on internally:

links:
  - dashboard-ui
  - ship-pipeline
reach-for:
  phrases: ["add a metered endpoint", "charge credits for this"]
  globs: ["app/api/v1/**"]
  shapes: ["a new route spends credits and must refund on failure"]
loads:
  - path: lib/credits.ts
    when: you need the current price of an action before writing the deduction

links is the edge list - other skills by name, or load-bearing docs by path. The wiki part is that an unresolved name is not an error. A link to a skill that does not exist yet marks something worth writing, exactly like a red link on Wikipedia. A skill with fifteen links has said nothing.

reach-for is the condition for loading this skill at all, in three flavours: what a human says, what files are in play, and the task shape when neither of the first two catches it. The globs entry is the one that changes behaviour most, because it lets tooling be proactive - about to edit a matching path, load the skill first - rather than waiting to be asked.

loads is tier three made explicit and conditional. Each entry is a path plus a when clause justifying the read. An entry without a when is not worth writing, because the entire point is that the agent can decide not to open the file. This is the field that turns a skill from a document into a router: reading it teaches the agent the shape of the available context without paying for any of it.

Everything else falls out. If skills link, tier one no longer has to list all of them - it lists entry points, and the rest are reachable. The flat index stops growing linearly with the library. A skill can be small and specific, because the thing it does not cover is one hop away rather than something it has to duplicate. And you can measure the library structurally: orphan pages, dead links, hub pages that everything routes through. Wiki health metrics, applied to agent context.

The reader is an agent and the pages are executable. But the navigation model is Wikipedia.

What our own repo looks like#

We run 36 skills in .agents/skills/, and we are guilty of exactly the thing described above.

Measured this morning:

$ ls .agents/skills | wc -l
36
$ wc -l .agents/skills/*/SKILL.md | tail -1
    4542 total
$ grep -rl "\.agents/skills/" .agents/skills/*/SKILL.md | wc -l
7

Thirty-six skills, 4,542 lines of skill body, and 7 files that reference another skill's path. Twenty-nine skills are islands. There are 18 bundled files across the whole library, so tier three is barely used either. Almost all the knowledge sits in tier two, in pages that know nothing about each other.

We did get the entry point right, by accident of the same pressure OpenAI hit. Our CLAUDE.md is 71 lines and most of it is a "Load on demand" section that names skills and the phrasing that should trigger them. That is the 100-line table of contents pattern, arrived at independently.

We also built a skills atlas, generated from the SKILL.md frontmatter - what each skill does, what phrasing should load it, what it leaves behind. And pnpm explore prints a live index of the knowledge with freshness on each entry, because as its header says, a competitor map from three weeks ago and one from this morning look identical when you open them.

Both of those are hub pages. Neither is a graph. They are indexes that point down into skills; the skills still do not point sideways to each other. An agent that lands in feature-slice has no structural signal that dashboard-ui is the next page unless a human wrote a sentence saying so - and in 29 of 36 cases nobody did.

The product already has the edges the repo does not#

Here is the part that surprised us when we went looking. We ship a public skill library at /library/skills, and it has the graph.

Every entry in the library carries an optional relatedPaths list, and the detail page resolves those into named links. The resolver is explicit about the skill-to-skill case:

const related = (skill.relatedPaths ?? []).map((path) => {
  const skillMatch = path.startsWith("/library/skills/")
    ? getSkill(path.replace("/library/skills/", ""))
    : undefined;
  const libMatch = getLibrary(path.replace("/library/", ""));
  const label = skillMatch?.name ?? libMatch?.name ?? path;
  return { path, label };
});

A path pointing at another skill resolves to that skill's name. Of 35 first-party library skills, 28 carry relatedPaths, and 26 of those edges point at another skill rather than at a marketing page. So the published product is closer to a wiki than the .agents/skills/ directory our own agents read from, where 29 of 36 are islands.

That inversion is worth sitting with. We built the graph where humans browse, because a page with no links out is obviously bad UX, and we skipped it where agents read, because nothing visibly breaks when a SKILL.md is an island. The agent just quietly reasons from scratch instead of loading the page that already had the answer.

There is a second surface behind sign-in that gets the other half right. Our skill viewer at /dashboard/skill-viewer walks a skill the way an agent does - tier one is a lean index, tier two is the overview plus a file manifest, tier three opens one file - and it shows the running token cost as you go. Its own source comment states the intent: "The running context cost is the point." Progressive disclosure stops being a diagram and becomes a number that goes up when you open something.

So we ship the tiers in one place and the edges in another, and neither surface has both.

Direction, not shipped: courses as curated traversals. Our courses are already ordered walks. A Course holds Module entries with lessonIds, so the data shape is a path through a set of nodes. If skills are a graph, a learning path is a named walk through it: an author writes a goal, an entry point, and what counts as passing each stop, and the route between stops comes from the edges rather than from a hand-written curriculum. We have not built that. Courses today do not read from the skill library at all. I am describing where two data shapes point, not a feature you can use.

The general claim is the interesting one. A knowledge graph good enough for an agent to navigate is also good enough for a human to browse. The two audiences want different renderings of the same edges, not different edges. That is why the viewer matters beyond being a nice page - if a human can see that a three-hop traversal costs a specific number of tokens, they are looking at exactly the bill an agent pays.

What we are changing#

The near-term work is unglamorous and mostly mechanical:

1. Retrofit links, reach-for, and loads opportunistically. No migration - 36 skills is too many to do in one pass and the fields are optional by design. When you touch a skill and know its neighbours, name them. Three skills carry links as I write this.
2. Generate the atlas from the edges rather than the flat list, and emit machine-readable JSON alongside the markdown so the product can read the same graph the agents do.
3. Render unresolved edges rather than dropping them. A dangling link shown as a dimmed node is honest about a gap; a silently omitted one is not.
4. Lint the graph: orphans, dead links, and skills nothing ever routes to. An orphan is either mislinked or unnecessary, and both are worth knowing.
5. Trim tier one to entry points once the edges are reliable enough to carry the rest.

The measurable claim is simple: if the graph works, average context loaded per task goes down while the right skill still gets found. If context goes down and the right skill stops getting found, the graph is wrong.

The short version#

Agent Skills solved packaging. Progressive disclosure in three tiers is correct and you should use it. But three tiers describe how one skill unfolds, not how a library connects, and a library without links is a card catalog the agent has to read end to end.

Wikis solved this in 1995. Pages link, links carry meaning, readers navigate. The only new part is that the reader is an agent and the pages run.

Continue Reading#

• Skills Delivered Over MCP: Why Progressive Disclosure Is the Missing Piece of Both Standards - the transport side of the same argument
• Agent Skills Production Checklist - what a skill needs before you trust it in a real loop
• MCP Servers vs Agent Skills - when to reach for which
• One Endpoint, Progressive Disclosure - the index to manifest to item pattern in practice
• The Agent Context Reduction Pattern - cutting what the model carries per turn