# skill-atlas

Adopt this skill: https://proskills.md/skills/other/daniellublinsky-skill-atlas-skills-skill-atlas

Page: https://proskills.md/skills/other/daniellublinsky-skill-atlas-skills-skill-atlas
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/skill-atlas/SKILL.md
size: 8951
sha: 8346352bc18cc839279ade12a1b418730bf6cf5e
upstream: https://github.com/daniellublinsky/skill-atlas/blob/main/skills/skill-atlas/SKILL.md

````text
---
name: skill-atlas
description: Graph, categorize and visualize the installed Claude Code skill collection. Use when the user wants to map, audit or categorize their skills, move skills into the searchable tier, or asks which skills are broken, dangling, dead, disabled or duplicated — and for any mention of the skill atlas, skill graph or skill catalog.
allowed-tools: Bash(python3:*), Read
---

# skill-atlas

Builds a structural graph of every registered skill on this machine,
maintains a model-assigned category catalog over it, and renders both as a
self-contained HTML atlas. Discovery is manifest-driven
(installed_plugins.json → plugin.json → settings.json), so marketplace
catalogues, stale cached plugin versions and deprecated trees never pollute
the picture.

Everything is **fully project-local**: all artifacts and curated state live
in `./.claude/skill-atlas/` of the directory you run in (auto-created on
first build — any directory becomes an atlas scope by running this),
covering the machine's plugins + user skills + this directory's own
`.claude/skills/`. Different directories are independent worlds with
independent taxonomies.

The flow is **build → categorize → render → report**. All scripts live under
`${CLAUDE_PLUGIN_ROOT}/scripts/` and are Python 3 stdlib-only.

## 1. Build

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/build_graph.py"
```

Exit 1 is findings, not failure — carry on and report them (see exit codes
below). If it exits 2 naming categories.json or config.json violations: that
is hand-editable curated state — report each violation, offer to fix the
file (or install a corrected one via `categorize.py import <path>`), and
NEVER delete or regenerate it. Other exit-2 causes: diagnose from stderr and
`./.claude/skill-atlas/debug.log`.

## 2. Categorize

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/categorize.py" status
```

All catalog writes go through `categorize.py` — never edit categories.json
free-hand. On exit 3 the payload was rejected: stderr names every violation;
fix exactly what it names and retry.

Every successful `bootstrap` / `assign` / `confirm` / `add-category` call
refreshes graph.json and `catalog/` itself and ends with a `catalog:` summary
line — no rebuild afterwards. If a call instead warns that the derived
refresh failed, run `build_graph.py` once before rendering. **The run's final
`catalog:` line must show 0 uncategorized.** Then branch on `bootstrapped`:

### `bootstrapped: false` → bootstrap now, autonomously (no approval step)

The status output already includes every skill's id and description
(`skills`). Draft 8–12 categories, each with a one-line description,
following these rules:

- describe the task shape in user-intent terms, not implementation terms;
- when two categories could be confused, let each description name its side
  of the boundary;
- a product gets its own category only when it dominates the collection;
- do NOT enumerate product/tool words in the description — the build derives
  token lists from membership automatically.

Assign EVERY skill to one or more categories, ordered (first entry is its
display home) — full coverage is mandatory and the CLI rejects a bootstrap
that leaves any skill unassigned; if nothing fits a skill, the taxonomy is
missing a category, so create it. Assignment rules:

- **Multi-home across confusable boundaries.** Search reads ONE shard,
  picked from the one-line descriptions, so a skill filed on only one side
  of a confusable pair is invisible to every task phrased in the twin's
  terms. Assign each skill to EVERY category a realistic task needing it
  would plausibly route to, home first — a debugging methodology also
  belongs in testing ("my tests are failing" is a debugging task phrased
  as testing); a design-interrogation skill also belongs in discovery.
  The boundary clauses written into the descriptions mark exactly the
  pairs to sweep: a boundary worth disclaiming in prose is a boundary
  whose straddling skills belong on both sides.
- A second home needs a realistic task phrasing, not a conceptual
  relation — when most skills sit in 3+ categories, the shards bloat back
  toward the flat catalog this system exists to avoid.
