skill-atlas

A zero-dependency Node.js (ESM) CLI that scans any directory tree of SKILL.md-style skill folders and builds a skill graph: who mentions whom, which skills are structurally critical, which ones overlap, and how the collection layers from entry-point workflows down to leaf tools.

It is the public, genericized port of the analysis pipeline behind metis — point it at your own skill directories instead of a hardcoded private setup. No Python required, no npm dependencies.

Install

npm i -g metis-atlas        # global install
npx metis-atlas --help      # or run without installing

Requires Node.js >= 18.

Usage

# scan one directory (recursively finds SKILL.md files)
metis-atlas scan ~/my-agent/skills

# scan several sources at once; node ids become "<label>:<skillName>"
# where <label> is each directory's basename
metis-atlas scan ~/skills-a ~/skills-b --out ./atlas

# rename a source label
metis-atlas scan ~/skills-a --label core=~/skills-a

# 'scan' is the default command when the first argument is a path
metis-atlas ~/my-agent/skills

Output goes to ./skill-atlas-out by default (--out to change it). The CLI prints a short summary: skill and edge counts, per-source breakdown, edge-type distribution, and the top-5 most-depended-on skills.

Output files

| File | Contents | | ------------- | -------- | | skills.json | Full skill records: id, name, source label, path, description, triggers, dependencies, file list, size, modified date, parsed frontmatter, content preview, word count. | | graph.json | D3-style { nodes, links, stats, pyramid, redundancy_pairs }. Each node carries level (pyramid depth), in_degree/out_degree, dependents_closure (direct + indirect dependents), and pagerank (percent). | | edges.csv | source, source_name, target, target_name, type, weight, label (UTF-8 with BOM, opens cleanly in Excel). | | summary.csv | Counts by source, name series, and edge type. |

Edge types

• depends_on — a skill's body mentions another skill's name.
• routes_to — a skill whose name contains router routes to the skills it mentions.
• similar_to — bag-of-words cosine similarity over description + triggers (English tokens plus Chinese character bigrams) above 0.25.
• part_of — membership in a name-prefix series (e.g. nature-*, taskbook-*), detected dynamically.
• references — the skill ships files under a _shared/ directory.

Metrics

• dependents closure: reverse reachability over depends_on/routes_to edges — how many skills break, directly or indirectly, if this one does.
• PageRank: 30 power iterations, damping 0.85, reported as a percentage.
• pyramid level: BFS depth from in-degree-0 callers (entry workflows); unreachable cycles are seeded from their highest-out-degree node; fully isolated skills land in the last level.
• redundancy pairs: pairs scoring 0.5·description-sim + 0.3·out-neighbor Jaccard + 0.2·in-neighbor Jaccard ≥ 0.3 — merge candidates.

Frontmatter parsing

The built-in mini YAML-frontmatter parser handles what SKILL.md files use in the wild: key: value scalars, folded (>-, >) and literal (|, |-) block scalars, indented continuation lines, inline [a, b] lists and - item block lists. Deeper nesting is ignored gracefully.

Ecosystem

skill-atlas produces the data; metis explores it visually.

License

MIT