🧭 skill-compass

Point your project at the right Claude Code skills.

A Claude Code hook that reads your repo, works out what it's actually made of — UI, API, database, auth, LLM, infra — and tells Claude which skills to load before it writes a single line.

Website · Install · How it works · Configure

English · Русский

---

Why

A loaded Claude Code has a huge skill library — design, API, database, security, every language stack. The right skill for the task is in there. The problem is remembering to reach for it.

skill-compass removes the remembering. On every prompt it inspects the project in front of Claude and hands over a short, accurate list of the skills that match — so the design skill fires on UI work, the security skill fires on auth work, the migration skill fires on schema work, automatically.

How it works

Match → Inject, in single-digit milliseconds. It reads three signals:

1. Project files — the project root one level deep: dependency manifests, folders, file extensions. Mapped to stacks (Rust, Next.js, Django…) and cross-cutting directions (UI, API, DB, auth, LLM, infra).
2. Your prompt — matches project/topic keywords in what you type, so it fires even from a junk-drawer cwd (a Desktop full of projects). Say "find the clickhouse migration and fix it" and it routes to the right skills before a file is opened.
3. What the AI finds mid-turn — a PostToolUse hook watches Bash/Grep/Glob/Read/Task results; the moment a tool surfaces a known keyword (a path, a dependency, a match line) it injects the matching skills right next to that tool result.

Matched skills are injected as a compact note — shown once per signal-set per session, re-shown when the detected set changes. With no manifest, no prompt keyword and no tool finding, the compass stays silent instead of guessing.

The bearings it reads

Bearing	Triggers	Skills it routes
UI	react, vue, next, .tsx, components/	frontend-design, make-interfaces-feel-better
API	express, fastapi, app/api/, routes/	api-design, backend-patterns
DB	prisma, drizzle, sqlalchemy, *.sql	database-migrations, postgres-patterns
AUTH	next-auth, stripe, jwt, auth/	security-review
LLM	anthropic, openai, langchain	claude-api, agent-harness-construction
INFRA	Dockerfile, compose.yml, k8s/	docker-patterns, deployment-patterns

Plus 16 language stacks (Rust, Go, Python, TypeScript, Next.js, React, Vue, Java, Spring Boot, Kotlin, Swift, Dart/Flutter, PHP/Laravel, C#, C/C++) and a keywords block that routes by project/topic name (SEO, a11y, research, video, Claude API, homelab, …) straight from your prompt or a mid-turn tool finding. Every row lives in directions.json.

Install

Needs Node.js and Claude Code.

git clone https://github.com/by-sonic/skill-compass
node skill-compass/install.js

The installer copies two files to ~/.claude/skill-compass/ and registers two hooks — UserPromptSubmit (prompt + project) and PostToolUse (mid-turn tool findings). Restart Claude Code to load them.

Manual install

Copy compass.js and directions.json to ~/.claude/skill-compass/, then add to ~/.claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [
      { "matcher": "", "hooks": [
        { "type": "command", "command": "node \"~/.claude/skill-compass/compass.js\"" }
      ]}
    ],
    "PostToolUse": [
      { "matcher": "Bash|Grep|Glob|Read|Task", "hooks": [
        { "type": "command", "command": "node \"~/.claude/skill-compass/compass.js\" --post" }
      ]}
    ]
  }
}

Install as a skill

skill-compass also ships as an Agent Skill so Claude can install and operate the hook for you on request. Point Claude Code at skill/skill-compass/ (copy it into your project's .claude/skills/ or your global ~/.claude/skills/). Then just ask:

"Install skill-compass" · "show my directions.json" · "add a mobile bearing" · "run the compass self-test"

The skill knows how to run install.js, edit directions.json, and verify with --self-test.

Configure

Open directions.json. Add a stack or a direction by appending one object.

{
  "id": "mobile",
  "name": "Mobile",
  "deps": ["react-native", "expo"],   // matched in dependency manifests
  "paths": ["ios", "android"],         // folder/file names at the root level
  "ext": [".kt", ".swift"],            // file extensions present
  "skills": ["ecc:react-native-patterns"]
}

Any of deps / paths / ext matching triggers the direction. skills are plain strings — point a bearing at whatever skill names you have installed.

Commands

node compass.js --self-test    # run detection against fixture projects
node compass.js --force        # ignore the once-per-session guard
SKILL_COMPASS=off              # env var — disable without uninstalling
node install.js --uninstall    # remove the hook (keeps your files)

What it sends anywhere

Nothing. It runs locally, reads files in your project, and writes a note to your own prompt. Zero dependencies, zero telemetry, ~200 lines of Node you can read in a sitting.

Contributing

New stacks and directions are the most useful PRs — add a tested entry to directions.json and a matching case in the --self-test fixtures in compass.js. Keep it dependency-free.

License

MIT — see LICENSE.