From multi-agent chaos
to a harness of predictable agents and skills.

Reclaim tokens (and money!), save time, and make your Markdowns deterministic. Detects incoherence, verbosity, redundancy, bloated skills, and much more.
The harness you designed, finally visible and testable: deterministic and probabilistic analysis and fixes, on one map.

See it live
~/.claude/skills
13 nodes · 15 links · 3 collisions · 1 orphan
Skill
Agent
MCP
Markdown
Command
Orphan
oauth-flow deploy ship release reviewer planner mcp:github mcp:fs fs/read git/log legacy.md read-pdf CLAUDE.md

Your whole agent harness,
on a single screen!

Quickstart

Tutorial in 5 lines

Install, create an empty folder, and open your agent (Claude Code, Codex, etc). Let your agent walk you through the whole flow, live in your console and browser.

bash
npm i -g @skill-map/cli mkdir try-skill-map && cd try-skill-map sm tutorial# installs the tutorial skill claude# opens Claude Code here

Then, inside Claude, type:

Ecosystem

Plugins: Six kinds.
Infinite extensions.

Six ways to extend this tool. Your plugin, your company's, the community's, all run against the same kernel.

+ your plugin KERNEL map engine Provider BUILT-IN Extractor BUILT-IN Analyzer BUILT-IN Action Formatter BUILT-IN Hook BUILT-IN
plugin kind

Provider

Defines an agent (Claude, Codex, etc)

Declares the file kinds an agent exposes (skill / agent / command for Claude), where its content lives on disk, the frontmatter schema each kind follows, and how the UI renders it (label, color, icon). The Claude provider ships built-in; write one for Codex, Copilot, or your own runner.

// claude/provider.ts (kinds live in claude/kinds/<name>/)
// id and kind come from the folder, you never write them.
export default {
  version: '0.1.0',
  description: 'Claude Code agents, commands, and skills',
  presentation: { label: 'Claude', color: '#cc785c' },
  detect: { markers: ['.claude'] },
  read: { extensions: ['.md'], parser: 'frontmatter-yaml' },
  classify: (path, fm) => /* 'agent' | 'command' | 'skill' | null */,
};
plugin kind

Extractor

Extracts data from a node

Each file is a node; an Extractor turns it into data. Links to other nodes, attributes that enrich the node, or signals you stash in your own KV store. Pure code, deterministic, runs in milliseconds inside `sm scan`, no LLM, no cost.

// claude/extractors/slash/index.ts
export default {
  version: '0.1.0',
  description: 'Link /command invocations to their target',
  scope: 'body',
  extract(ctx) {
    for (const [, cmd] of ctx.body.matchAll(SLASH_RE))
      ctx.emitLink({
        source: ctx.node.path, target: cmd,
        kind: 'invokes', confidence: 0.8,
      });
  },
};
plugin kind

Analyzer

Finds problems in the map

Looks at the whole map and spots problems: trigger collisions, orphans, dead dependencies, broken references. Write an analyzer, run it on any project, or publish it for others to use.

// example/analyzers/trigger-collisions/index.ts
export default {
  version: '0.1.0',
  description: 'Flags two nodes that share one trigger',
  evaluate(ctx) {
    return [...byTrigger(ctx.nodes)]
      .filter(([, ns]) => ns.length > 1)
      .map(([trigger, ns]) => ({
        severity: 'warn',
        nodeIds: ns.map((n) => n.path),
        message: `"${trigger}" claimed by ${ns.length} nodes`,
      }));
  },
};
plugin kind

Action

Improves your agents and skills automatically

Actions are the only plugin kind that touches disk. Deterministic mode: straight code (rename a trigger, tweak frontmatter). Probabilistic: a prompt run by the LLM (regenerate a summary, rewrite text).

// core/actions/rename-trigger/index.ts
export default {
  version: '0.1.0',
  description: 'Rename a node trigger',
  mode: 'deterministic',
  invoke(input, ctx) {
    return {
      report: { ok: true, trigger: input.trigger },
      writes: [{ kind: 'sidecar', path: ctx.nodeAbsolutePath,
        changes: { annotations: { trigger: input.trigger } } }],
    };
  },
};
plugin kind

Formatter

Exports the map to other formats

The map lives in memory; a Formatter ships it out. ASCII for terminal, Mermaid for your README, DOT for Graphviz, JSON for your pipeline. Built-ins cover the common cases; write your own for the rest.

// core/formatters/mermaid/index.ts
export default {
  version: '0.1.0',
  description: 'Render the graph as Mermaid',
  format(ctx) {
    return 'graph LR\n' + ctx.links
      .map((l) => `  ${l.source} --> ${l.target}`).join('\n');
  },
};
plugin kind

Hook

Notifies and integrates with other tools

When something happens in skill-map (scan finished, action executed, job failed), a Hook reacts. Send it to Slack, fire a webhook, gate a spawn before it starts. There are ten events you can subscribe to.

// integrations/hooks/slack-on-failure/index.ts
export default {
  version: '0.1.0',
  description: 'Post to Slack when a job fails',
  triggers: ['job.failed'],
  on(ctx) {
    slack.post('#alerts', ctx.jobResult);
  },
};

A plugin is ~30 lines of code.

sm plugins list
Read the docs
Features

Deterministic. Semantic. Same map.

Deterministic & probabilistic, side by side

Static analysis runs in milliseconds, offline. Then queue a semantic job and your own AI agent reads a node for meaning: redundancy, a trigger that will misfire, vague or contradictory instructions, even content trying to manipulate the agent. One map, two angles.

Token weight per node

Per-node byte and token counts. Find the bloated skill that's eating your context window.

Use cases

Built for people who live in Markdown.

No promises, no magic. Just a map over the files you already have.

For authors

Optimize before you publish.

Before you publish a skill, see it in context: what it duplicates elsewhere, where it repeats itself, how many tokens it costs. Tighten it while it is still yours to change.

For AI architects & platform teams

See the harness you designed, not the one that drifted.

Point it at your project, or the roots you hand it, and the design you intended lines up with what is actually on disk: divergent copies of a skill, an agent nothing references, a rule that quietly rotted.

For agent debuggers

Watch what your agent actually ran.

Leave the map open and each node lights up the moment your runtime invokes it: the skill it loaded, the agent it delegated to, the file it read. Open a delegation edge and read the exact prompt and reply. No log tailing.

For tool builders

Build on top of the map.

Every operation has a CLI verb, a JSON output, and a plugin hook, and your agent can drive the whole thing over MCP. Wire skill-map into your CI, your dashboard, or your LLM workflow, without forking the kernel.

Stop reading dirs.
Start reading maps.

See your entire agent harness at a glance. Time to design it right!

View on GitHub

Roadmap.
290+ decisions documented, six phases, one 1.0. No shortcuts.

Cookies & analytics

We use Google Analytics to learn which parts of the site help. No personal info, no tracking across other sites.