skill-advisor
aniboy2k-gif/skill-advisor
A decision-support framework for selecting the right approach in AI-assisted development workflows.
Instalação
npx convez-ai aniboy2k-gif/skill-advisor1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
skill-advisor
Your Claude Code skills not triggering? Find out why — without touching a single file.
skill-advisor is a read-only diagnostic skill for Claude Code. No SKILL.md is ever modified — it surfaces issues and outputs structured JSON proposals you review and apply when ready.
When to use this
- A skill isn't loading automatically even though you installed it
- Two skills seem to react to the same file at the same time
- You want a safety check before editing a skill's configuration manually
- You want to know which of your skills have no file-based auto-trigger set up
- You want error and correction patterns from your session mapped to relevant skills
- You want to check if installed skills have newer upstream versions available
- You want to bulk-update skills from GitHub, npm, or pip in one command
Features
Find unreachable and misconfigured skills — --scan
Audits all installed skills and classifies issues by severity:
| Code | Severity | Meaning | User impact |
|---|---|---|---|
| C1 | critical | Broken absolute path in file_path_globs | Skill silently fails to load |
| H0 | high | Ghost skill — zero triggers across all mechanisms | Skill is completely unreachable |
| H1 | high | Missing file_path_globs | Skill won't load on file edits |
| H1-E | info | tool_events only, no globs — intentional design | No false alarm; treated like H1-M |
| H1-M | info | utterance patterns only — intentional manual-only | No false alarm |
| M1 | medium | Duplicate glob string declared by 2+ skills | Potential redundant loading |
| I1 | info | Empty description field | Reduces indexing quality |
H0 is higher severity than H1: a ghost skill is completely unreachable, while H1/H1-E/H1-M skills can still be triggered by other mechanisms.
⚠ Phase 1 limitation: M1 detects exact string matches only. "No M1" does not guarantee zero conflicts.
Review post-work skill coverage — --session-review
After completing a task, analyze the current session's JSONL to get two layers of skill recommendations:
Layer 1 — File-change based (existing): Which skills are relevant to files you edited?
Layer 2 — Signal based (new in Phase 1.6): What do error patterns and user corrections in this session suggest about missing skills?
/skill-advisor --session-review → Immediate analysis (most recent session)
/skill-advisor --session-review --confirm → Choose session interactively
/skill-advisor --session-review --json → Machine-readable output
Example output:
## /skill-advisor --session-review
Session: abc123.jsonl (2026-04-23 09:18, 1662 KB)
Parsed: 160 file edit events / 758 tool_uses
---
### Related Skill Candidates (file-change based)
Skill Matched file Glob Confidence
----------------------------------------------------------------------------------------------------
skill-creator SKILL.md **/.claude/skills/** medium
---
### Error-driven Recommendations
Skill Signal Confidence Evidence
--------------------------------------------------------------------------------
systematic-debugging test failure pattern high 3 건
---
### Correction-driven Recommendations
→ plan (repeated user corrections, 4건 수정 감지)
🔗 session-retrospective installed — run /session-retrospective for a full session retrospective
Each signal-based recommendation carries provenance: source, signal, confidence, and evidence_count — so you know exactly why a skill was recommended.
Conservative design: signal detection uses a 3-condition AND gate (assistant tool_use preceding + short message + negation keyword) to minimise false positives. False negatives are accepted as a trade-off.
Phase 1 limitation: Bash command-based file changes are not detected. Signal recommendations are heuristic, not definitive.
Get reviewable improvement proposals — --enrich [skill-name]
Reads the target skill's SKILL.md, optionally fetches the official README for anthropics/skills sources, and outputs a SkillPatchProposal[] array — structured suggestions you review before applying.
Check and apply upstream skill updates — --update
Keep your installed skills in sync with their upstream sources (GitHub, npm, pip). skill-advisor tracks each skill's source URL in ~/.claude/skill-sources.json and compares SHA256 hashes to detect updates.
/skill-advisor --update → Check all skills for updates (dry-run)
/skill-advisor --update <skill-name> → Check a specific skill
/skill-advisor --update --apply → Apply updates (y/N confirmation per skill)
/skill-advisor --update --apply --yes → Apply all updates automatically (CI mode)
/skill-advisor --update --apply <skill> → Apply update to one skill
/skill-advisor --update --json → Machine-readable output
Channel behaviour:
| Channel | upstream_type | check | apply |
|---|---|---|---|
| GitHub raw | anthropic_official · microsoft · community | SHA256 diff | Replace SKILL.md, preserve trigger_conditions |
| npm | npm | npm outdated + npm audit | Advisory (print command) — v2.0 will auto-install |
| pip | pip | pip list --outdated | Advisory (print command) — never auto-installs |
| Local custom | local_custom | — | Not applicable |
Safety features:
- Atomic apply:
backup → tmp write → verify → rename. If verify fails,.bakis restored automatically. trigger_conditionspreserved: your local trigger blocks survive GitHub raw updates.- npm guard: if a
node_modulesSKILL.md containstrigger_conditions,--applyis blocked until you relocate the block withskill-creator.
Exit codes: 0 up-to-date · 1 updates available · 2 fetch error · 3 apply failed (rollback OK) · 4 apply + rollback both failed (.bak path printed)
SSOT: ~/.claude/skill-sources.json — tracks 65+ skills, upstream URLs, channels, and last-check timestamps.
Machine-readable output — --scan --json
Returns a JSON array for CI pipelines or shell scripts.
The --session-review --json output includes:
{
"session": "abc123.jsonl",
"track": "track1",
"candidates": [...],
"signal_recommendations": [
{
"skill": "systematic-debugging",
"source": "error_signal",
"signal": "test failure pattern",
"confidence": "high",
"evidence_count": 3
}
],
"proposals": [...]
}
Optional Integration: session-retrospective
skill-advisor works standalone, but pairs naturally with claude-skill-session-retrospective.
Two-track detection
skill-advisor automatically detects whether session-retrospective is installed and adjusts its output:
| Track 1 (installed) | Track 2 (not installed) | |
|---|---|---|
| JSONL analysis | ✅ same | ✅ same |
| Signal recommendations | ✅ same | ✅ same |
| Footer message | 🔗 session-retrospective installed — run /session-retrospective | 💡 TIP: install session-retrospective for a full narrative retrospective |
Both tracks produce identical skill recommendation quality — the difference is only the footer guidance.
Install session-retrospective
cd ~/.claude/skills
git clone https://github.com/accidentalrebel/claude-skill-session-retrospective session-retrospective
Once installed, running /skill-advisor --session-review followed by /session-retrospective gives you:
- skill-advisor: which skills to use next time (forward-looking)
- session-retrospective: what you learned this session (backward-looking)
Note: session-retrospective has no published license (licenseInfo: null as of 2026-04-23). skill-advisor's signal analysis is an independent implementation — no code from that repository is reused.
What skill-advisor does right now (Phase 1.6)
skill-advisor never writes to SKILL.md — it only reads and reports.
| Capability | Phase 1.6 (now) | Phase 2 (planned) |
|---|---|---|
Diagnose skill coverage (--scan) | ✅ | ✅ |
Generate improvement proposals (--enrich) | ✅ dry-run only | ✅ |
| Apply proposals to SKILL.md | ❌ not available | ✅ via skill-creator --apply-proposal |
File-change based skill candidates (--session-review) | ✅ | ✅ |
Error/correction signal analysis (--session-review) | ✅ | ✅ |
| session-retrospective 2-track detection | ✅ | ✅ |
Upstream update check (--update) | ✅ GitHub/npm/pip | ✅ |
Upstream update apply (--update --apply) | ✅ GitHub raw; npm/pip advisory | ✅ full npm/pip |
To apply proposals now: review the JSON output, then use skill-creator manually.
Architecture (Phase 1.7)
scripts/
session-review.py Orchestrator — coordinates session analysis
update.py Orchestrator — coordinates upstream update checks and applies
jsonl_analyzer.py Collector — parses JSONL for error/correction signals
signal_to_skill.py Mapper — maps signals to skill recommendations (with provenance)
constants.py Shared constants (prevents circular imports)
channels/
github_raw.py Channel handler — SHA256 diff, atomic apply, trigger_conditions preserve
npm.py Channel handler — npm outdated + audit, advisory apply
pip.py Channel handler — pip list --outdated, advisory apply
data/
signal-skills.json Versioned mapping table (schema_version: "1.0")
~/.claude/
skill-sources.json SSOT — 65+ skills, upstream URLs, channels, last-check timestamps
The signal mapping table is externalized so you can tune it without touching Python code:
{
"schema_version": "1.0",
"mappings": [
{
"id": "test-failure",
"triggers": { "error_keywords": ["AssertionError", "test failed"], "min_count": 1 },
"skill": "systematic-debugging",
"confidence": "high",
"evidence_label": "test failure pattern"
}
]
}
What is a Claude Code skill?
Claude Code skills are SKILL.md files that extend Claude's capabilities. Each skill can define three types of trigger mechanisms:
| Mechanism | How it works |
|---|---|
file_path_globs | Auto-loads the skill when you edit a matching file path |
tool_events | Auto-loads when a specific tool (Edit, Write…) is used on a matching file |
utterance_patterns | Helps Claude identify the skill when you describe a task in natural language |
skill-advisor audits all three. A skill with none of them is a "ghost skill" — installed but unreachable.
New to Claude Code? See the official skills documentation to get started.
Prerequisites
-
Claude Code installed and running
-
Python 3.9+ (for
--session-review)Verify:
python3 --version -
skill-index.shSessionStart hook activeCheck if it's already installed:
ls ~/.claude/hooks/skill-index.sh # Prints the path if installed — if not found, install the Claude Code hooks packageTo register the hook permanently, add to
~/.claude/settings.json:{ "hooks": { "SessionStart": [ { "hooks": [ {"type": "command", "command": "zsh ~/.claude/hooks/skill-index.sh"} ] } ] } }If
skill-index.jsonis unavailable at runtime, skill-advisor automatically falls back to scanning~/.claude/skills/directly and warns you.
Installation
# Clone and install
git clone https://github.com/aniboy2k-gif/skill-advisor
cp -r skill-advisor ~/.claude/skills/
# ↑ This copies SKILL.md, scripts/, data/, and references/
# Rebuild the skill index so Claude Code recognises the new skill
zsh ~/.claude/hooks/skill-index.sh
Start or restart a Claude Code session — skill-advisor will be available immediately.
Optional: pair with session-retrospective
cd ~/.claude/skills
git clone https://github.com/accidentalrebel/claude-skill-session-retrospective session-retrospective
Usage
/skill-advisor → Full scan (default)
/skill-advisor --scan → Coverage audit with severity labels
/skill-advisor --scan --json → JSON output for automation
/skill-advisor --enrich <skill-name> → Deep analysis + SkillPatchProposal output
/skill-advisor --session-review → Post-work skill candidate recommendations
/skill-advisor --session-review --confirm → Choose session interactively
⚠ Requires interactive terminal — do not use in Claude Code sessions
Example --scan output
## skill-advisor --scan (2026-04-23)
| Skill | globs | events | Type | Issues |
|------------------|-------|--------|-------------|---------|
| doc-coauthoring | 8 | 10 | normal | — |
| skill-creator | 7 | 12 | normal | — |
| my-custom-skill | 0 | 0 | manual-only | ℹ H1-M |
Issue list
[HIGH] orphan-skill: H0 Ghost skill — no triggers defined
[MEDIUM] skill-a, skill-b: M1 duplicate glob "**/*.md"
⚠ M1 matches exact strings only — fnmatch path overlap detection coming in Phase 2.
Example SkillPatchProposal (--enrich)
[
{
"schema_version": "1.0",
"skill": "doc-coauthoring",
"target_field": "file_path_globs",
"proposal_type": "add_glob",
"value": "**/*.mdx",
"current_value": ["**/*.md"],
"source": "official_readme",
"source_url": "https://github.com/anthropics/skills/...",
"fetched_at": "2026-04-23T10:00:00+0900",
"confidence": "high",
"reason": "MDX files mentioned in official README"
}
]
proposal_type values (Phase 1): add_glob · update_description · fix_path · update_utterance
I/O Contract
| Definition | |
|---|---|
| stdin | None |
| stdout | Text report; --json → JSON array |
| stderr | Execution error messages |
| exit 0 | --scan: no issues / --session-review: always (informational tool) |
| exit 1 | --scan: actionable findings exist (useful for CI gating) |
| exit 2 | Execution failed — file access error, parse error, etc. |
--session-review --json keys: session, track, stats, candidates, signal_recommendations, proposals
Configuration: Hard Gates
What this is: a lightweight JSON configuration file, not a stable plugin API. The schema may change before v2.0 — fork or pin a commit if you depend on it.
data/hard-gates.json lists which skill --session-review should expect to have run when certain signals appear in a session.
A Hard Gate is a rule that tells --session-review which skill should have been used; the tool then flags missing gates. It does not automatically run the skill.
How matching works (read this first):
- Matching is literal: case-sensitive substring checks against the session JSONL — not semantic / NLP matching.
- Only the
session_signalsarray is matched. Thetrigger_pattern/trigger_pattern_enfields are informational metadata only (human-readable; not used for matching).
Source of truth: data/hard-gates.json is the source of truth for gate definitions; this section documents that file.
Bundled default gates (v1.0)
The bundled six gates come from the maintainer's real-world Claude Code workflow and are provided as defaults — they are not official Claude Code rules.
| Skill | When it should fire (intent) | Example signals (English; JSON also has Korean) |
|---|---|---|
/systematic-debugging | A bug, test failure, or unexpected behavior | error, traceback, pytest, AssertionError |
/plan | A new feature spans 3+ files, an architectural change, or an API change | SKILL.md (this gate's signal coverage is intentionally narrow — the trigger intent above is broader than the single keyword that fires it; if you add your own copy of this gate, pick more distinctive signals) |
/security-pipeline | API, authentication, or security work | auth, credentials, token, password |
/verification-before-completion | Right before claiming work is complete | done, finished, complete |
/vercel-react-best-practices | Designing or implementing React components | .tsx, .jsx, React, component |
/handoff-verify | A sub-agent task has completed and needs independent verification | subagent, sub-agent, agent completed |
Korean signals: Some entries in the JSON also include Korean keywords (e.g.
완료,서브에이전트). They are present because Claude Code sessions may contain mixed-language prompts and completion claims; the matcher treats them no differently from English keywords. Seedata/hard-gates.jsonfor the full list.
Data format (v1.0)
This is not a JSON Schema — it's a description of the file's shape.
{
"schema_version": "1.0",
"last_updated": "YYYY-MM-DD",
"description": "Free-text description of where these gates come from",
"gates": [
{
"skill": "skill-name",
"trigger_pattern": "fire condition (free-form, may be in any language)",
"trigger_pattern_en": "fire condition (English)",
"session_signals": ["keyword1", "keyword2", "..."]
}
]
}
| Field | Type | Notes |
|---|---|---|
schema_version | string | "1.0" for this format. Adding new optional fields is non-breaking; removing or renaming fields is breaking and requires a version bump. |
last_updated | string (YYYY-MM-DD) | Recommended to update when the file changes; not enforced. |
description | string | Human-readable origin of the gate set. |
gates | array | Order is used for display only — it does not affect matching priority. |
gates[].skill | string | The skill name --session-review will surface in its missing-gate list. |
gates[].trigger_pattern | string | Informational metadata only (any language). Not used at runtime. |
gates[].trigger_pattern_en | string | Informational metadata only (English). Not used at runtime. |
gates[].session_signals | string[] | The only field actually matched. Case-sensitive substring matches against the session JSONL. |
Adding a custom gate (in your fork or local clone)
You can add gates to your own copy of the file without code changes — as long as the skill name exists in your environment and the chosen signals actually appear in your session JSONL.
- Open
data/hard-gates.json. - Append a new entry to the
gatesarray using the format above. - Pick
session_signalskeywords that uniquely indicate the trigger pattern in your own session JSONL. - Optionally bump
last_updated. - Validate the JSON syntax before committing:
python3 -m json.tool data/hard-gates.json > /dev/null && echo "JSON syntax OK" # or, if you have jq: jq empty data/hard-gates.json && echo "JSON syntax OK"This only checks JSON syntax — it does not check semantic validity (e.g. that the skill name exists in your environment, that signals are well chosen, or that fields are not duplicated). A bundled JSON-Schema validator is on the roadmap (see Out of scope below).
- Run
--session-reviewagainst a session that should fire the new gate to confirm it triggers as expected.
Best practice: choose distinctive signals (typically 4+ characters and unique to your context) to avoid false-positive matches in unrelated text — for example,
tracebackis safer thanbug, which would also match words likedebugger.
Out of scope (v1.0)
tieraxis — Some advanced setups classify gates by when they should run (e.g. before edit, after response). This schema does not model that yet.- Programmatic JSON-Schema validation — Not bundled. Roadmap item.
- Adding a 7th bundled default (e.g.
/check-context-size) — Tracked separately; users are free to add it as a custom gate locally.
Limitations
- M1 detects exact string duplicates only — fnmatch path overlap is Phase 2
--applyis not available in Phase 1 — apply proposals manually viaskill-creatorsource_typeclassification is path-heuristic — official skill impersonation is not detected--enrichsupports official (anthropics/skills) and local (.claude/skills/) skills only--session-review --confirmrequires an interactive terminal- Signal analysis uses a conservative 3-condition gate — some corrections may not be detected (by design)
- session-retrospective integration: skill-advisor detects installation but does not execute its scripts or parse its output
Roadmap
✅ Phase 1 (initial)
- Scan for C1 / H0 / H1 / M1 / I1 issues with severity classification
- Generate
SkillPatchProposalJSON (4 proposal types) - Automatic fallback scan when
skill-index.jsonis unavailable --session-review: post-work skill candidate recommendations from JSONL session analysis
✅ Phase 1.6
- JSONL signal analysis: error patterns (
is_error: true) and correction patterns mapped to skills - Provenance fields: every recommendation carries
source,signal,confidence,evidence_count - 2-track detection: auto-detects session-retrospective installation, adapts output accordingly
- Versioned mapping table:
data/signal-skills.jsonfor tunable signal→skill mapping - constants.py: shared constants preventing circular imports across analyzer modules
✅ Phase 1.7 (current)
--updatemode: check and apply upstream skill updates from GitHub raw URLs, npm, and pipscripts/channels/: channel-scoped handlers (github_raw, npm, pip) with per-channel semantics- Atomic apply (GitHub raw): backup → write to temp → verify frontmatter → rename. Rollback on failure.
trigger_conditionspreservation: local trigger blocks survive upstream SKILL.md replacements- npm guard: blocks
--applywhentrigger_conditionslives insidenode_modules(data loss prevention) ~/.claude/skill-sources.json: SSOT for 65+ skill upstream URLs, channels, and last-check state- Exit code contract: 0 up-to-date · 1 updates available · 2 fetch error · 3 apply+rollback OK · 4 apply+rollback failed
🔜 Phase 1.5 (next milestone)
- Load event logging in
skill-auto-loader.shfor direct comparison - Enable
--session-reviewto show "actually loaded" vs "should have loaded"
🔜 Phase 2 (planned)
- Direct apply: send proposals to
skill-creatorautomatically - Better conflict detection: fnmatch-based path overlap for M1
- Smarter proposals: confidence scoring with source freshness tracking
- Trusted source verification for official skills
--session-reviewutterance-based skill discovery (semantic analysis)- session-retrospective structured JSON exchange (requires author collaboration)
License
MIT