# Skill Compass

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-by-sonic-skill-compass-skill-compass`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [by-sonic](https://agentstack.voostack.com/s/by-sonic)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [by-sonic](https://github.com/by-sonic)
- **Source:** https://github.com/by-sonic/skill-compass/tree/master/skill/skill-compass
- **Website:** https://by-sonic.github.io/skill-compass/

## Install

```sh
agentstack add skill-by-sonic-skill-compass-skill-compass
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# skill-compass

`UserPromptSubmit` + `PostToolUse` hooks for Claude Code. They route to the right
skills/agents from three signals: the working directory's composition (languages,
frameworks, config files), project/topic keywords in your prompt, and keywords the
AI surfaces mid-turn (a `Bash`/`Grep`/`Glob`/`Read`/`Task` result). E.g. UI files →
frontend-design, API routes → api-design, a `Dockerfile` → infra, "find the
clickhouse migration" → the database skills. It nudges the model toward the right skill instead of
relying on memory.

## Layout (this repo)

Run paths are relative to the repo root (the parent of `skill/`):

- `compass.js` — the hook engine (handles both events). Flags: `--self-test`, `--force`, `--post` (PostToolUse mode). Disable per-session with env `SKILL_COMPASS=off`.
- `directions.json` — the routing table: maps detected stacks/files → suggested directions. **This is the file users edit.**
- `install.js` — installer. Copies `compass.js` + `directions.json` into `~/.claude/skill-compass/` and registers both the `UserPromptSubmit` and `PostToolUse` hooks in `~/.claude/settings.json`. Idempotent. `--uninstall` removes both hooks.

After install the live copy runs from `~/.claude/skill-compass/`, so edits to the
installed `directions.json` survive re-installs (the installer keeps an existing
one).

## Tasks

### Install / enable the hook

Run from the repo root:

```
node install.js
```

It copies files, registers the hook, and prints the test command. Tell the user
to **restart Claude Code** afterward — the hook is loaded at process start. If
they re-run it, it's a no-op (idempotent), which is the expected, safe outcome.

### Uninstall / disable

- Permanent removal: `node install.js --uninstall` (strips the hook from `settings.json`, leaves files in place).
- Temporary, one session: set `SKILL_COMPASS=off` in the environment before launching Claude Code.

### Inspect or edit routing rules

`directions.json` is the source of truth for what gets suggested. To see current
rules, read it. To change behavior, edit it directly. After editing the
*installed* copy at `~/.claude/skill-compass/directions.json`, no reinstall is
needed — the running hook reads it fresh.

When adding a new stack→direction mapping, match the existing entries' shape (a
detector for the stack and the direction text it emits). After any edit, always
run the self-test below to confirm nothing broke.

### Run the self-test

This is the verification step before claiming any change works:

```
node compass.js --self-test
```

It exercises stack detection, direction routing, and the empty-project guard,
then prints `ALL PASSED` (non-zero exit on failure). If a user reports the hook
mis-suggesting, reproduce by adding or adjusting a case here first — a failing
self-test case localizes the bug before you touch the engine.

### Debug "it's not suggesting anything"

Walk these in order:
1. Hooks registered? Check `~/.claude/settings.json` → `hooks.UserPromptSubmit` and `hooks.PostToolUse` each contain a command with `skill-compass` (the PostToolUse one ends with `--post`).
2. Disabled? Check the `SKILL_COMPASS` env var isn't `off`.
3. Restarted? Hooks only load at Claude Code startup.
4. Empty/at-root project? With no stack manifest, no prompt keyword and no mid-turn tool finding, the engine intentionally stays silent (junk-drawer guard) — `cd` into a real project, mention a project/topic keyword, or pass `--force`.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [by-sonic](https://github.com/by-sonic)
- **Source:** [by-sonic/skill-compass](https://github.com/by-sonic/skill-compass)
- **License:** MIT
- **Homepage:** https://by-sonic.github.io/skill-compass/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-by-sonic-skill-compass-skill-compass
- Seller: https://agentstack.voostack.com/s/by-sonic
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.