convez.ai
Skill
aniboy2k-gif

skill-advisor

aniboy2k-gif/skill-advisor

Ver no GitHub
InicialPluginScore · de 0 a 100

A decision-support framework for selecting the right approach in AI-assisted development workflows.

Instalação

$npx convez-ai aniboy2k-gif/skill-advisor

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 6 dias
Versão
—
Issues abertas
0
Contribuidores
2

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.

Claude Code Skill License: MIT

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:

CodeSeverityMeaningUser impact
C1criticalBroken absolute path in file_path_globsSkill silently fails to load
H0highGhost skill — zero triggers across all mechanismsSkill is completely unreachable
H1highMissing file_path_globsSkill won't load on file edits
H1-Einfotool_events only, no globs — intentional designNo false alarm; treated like H1-M
H1-Minfoutterance patterns only — intentional manual-onlyNo false alarm
M1mediumDuplicate glob string declared by 2+ skillsPotential redundant loading
I1infoEmpty description fieldReduces 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:

Channelupstream_typecheckapply
GitHub rawanthropic_official · microsoft · communitySHA256 diffReplace SKILL.md, preserve trigger_conditions
npmnpmnpm outdated + npm auditAdvisory (print command) — v2.0 will auto-install
pippippip list --outdatedAdvisory (print command) — never auto-installs
Local customlocal_custom—Not applicable

Safety features:

  • Atomic apply: backup → tmp write → verify → rename. If verify fails, .bak is restored automatically.
  • trigger_conditions preserved: your local trigger blocks survive GitHub raw updates.
  • npm guard: if a node_modules SKILL.md contains trigger_conditions, --apply is blocked until you relocate the block with skill-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.

CapabilityPhase 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:

MechanismHow it works
file_path_globsAuto-loads the skill when you edit a matching file path
tool_eventsAuto-loads when a specific tool (Edit, Write…) is used on a matching file
utterance_patternsHelps 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.sh SessionStart hook active

    Check if it's already installed:

    ls ~/.claude/hooks/skill-index.sh
    # Prints the path if installed — if not found, install the Claude Code hooks package
    

    To register the hook permanently, add to ~/.claude/settings.json:

    {
      "hooks": {
        "SessionStart": [
          {
            "hooks": [
              {"type": "command", "command": "zsh ~/.claude/hooks/skill-index.sh"}
            ]
          }
        ]
      }
    }
    

    If skill-index.json is 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
stdinNone
stdoutText report; --json → JSON array
stderrExecution error messages
exit 0--scan: no issues / --session-review: always (informational tool)
exit 1--scan: actionable findings exist (useful for CI gating)
exit 2Execution 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_signals array is matched. The trigger_pattern / trigger_pattern_en fields 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.

SkillWhen it should fire (intent)Example signals (English; JSON also has Korean)
/systematic-debuggingA bug, test failure, or unexpected behaviorerror, traceback, pytest, AssertionError
/planA new feature spans 3+ files, an architectural change, or an API changeSKILL.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-pipelineAPI, authentication, or security workauth, credentials, token, password
/verification-before-completionRight before claiming work is completedone, finished, complete
/vercel-react-best-practicesDesigning or implementing React components.tsx, .jsx, React, component
/handoff-verifyA sub-agent task has completed and needs independent verificationsubagent, 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. See data/hard-gates.json for 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", "..."]
    }
  ]
}
FieldTypeNotes
schema_versionstring"1.0" for this format. Adding new optional fields is non-breaking; removing or renaming fields is breaking and requires a version bump.
last_updatedstring (YYYY-MM-DD)Recommended to update when the file changes; not enforced.
descriptionstringHuman-readable origin of the gate set.
gatesarrayOrder is used for display only — it does not affect matching priority.
gates[].skillstringThe skill name --session-review will surface in its missing-gate list.
gates[].trigger_patternstringInformational metadata only (any language). Not used at runtime.
gates[].trigger_pattern_enstringInformational metadata only (English). Not used at runtime.
gates[].session_signalsstring[]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.

  1. Open data/hard-gates.json.
  2. Append a new entry to the gates array using the format above.
  3. Pick session_signals keywords that uniquely indicate the trigger pattern in your own session JSONL.
  4. Optionally bump last_updated.
  5. 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).

  6. Run --session-review against 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, traceback is safer than bug, which would also match words like debugger.

Out of scope (v1.0)

  • tier axis — 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
  • --apply is not available in Phase 1 — apply proposals manually via skill-creator
  • source_type classification is path-heuristic — official skill impersonation is not detected
  • --enrich supports official (anthropics/skills) and local (.claude/skills/) skills only
  • --session-review --confirm requires 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 SkillPatchProposal JSON (4 proposal types)
  • Automatic fallback scan when skill-index.json is 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.json for tunable signal→skill mapping
  • constants.py: shared constants preventing circular imports across analyzer modules

✅ Phase 1.7 (current)

  • --update mode: check and apply upstream skill updates from GitHub raw URLs, npm, and pip
  • scripts/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_conditions preservation: local trigger blocks survive upstream SKILL.md replacements
  • npm guard: blocks --apply when trigger_conditions lives inside node_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.sh for direct comparison
  • Enable --session-review to show "actually loaded" vs "should have loaded"

🔜 Phase 2 (planned)

  • Direct apply: send proposals to skill-creator automatically
  • Better conflict detection: fnmatch-based path overlap for M1
  • Smarter proposals: confidence scoring with source freshness tracking
  • Trusted source verification for official skills
  • --session-review utterance-based skill discovery (semantic analysis)
  • session-retrospective structured JSON exchange (requires author collaboration)

License

MIT

Ver o original no GitHub

Bom para

Relacionados