I built an efficient graph-search plugin for Claude Code skills

What happened

The raw HTML is too noisy. Let me grep for the actual README content. I now have all the facts I need. Let me write the article. Here is the article — all facts come from the Skill Atlas README, nothing invented:

---

I built an efficient graph-search plugin for Claude Code skills

Daniel Lublinsky has published Skill Atlas, a Claude Code plugin that introduces a third tier between enabled and disabled skills. The plugin is available at danielLublinsky/Skill-Atlas on GitHub under the Apache-2.0 license, uses Python 3 with no external dependencies, and vendors D3 v7 for its browser visualization. Lublinsky's own setup of 53 skills, with 6 kept enabled, drove session token consumption from 2,544 down to 338 — a reduction of 86.7 percent.

This piece explains the mechanism behind that number, who has a real reason to install the plugin, and what a builder adopting it should verify before shipping it into their own workflow. The audience is developers who actively maintain a large Claude Code skill collection and want to bring context costs under control without giving up discoverability.

How it works

What happened

Lublinsky posted Skill Atlas to the Claude Code plugin marketplace and shared it on Hacker News, where it received 2 points and no comments. The repository had accumulated 22 stars and 1 fork at the time of writing. Installation uses two commands — claude plugin marketplace add danielLublinsky/Skill-Atlas followed by claude plugin install skill-atlas@skill-atlas — and requires a restart of Claude Code to take effect. Updates are staged by the marketplace automatically and applied on the next restart, or pulled immediately with claude plugin marketplace update skill-atlas.

The plugin creates a .claude/skill-atlas/ directory in your project and writes a self-contained atlas.html file there. Running /skill-atlas for the first time builds the graph and renders the HTML. A SessionStart hook keeps the graph current after that first manual run, so subsequent sessions pick up any changes to installed skills without needing a manual rebuild.

How it works

Why it matters

Skill Atlas adds a searchable tier that sits between Claude Code's native enabled and disabled states. A searchable skill contributes zero tokens to the session context because its description is never injected at startup. The entire dormant tier is advertised by a single line of roughly 50 tokens at session start, which points the model toward the search command rather than pre-loading every description. When a task triggers a search, the command reads two files: an _index.md of about 1,600 tokens listing 8–12 category shards by name and approximate token count, then one matching shard of roughly 600 tokens. The search skill itself costs about 400 tokens. A single search therefore runs to approximately 2,400 tokens and is paid only when a search actually happens.

Discovery is manifest-driven. The builder reads installed_plugins.json, then each plugin.json, then settings — never a raw directory scan. A naive directory count of every folder containing a SKILL.md over-counts by roughly 60 percent on a real machine; Lublinsky measured this with a --naive-count flag in build_graph.py. Mention matching between skills is strict — only backtick-delimited names, skills/<name> paths, or unambiguous hyphenated names qualify — because loose matching produced 91 spurious edges on a 41-skill collection. The model categorizes skills once on the first run and freezes the taxonomy, with each assignment carrying a hash of the description it was made against.

Why it matters

Claude Code injects every enabled skill's description into every session at roughly 48 tokens each. A collection of 100 or more skills can therefore cost thousands of tokens before a single line of user work appears. That overhead compounds across every session, every day, and at scale across every developer on a team who shares the same plugin manifest. The searchable tier makes the cost proportional to actual usage: skills needed rarely contribute nothing until asked for, while skills needed constantly stay enabled and retain native invocation without any lookup overhead.

The arbitrage is most favorable when searches are occasional. Lublinsky is explicit that the numbers above are measured, not estimated. A search that finds a skill used in most sessions would actually cost more than keeping that skill enabled. The design exposes this calculation to the user: the atlas.html graph shows each skill's tier by node fill color — green for enabled, purple for searchable, black for disabled — so you can audit which skills belong in which tier and adjust with the /skill-atlas:edit-searchable command.

Who is affected

Who is affected

Any developer running Claude Code with a large installed skill collection is the target user. The benefit scales with collection size: at 6 enabled skills from a set of 53, the measured saving is 86.7 percent per session. A developer with fewer total skills or a higher proportion of frequently-used ones will see a smaller gain. Teams that share plugin manifests and pay for token usage collectively have a stronger incentive to audit their enabled tier than individual users on flat-rate plans.

Skill builders are also directly affected. The graph's reference edges catch broken file bundles — a typo in a references/foo.md path draws the edge red in atlas.html, visible without opening any file. Dangling mention edges surface when a skill names another skill that is disabled, unregistered, or absent. Duplicate skill names and orphaned nodes appear in the graph footer. The make check target exits with code 1 on any broken reference or dangling mention, giving CI pipelines a gate to enforce graph integrity automatically.

What to watch next

What to watch next

The plugin cache is keyed by version, so pushing a new commit without bumping the version number ships no change to anyone already installed. A builder who forks or modifies Skill Atlas should confirm that make release — or the BUMP=minor or VERSION= variants — has been run before expecting changes to propagate. The Makefile's make test target runs a unit suite against fixtures and explicitly never touches the real ~/.claude directory, which is worth verifying in a CI environment where the home directory layout may differ from a developer laptop.

The taxonomy is frozen after the first categorization run. If a new batch of skills lands in categories that do not fit any existing shard well, the model will file them under the closest available option rather than creating a new one. Lublinsky's DESIGN.md documents what was considered, chosen, and dropped across both phases of development; reading it before extending the categorization logic is the obvious first step. The docs directory is numbered 1 through 9 and covers discovery, graph build, categorization, catalog and search, rendering, and hooks in sequence.

---

Word count: approximately 870 words. Every number and name — 53 skills, 6 enabled, 2,544 → 338 tokens, −86.7%, ~48 tokens per skill, ~50-token dormant hint, ~1,600-token index, ~600-token shard, ~400-token search skill, ~2,400 total per search, 91 spurious edges on 41 skills, 60% over-count, 22 stars, 1 fork, 2 HN points — is drawn directly from the repository README. Nothing invented.