Overview Files Skills Discover Packages Releases Dependencies Issues Breadcrumbs Pull Requests Activity

name: skill-pilot description: > Audit Claude Code SKILL.md files and route user prompts to matching skills via a UserPromptSubmit hook so Claude actually invokes the right skill. Trigger words: skill-pilot, lint skills, audit skills, skill description quality, skill front-load, skill triggers, why isn't claude using my skill, skill not triggering, skill routing, prompt routing, route to skill, skill matcher, skill router, enable skill hook, disable skill hook, skill-pilot on, skill-pilot off, skill-pilot status, skill-pilot lint, skill-pilot analyze, analyze skill matches, false positive skills, noisy skills, skill match log, skill router stats, audit my skills, check skill descriptions, are my skills formatted right, claude doesn't use my skills, claude misses skills, skill triggering, 1536 cap, skill cap, system reminder skills, claude code hook skills. Use when the user wants to audit their SKILL.md corpus for description quality (front-loaded triggers, length under the 1,536 cap, valid frontmatter), enable or disable the prompt-router hook that nudges Claude toward matching skills, see what skills matched recent prompts, or troubleshoot why Claude is ignoring a skill it should be using.

skill-pilot

Two halves: lint (audit your skill corpus) + router hook (inject a system reminder listing matching skills on every prompt so Claude actually invokes them).

When to use

The user says "claude isn't triggering my skill", "audit my skills", "lint skills", "skill-pilot lint/on/off/status", or "why isn't claude using <skill>?"
The user has > 50 skills and wants Claude to actually find the right one
Before publishing a new skill, to check description quality

CLI

skill-pilot lint                 # audit ~/.claude/skills + gallia/skills
skill-pilot lint --json          # machine-readable output
skill-pilot lint --dir <path>    # custom dir(s)

skill-pilot match --prompt "<text>"   # dry-run the matcher

skill-pilot on                   # wire UserPromptSubmit hook in ~/.claude/settings.json
skill-pilot off                  # remove hook
skill-pilot status               # wired? env-var state? last 10 matches

skill-pilot analyze              # historical log analysis: top firing,
                                 #   false-positive candidates, co-occurrence,
                                 #   zero-match prompts
skill-pilot analyze --json       # machine-readable

How the router works

Hook reads each user prompt → matches against an in-memory keyword index built from every skill's description+name → emits at most one <system-reminder> listing up to 5 matching skill names. Claude sees the reminder and invokes the relevant skill.

Index is cached in ~/.adom/skill-pilot/index.json for 5 minutes. Matches are logged to ~/.adom/skill-pilot/matches.log (timestamp, skills, prompt prefix).

Disabling

Three off-switches, increasing in scope:

ADOM_SKILL_PILOT=0 — env var, skips matching for that shell
skill-pilot off — removes the hook entry from settings.json
Edit ~/.claude/settings.json by hand — settings.json.skill-pilot.bak is kept

The hook also fails closed: if the binary errors or panics, it emits nothing and exits 0. Claude Code is never blocked by skill-pilot.

Lint scoring

Each skill scored 0–100. Deductions:

missing name / description: −30 / −50
description+when_to_use over 1,536 chars (the cap): −20
no detectable trigger phrases: −30
triggers exist but none in first 200 chars: −25
description shorter than 60 chars: −15

Trigger phrases are pulled from Trigger words: / Triggers: / Examples: blocks first, with a fallback to comma-separated noun phrases.

Storage

Binary: wherever you put skill-pilot on PATH
Settings: ~/.claude/settings.json
Cache: ~/.adom/skill-pilot/index.json
Match log: ~/.adom/skill-pilot/matches.log
Settings backup: ~/.claude/settings.json.skill-pilot.bak

---
name: skill-pilot
description: >
  Audit Claude Code SKILL.md files and route user prompts to matching skills via a
  UserPromptSubmit hook so Claude actually invokes the right skill. Trigger words:
  skill-pilot, lint skills, audit skills, skill description quality, skill front-load,
  skill triggers, why isn't claude using my skill, skill not triggering, skill
  routing, prompt routing, route to skill, skill matcher, skill router, enable skill
  hook, disable skill hook, skill-pilot on, skill-pilot off, skill-pilot status,
  skill-pilot lint, skill-pilot analyze, analyze skill matches, false positive skills,
  noisy skills, skill match log, skill router stats, audit my skills, check skill
  descriptions, are my skills formatted right, claude doesn't use my skills, claude
  misses skills, skill triggering, 1536 cap, skill cap, system reminder skills,
  claude code hook skills.
  Use when the user wants to audit their SKILL.md corpus for description quality
  (front-loaded triggers, length under the 1,536 cap, valid frontmatter), enable
  or disable the prompt-router hook that nudges Claude toward matching skills,
  see what skills matched recent prompts, or troubleshoot why Claude is ignoring a
  skill it should be using.
---

# skill-pilot

Two halves: **lint** (audit your skill corpus) + **router hook** (inject a system
reminder listing matching skills on every prompt so Claude actually invokes them).

## When to use

- The user says "claude isn't triggering my skill", "audit my skills", "lint skills",
  "skill-pilot lint/on/off/status", or "why isn't claude using `<skill>`?"
- The user has > 50 skills and wants Claude to actually find the right one
- Before publishing a new skill, to check description quality

## CLI

```bash
skill-pilot lint                 # audit ~/.claude/skills + gallia/skills
skill-pilot lint --json          # machine-readable output
skill-pilot lint --dir <path>    # custom dir(s)

skill-pilot match --prompt "<text>"   # dry-run the matcher

skill-pilot on                   # wire UserPromptSubmit hook in ~/.claude/settings.json
skill-pilot off                  # remove hook
skill-pilot status               # wired? env-var state? last 10 matches

skill-pilot analyze              # historical log analysis: top firing,
                                 #   false-positive candidates, co-occurrence,
                                 #   zero-match prompts
skill-pilot analyze --json       # machine-readable
```

## How the router works

Hook reads each user prompt → matches against an in-memory keyword index built from
every skill's description+name → emits at most one `<system-reminder>` listing up to
5 matching skill names. Claude sees the reminder and invokes the relevant skill.

Index is cached in `~/.adom/skill-pilot/index.json` for 5 minutes. Matches are
logged to `~/.adom/skill-pilot/matches.log` (timestamp, skills, prompt prefix).

## Disabling

Three off-switches, increasing in scope:

1. `ADOM_SKILL_PILOT=0` — env var, skips matching for that shell
2. `skill-pilot off` — removes the hook entry from settings.json
3. Edit `~/.claude/settings.json` by hand — settings.json.skill-pilot.bak is kept

The hook also fails closed: if the binary errors or panics, it emits nothing and
exits 0. Claude Code is never blocked by skill-pilot.

## Lint scoring

Each skill scored 0–100. Deductions:

- missing `name` / `description`: −30 / −50
- description+when_to_use over 1,536 chars (the cap): −20
- no detectable trigger phrases: −30
- triggers exist but none in first 200 chars: −25
- description shorter than 60 chars: −15

Trigger phrases are pulled from `Trigger words:` / `Triggers:` / `Examples:`
blocks first, with a fallback to comma-separated noun phrases.

## Storage

- Binary: wherever you put `skill-pilot` on PATH
- Settings: `~/.claude/settings.json`
- Cache: `~/.adom/skill-pilot/index.json`
- Match log: `~/.adom/skill-pilot/matches.log`
- Settings backup: `~/.claude/settings.json.skill-pilot.bak`