⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v0.5.3

skill-atlas

daniellublinsky@daniellublinsky⭐ 24 stars· last commit 3mo ago· 0 open issues

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.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐ 24 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Skill Atlas

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

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

CI

The atlas, scope view


⚡ Install

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:

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

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

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

▶️ Run

CommandWhat it does
/skill-atlasBuild the graph, categorize what's new, render atlas.html. Run this once to set up.
/skill-atlas:edit-searchableMove plugins in and out of the searchable tier, interactively.
/skill-atlas:skill-searchFind 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.

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.


🎯 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:

TierIn context?Findable?Cost / session
🟢 enabledyesnatively~48 tokens each
🟣 searchablenovia skill-search0
⚫ disablednono0

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

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

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:

EdgeCaught
🔗references — a skill → its own bundled filesbroken when the file isn't there
💬mentions — a skill naming another skilldangling 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

  • 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/ — component guide, numbered 1–9

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/skill-atlas/SKILL.md8.7 KB8346352bc18cupstream ↗
    ---
    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).
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/daniellublinsky-skill-atlas-skills-skill-atlas.md

// REPO STATS

24 stars
0 open issues
Last commit: 3mo ago