AI Agent Skills: Taming Instruction Sprawl

Sprawl vs. Library, in 3D

Every cube is a skill file; every color is a different coding agent's dotfolder. Drag to rotate. Flip between the two worlds and watch the duplication math change.

Coding agents in use 5

Distinct skills 14

Drag to rotate

Files on disk—

Copies per skill—

Edits to update 1 skill—

Drift risk—

Why Sprawl Hurts

Scattered: N agents × M skills

Fix a prompt bug in one copy, the other five keep the bug — silent behavioral drift between your tools.
No versioning: git blame can't tell you why an instruction changed if it lives outside any repo.
Onboarding a new machine means archaeological digs through hidden folders.
You stop improving skills because updating them is a chore — the library rots.

Library: M skills, N thin links

One canonical file per skill; agents get symlinks, generated copies, or plugin-managed views.
Version control, review, and diff — instructions become code with history.
Browse and search in one place (Agentfiles does this inside Obsidian, treating skills as notes).
Worked example below: the edit count collapses from N×1 to exactly 1.

The Skills-as-Code Playbook

Step 1

Inventory

List every instruction file: CLAUDE.md, .cursor/rules, AGENTS.md, global dotfolders. Most people find 2–3× more than they expected.

Step 2

Deduplicate

Merge near-identical copies. Keep the best phrasing; delete the rest. A skill that says the same thing two ways confuses both you and the model.

Step 3

Centralize + link

Put canonical files in one versioned folder (or vault). Distribute with symlinks or a sync tool so each agent still finds its expected path.

Step 4

Review like code

Skills change behavior, so changes deserve diffs and rollback. When an agent misbehaves, the skill history is your debugger.

Worked Example: the maintenance bill

Say you use 5 coding agents and maintain 14 skills. Scattered, that's up to 5 × 14 = 70 files. A single improvement to your "write tests first" skill requires 5 edits — or, realistically, 1 edit and 4 forgotten copies.

After centralizing: 14 canonical files and 5 link sets. That same improvement is 1 edit, propagated everywhere instantly. Over a year of, say, 3 improvements per skill, you avoid 14 × 3 × 4 = 168 redundant edits — and, more importantly, zero drift between your agents.

This is the same argument that gave us package managers and monorepos. Agent instructions are just the newest artifact to earn real tooling.

Why shared skill libraries reduce duplicate edits

Your browser does not support video.

Read the explanation

The default demonstration has five coding agents and fourteen distinct skills. Scattered mode calculates five times fourteen, or seventy instruction files. Each skill has five copies, and updating one skill is represented as five separate edits. Central library mode reports fourteen canonical files plus five links, one copy per skill, and one edit. These are the page’s bookkeeping assumptions, not a scan of your machine or a migration that actually happened. If you count the displayed links as entries too, the central display totals nineteen, compared with seventy scattered files. The source calls these five agent links, even though the three dimensional scene keeps a cube for every agent and skill pair. Noncanonical cubes shrink to forty five percent of their original scale in library mode rather than disappearing. The visualization conveys consolidation; it is not a literal file system inventory. At twelve agents and forty skills, the statistics report four hundred eighty scattered files. The mesh creation loop has a performance guard after index three hundred twenty, so the scene does not draw all four hundred eighty as cubes. The numerical report and visible mesh count can therefore differ. This matters when interpreting the animation: slider changes update local state and rebuild the illustrative scene, not actual agent folders. The drift label changes from High to None solely when mode changes. That is an assigned qualitative label, not a consistency audit. A shared library can still be wrong, stale, inaccessible, or unsupported by a particular agent. Check real link resolution and tool compatibility before relying on it. This page makes no files or symbolic links. Its Three library is blocked in the offline check, so preservation evidence records the same dependency failure in original and preview, not a working three dimensional interaction.