- A platform-locked skill (usable only on one vendor's stack) stays in
  its platform category — never file it into a generic category its
  wording happens to match.

Then write it in one call:

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/categorize.py" bootstrap <<'EOF'
{"taxonomy": [{"name": "testing", "description": "writing, running and structuring tests"}],
 "assignments": {"some-plugin:tdd": ["testing"]}}
EOF
```

### `bootstrapped: true` → incremental

The taxonomy is frozen — assign into it, never re-label unchanged skills:

- For every id in `uncategorized`: match its description against the frozen
  taxonomy's one-line descriptions; batch all fits into ONE
  `categorize.py assign` call (same stdin shape as bootstrap, without
  "taxonomy"). The bootstrap assignment rules apply here too: multi-home
  the skill into every category a realistic task would route to, not just
  its best single fit.
- If nothing fits a skill: add a category yourself —
  `categorize.py add-category <name> "<one-line description>"`, then assign —
  and call the addition out prominently in the report.
- For every id in `stale`: re-read its current description. Labels still
  right → batch into `categorize.py confirm <id> <id> …`. Wrong → include in
  the `assign` payload with new labels.
- **A run must end with zero uncategorized skills** — uncategorized is a
  transitional state between runs, never an acceptable end state. If the
  last `catalog:` line still reports uncategorized > 0, something was
  missed — go back and assign it.
- **Every registered skill in this scope's graph is categorized** —
  plugins, user skills, and this directory's own project skills alike
  (including collision-renamed ids like `name@user` / `name@project`).

## 3. Render

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/render.py"
```

## 4. Report

The summary line per view (skills / enabled / files / edges / uncategorized /
stale); every dangling or broken-reference finding by name (these are real
defects); what categorization did this run — newly assigned
(id → categories), stale confirmed vs moved, any category you added; and the
atlas path (`./.claude/skill-atlas/atlas.html`). The first build in a repo
drops a `.gitignore` inside `.claude/skill-atlas/` covering the derived files
(`graph.json`, `atlas.html`, `catalog/`, `graph.dirty`, `debug.log`) — commit
it together with `categories.json` (this project's curated categorization)
and `config.json`. Caveat: a repo that ignores `.claude/` wholesale swallows
that nested file; it needs negation rules before `categories.json` can be
committed.

## Interpreting exit codes

- `0` — built, nothing dangling.
- `1` — built AND at least one defect: a broken bundled-file reference, or a
  mention of an unregistered/disabled skill. **Report each finding** — these
  are real defects. Uncategorized/stale counts are NOT defects, only TODO
  states for categorization.
- `2` — build failed. If stderr names categories.json/config.json
  violations, that is curated state failing loud: report the violations,
  offer to fix the file or `categorize.py import <path>` a corrected one.
  Otherwise check stderr and `./.claude/skill-atlas/debug.log`.
- `3` — (`categorize.py` writes only) the payload was rejected; stderr names
  every violation. Fix and retry.

## Contract

- Reads only skill files and manifests. It never reads session transcripts
  and records no usage data.
- `graph.json`, `atlas.html` and `catalog/` are derived caches — safe to
  delete, always rebuildable.
- **`categories.json` is curated state — the one exception to
  rebuild-never-repair.** Never delete or regenerate it; regeneration
  discards the frozen taxonomy and every assignment. Each scope carries
  its own complete file (taxonomy + assignments) in
  `./.claude/skill-atlas/` — commit it with the repo. `config.json`
  (the searchable-plugins opt-in) is per-scope user config.
- The taxonomy freezes at bootstrap. Renaming or merging categories is a
  hand-edit of categories.json (taxonomy AND assignments) validated via
  `categorize.py import`, followed by a rebuild.
- This skill, the build and the hooks never write Claude Code's own config —
  recommend enabling a plugin, never flip `enabledPlugins` yourself. The one
  exception is the `/skill-atlas:edit-searchable` command, where disabling a
  plugin IS the user's explicit selection and is confirmed before it runs;
  automated paths stay read-only on settings.
- The atlas shows structure only (what is loadable, what is broken). Do NOT
  tell the user which skills are unused or "dead" — the tool does not
  measure usage, deliberately (DESIGN §6).
````

## File: README.md
upstream: https://github.com/daniellublinsky/skill-atlas/blob/main/README.md

````text
<div align="center">

<img src="assets/logo.svg" width="76" alt="Skill Atlas">

# Skill Atlas

<h3>🔎 Query your whole skill collection at ~85% fewer tokens</h3>

**A third tier for Claude Code skills — dormant, zero tokens, still findable.**
Search a graph of your collection instead of preloading it.

<sub>53 skills, 6 kept enabled: **2,544 → 338 tokens per session (−86.7%)**. The other
47 cost nothing until asked for.</sub>

[![CI](https://github.com/danielLublinsky/Skill-Atlas/actions/workflows/ci.yml/badge.svg)](https://github.com/danielLublinsky/Skill-Atlas/actions/workflows/ci.yml)

</div>

![The atlas, scope view](assets/atlas-scope.png)

---

## ⚡ Install

```bash
claude plugin marketplace add danielLublinsky/Skill-Atlas
claude plugin install skill-atlas@skill-atlas
```

Python 3 only — no dependencies, no network (d3 is vendored).

**Update.** New versions arrive on their own — Claude Code refreshes marketplaces
periodically and picks up the new version, applying it on the next restart. To
pull one immediately:

```bash
claude plugin marketplace update skill-atlas
claude plugin update skill-atlas@skill-atlas
```

Then restart Claude Code — the update is staged until you do.

<details>
<summary>From a local clone (for hacking on it)</summary>

```bash
git clone https://github.com/danielLublinsky/Skill-Atlas.git
claude plugin marketplace add ./Skill-Atlas
claude plugin install skill-atlas@skill-atlas
```

</details>

## ▶️ Run

| Command | What it does |
| --- | --- |
| **`/skill-atlas`** | Build the graph, categorize what's new, render `atlas.html`. **Run this once to set up.** |
| **`/skill-atlas:edit-searchable`** | Move plugins in and out of the searchable tier, interactively. |
| **`/skill-atlas:skill-search`** | Find the right skill for a task across the whole library, dormant tier included. |
| *(automatic)* | A SessionStart hook keeps everything fresh after that. |

Then open `./.claude/skill-atlas/atlas.html` in a browser, and just ask for a
task — the search runs itself, names the skill it picked in one line, and gets
on with the work.

<details>
<summary>Without the plugin (Makefile)</summary>

```bash
make build    # graph.json + catalog/ from your live manifests
make render   # atlas.html
make check    # CI gate: exit 1 on any broken reference or dangling mention
make test     # unit suite against fixtures — never touches the real ~/.claude
make release  # bump both manifests, validate, test — never commits or pushes
```

The plugin cache is keyed by version, so a push without a bump ships no code to
anyone already installed. `make release` (or `BUMP=minor`, `VERSION=1.0.0`) is
what makes a change land.

</details>

---

## 🎯 The problem

Claude Code injects **every** enabled skill's description into **every** session —
~48 tokens each. At 100+ skills that's thousands of tokens you pay for constantly,
and near-duplicates quietly compete for the model's attention.

Disabling fixes the cost and loses the skill. So Skill Atlas adds a tier in between:

| Tier | In context? | Findable? | Cost / session |
| --- | --- | --- | --- |
| 🟢 **enabled** | yes | natively | ~48 tokens each |
| 🟣 **searchable** | **no** | via `skill-search` | **0** |
| ⚫ **disabled** | no | no | 0 |

A **searchable** skill is dormant — its description never enters your context, but
it stays discoverable on demand. All that advertises the whole dormant tier is one
~50-token line at session start.

## 🔍 Search reads two files, not the catalog

```mermaid
flowchart LR
    A(["🧭 a task arrives<br/><i>“resolve this merge conflict”</i>"])

    subgraph R1["1️⃣ read the index · ~1.6k tok"]
        I["<b>_index.md</b> — 14 lines<br/><i>name · count · what it covers · member tokens</i>"]
    end

    subgraph R2["2️⃣ read one shard · ~0.6k tok"]
        S["<b>version-control.md</b><br/>using-git-worktrees<br/>resolving-merge-conflicts ← hit"]
    end

    X["the other 13 shards<br/><i>~10k tok · never opened</i>"]

    A --> I
    I -- "pick ONE category" --> S
    I -. skipped .-> X
    S --> E["🟢 <b>enabled</b><br/><i>invoke natively</i>"]
    S --> F["🟣 <b>searchable</b><br/><i>read its path,<br/>follow as instructions</i>"]

    classDef file stroke:#8a8578,stroke-width:1.5px
    classDef ghost fill:transparent,stroke:#8a8578,stroke-width:1.5px
    classDef hit fill:#1baf7a26,stroke:#1baf7a,stroke-width:2px
    classDef dormant fill:#8a5cd626,stroke:#8a5cd6,stroke-width:2px
    classDef muted fill:transparent,stroke:#8a8578,stroke-width:1px,stroke-dasharray:4 3
    class I,S file
    class A ghost
    class E hit
    class F dormant
    class X muted
    style R1 fill:#3987e514,stroke:#3987e5,stroke-width:1.5px
    style R2 fill:#3987e514,stroke:#3987e5,stroke-width:1.5px
```

**A search costs ~2.4k tokens** — the index (1.6k), one shard (~0.6k) and the
search skill itself (0.4k) — **and you pay it only when a search happens.** The
alternative it replaces is every dormant description sitting in context from
session start, billed whether you search or not. The arbitrage is real when
searches are occasional; it is not free, and the numbers above are measured
rather than estimated.

One shard is the norm. A second is opened only when the entry you found lists a
category you haven't read — the catalog pointing, not the model guessing — and
never a third. Counts overlap on purpose, so the pick doesn't have to land on
*the* right bucket, only *a* right one. Tier-off skills are excluded when shards
are written, so a disabled plugin can never return through a side door. The
result is announced in one line before the work continues: search is a lookup
inside a task, not a deliverable.

**The model categorizes once.** The first run drafts 8–12 categories named for
*user-intent task shapes*, not products, then freezes the taxonomy. Later runs only
file new skills and re-confirm the ones whose description changed — each assignment
carries a hash of the description it was made against.

## 🕸️ The graph

![The atlas, category view](assets/atlas-categories.png)

Discovery is **manifest-driven** — `installed_plugins.json` → each `plugin.json` →
settings — so marketplace catalogues and stale cached versions never pollute the
picture. (The naive "every directory with a SKILL.md" count over-counts by ~60% on a
real machine: `build_graph.py --naive-count`.)

Skills are nodes. The edges are the interesting part:

| | Edge | Caught |
| --- | --- | --- |
| 🔗 | **references** — a skill → its own bundled files | **broken** when the file isn't there |
| 💬 | **mentions** — a skill naming another skill | **dangling** when the target is `disabled`, `unregistered` or `absent` |

Mention matching is deliberately strict — only backticked, `skills/<name>`, or
unambiguous hyphenated names, code fences stripped first. Loose matching produced 91
edges on a 41-skill collection, almost all of them ordinary English words. You also
get duplicate names, orphans, and an exit code to gate CI on.

`atlas.html` is self-contained and opens from `file://` with zero network requests:
**scope** (origin, state, breakage in red) and **categories** (hub-and-spoke — solid
edge to the home category, dashed to the rest; search `cat:<name>` to isolate).

## 🛠️ Building and debugging skills

![Debugging a skill in the atlas](assets/atlas-markdown.png)

- **What's really registered** — discovery is manifest-driven, so unregistered copies
  and stale plugin caches surface as their own nodes instead of quietly counting.
- **Broken bundles** — a `references` edge whose file isn't on disk draws red, so a
  typo'd `references/foo.md` is visible without opening anything.
- **Why it didn't trigger** — tier is the node's fill (enabled · searchable ·
  disabled), and duplicate names are called out in the footer with both nodes drawn.
- **Read it in place** — pin any skill or bundled file and hit **open markdown** to
  read the source in a popup without leaving the graph.

## 📚 Docs

[**docs/**](docs/) — component guide, numbered 1–9
````
