Skip to content

stevesolun/ctx / docs

skill-router

Flagged

Repo-aware recommendation manager for ctx. Scans the active repository, identifies stack and workflow signals, recommends a capped set of skills, agents, and MCP servers, and unloads helpers that no longer match the current work after user confirmation. Harnesses are recommended by the custom-model onboarding flow or loop adapters and then attach to the same recommendation layer.

FileKindSize
SKILL.mdskill md9.3 KB
assets/javascripts/catalog.jsscript2.5 KB
assets/javascripts/repo-stats-refresh.jsscript3.2 KB
backup-hook-install.mdmarkdown9.2 KB
catalog.mdmarkdown10.3 KB
ctx-fit/ARCHITECTURE_CANDIDATES.mdmarkdown12.9 KB
ctx-fit/ARCHITECTURE_GAP_ANALYSIS.mdmarkdown10.7 KB
ctx-fit/CTX_AUDIT.mdmarkdown11.6 KB
ctx-fit/CURRENT_STATE.mdmarkdown16.3 KB
ctx-fit/DECISIONS.mdmarkdown15.7 KB
ctx-fit/GOOD_FIRST_ISSUES.mdmarkdown20.6 KB
ctx-fit/IMPLEMENTATION_TRACKER.mdmarkdown697 B
ctx-fit/MAP.mdmarkdown7.8 KB
ctx-fit/PRD.mdmarkdown9.7 KB
ctx-fit/STATE.mdmarkdown60.9 KB
ctx-fit/milestones/M1_SPIKE_FRICTION_LOG.mdmarkdown5.5 KB
ctx-fit/milestones/MILESTONE_00_AUDIT.mdmarkdown5.1 KB
ctx-fit/planned_tasks.mdmarkdown17.7 KB
dashboard.mdmarkdown24.7 KB
enterprise-readiness-review.mdmarkdown8.7 KB
entity-onboarding.mdmarkdown18.0 KB
harness/attaching-to-hosts.mdmarkdown16.2 KB
harness/clean-host-contract.mdmarkdown4.5 KB
harness/loopflow-adapter-demo.mdmarkdown11.1 KB
huggingface-publish.mdmarkdown3.3 KB
index.mdmarkdown22.4 KB
knowledge-graph.mdmarkdown22.7 KB
marketplace-registry.mdmarkdown4.0 KB
memory-anchor.mdmarkdown2.7 KB
plans/ctx-agent-reviewer-workbench.mdmarkdown12.4 KB
plans/unified-capability-engine.mdmarkdown59.0 KB
qa/dashboard-user-story-status.csvother26.0 KB
qa/feature-user-story-status.csvother92.5 KB
research/context-engineering-guidance-audit.mdmarkdown10.4 KB
services/macos/com.claude.backup.watchdog.plistother1.7 KB
services/systemd/claude-backup-watchdog.serviceother1.3 KB
skill-lifecycle-and-dashboard.mdmarkdown6.2 KB
skill-quality-install.mdmarkdown6.2 KB
skill-router/index.mdmarkdown2.5 KB
skill-stack-matrix.mdmarkdown5.5 KB
skills-health.mdmarkdown3.5 KB
stack-signatures.mdmarkdown6.2 KB
telemetry.mdmarkdown24.7 KB
threat-model.mdmarkdown15.0 KB
toolbox/behavior-miner.mdmarkdown2.6 KB
toolbox/configuration.mdmarkdown4.0 KB
toolbox/council-runner.mdmarkdown2.4 KB
toolbox/hooks.mdmarkdown2.6 KB
toolbox/index.mdmarkdown3.0 KB
toolbox/intent-interview.mdmarkdown3.0 KB
toolbox/starters.mdmarkdown3.0 KB
toolbox/templates/docs-review.jsonconfig599 B
toolbox/templates/fresh-repo-init.jsonconfig533 B
toolbox/templates/refactor-safety.jsonconfig634 B
toolbox/templates/security-sweep.jsonconfig636 B
toolbox/templates/ship-it.jsonconfig676 B
toolbox/verdicts.mdmarkdown4.0 KB

skill-quality-install.md

View on GitHub
# Skill quality — install & operations

One page on running the quality scorer: install the Stop hook, seed the
sidecars, and verify the data flows into the wiki and the knowledge graph.

## What it does

Every installed skill and agent gets a continuous quality score in
`[0.0, 1.0]` plus an A/B/C/D/F letter grade, derived from four signals:

| Signal    | Weight | What it measures                                      |
| --------- | -----: | ----------------------------------------------------- |
| telemetry |   0.40 | Load count, recency, freshness in `skill-events.jsonl`|
| intake    |   0.20 | Live re-run of the six install-time structural checks |
| graph     |   0.25 | Degree + average edge weight in the wiki graph        |
| routing   |   0.15 | Router hit-rate (neutral prior below 3 observations)  |

Two hard floors override the weighted sum:

- **`intake_fail`** — any structural check is currently failing → grade **F**.
  Grade F is **only** produced by this hard floor; it is never returned by
  the score-to-grade mapping function alone.  A score of 0.0 maps to **D**.
- **`never_loaded_stale`** — no load events ever → grade capped at **D**.

The score is mirrored to three on-disk sinks so every consumer sees the
same number:

1. `~/.claude/skill-quality/<slug>.json` — canonical machine-readable form.
2. Wiki entity frontmatter — `quality_score`, `quality_grade`, `quality_updated_at`.
3. Wiki body — a `## Quality` block between `<!-- quality:begin -->` markers.

The knowledge-graph node attribute is a **separate consumer path**, not a
write path from `persist_quality`: `wiki_graphify` reads the sidecar JSON
produced by sink 1 and attaches `quality_score` / `quality_grade` to each
node on its next build.

## Register the Stop hook

The hook runs once per session-end. It reads `skill-events.jsonl` since
its last run, collects every slug that appeared, and calls
`skill_quality.py recompute --slugs <comma-list>` — so scoring is
incremental (touched skills only), not a full 2,000-page sweep.

Edit `~/.claude/settings.json` and add, replacing `<REPO>` with the
absolute path to this checkout:

```json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python <REPO>/hooks/quality_on_session_end.py"
          }
        ]
      }
    ]
  }
}
```

The hook always exits 0: a scoring error will not block session
shutdown. If recompute fails, the hook leaves
`~/.claude/skill-quality/.hook-state.json` unchanged so the same event
window is retried on the next session end.

## Seed the sidecars (first run only)

Run once after install so every installed skill has a baseline score:

```bash
python -m skill_quality recompute --all
```

This walks `~/.claude/skills/*/SKILL.md` and `~/.claude/agents/*.md`,
scores each, and writes the three on-disk sinks. Expect ~15–30s depending on
corpus size and disk.

## CLI reference

```bash
# Full recompute (use sparingly; the Stop hook handles incrementals).
python -m skill_quality recompute --all

# One slug.
python -m skill_quality recompute --slug python-testing

# Show the most recent score.
python -m skill_quality show python-testing

# Signal-by-signal breakdown with evidence.
python -m skill_quality explain python-testing

# List every slug with its grade, filtered.
python -m skill_quality list --grade D
```

All verbs accept `--json` for piping into other tools.

## Graph integration

`wiki_graphify.py` reads the sidecar directory automatically and
attaches `quality_score` and `quality_grade` to every matching node. The
Obsidian graph view can then color nodes by grade — configure the
`quality_grade` property in Obsidian's graph settings.

Nodes without a sidecar get `quality_score: null` and `quality_grade:
null` so downstream consumers can always read the attribute safely.

## Configuration

All knobs live in `src/config.json` under the top-level `quality` key:

```json
{
  "quality": {
    "weights": {
      "telemetry": 0.40, "intake": 0.20, "graph": 0.25, "routing": 0.15
    },
    "agent_weights": {
      "telemetry": 0.15, "intake": 0.30, "graph": 0.35, "routing": 0.20
    },
    "grade_thresholds": {"A": 0.80, "B": 0.60, "C": 0.40},
    "stale_threshold_days": 30.0,
    "recent_window_days": 14.0,
    "min_body_chars": 120,
    "paths": {
      "sidecar_dir": "~/.claude/skill-quality",
      "router_trace": "~/.claude/router-trace.jsonl"
    }
  }
}
```

`ctx_config.Config` exposes this through `cfg.get("quality", {})`. User
overrides in `~/.claude/skill-system-config.json` deep-merge over the
repo defaults, so you can pin only the keys you want to change.

Both weight vectors must sum to 1.0 (±0.01) and grade thresholds must
satisfy `0 ≤ C ≤ B ≤ A ≤ 1` — `QualityConfig.__post_init__` will raise
on bad values, catching typos before they pollute sidecars.

### Why two weight vectors

Skills and agents differ in how they're invoked. Skills are loaded
automatically by the router, so **telemetry** (load counts, recency) is
the strongest post-install quality signal — hence 0.40 weight.

Agents are invoked via the Agent tool, deliberately and rarely. A
seldom-used agent isn't stale, it's specialized. The agent weights
shift mass onto **graph connectedness** (0.35) and **intake structure**
(0.30) so agents aren't penalized for having an empty telemetry stream.
The `never_loaded_stale` hard floor, which caps skills at D when they
have zero load events, does **not** apply to agents for the same
reason.

## Troubleshooting

- **Every skill grades D.** Telemetry hasn't accumulated enough load
  events yet. This is expected on a fresh install; the stop-hook will
  pick up real usage over the next few sessions.
- **A recently-edited skill now grades F.** Open the sidecar and look
  at `signals.intake.evidence.checks` — one of the six structural
  checks is failing. Fix the file and rerun `recompute --slug <name>`.
- **Wiki page has two `## Quality` sections.** Shouldn't happen —
  `persist_quality` is idempotent via the HTML-comment markers. If it
  does, delete both blocks and rerun `recompute`; the first pass will
  re-emit exactly one.
- **Graph view shows no color.** Run `python -m ctx.core.wiki.wiki_graphify
  --graph-only` to rebuild; it reads sidecars fresh on every build.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall