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-lifecycle-and-dashboard.md

View on GitHub
# Skill lifecycle & KPI dashboard — install & operations

One page on running the lifecycle CLI, the category backfill, and the KPI
dashboard. Prerequisite: the quality scorer is installed and has written at
least one sidecar. See
[skill-quality-install.md](./skill-quality-install.md).

## What it does

After the scorer has labeled everything, these three tools turn the
labels into action:

| Tool | CLI | Purpose |
| ---- | --- | ------- |
| `ctx_lifecycle.py`  | `review`, `demote`, `archive`, `purge`, `review-archived` | Move D/F-grade skills through `active → watch → demote → archive → deleted`. |
| `skill_category.py` | `backfill`, `infer`                                       | Write the closed-set `category:` field into skill/agent frontmatter. |
| `kpi_dashboard.py`  | `render`, `summary`                                       | Emit a single Markdown dashboard joined across all quality sinks. |

Asymmetric gates: downward transitions are automatic from a D-streak;
upward transitions are deliberate. Archive needs aging (`active` for
14 days in `_demoted`); delete needs a typed-slug confirmation even
under `--auto`.

## Category taxonomy

Closed set: `framework`, `language`, `tool`, `pattern`, `workflow`,
`meta`. The dashboard groups scores by category so you can see, e.g.,
that your `framework`-tagged skills average a B but your
`workflow`-tagged skills are mostly D — which tells you where to focus
curation.

Inference is precedence-ordered: `python + django` → `language`
(language wins over framework). The backfill **never overwrites** an
existing non-empty value — human edits win.

Run once after the scorer has seeded the sidecars:

```bash
python -m skill_category backfill --dry-run
python -m skill_category backfill            # apply
```

Unresolved slugs (no tag matched the taxonomy) are listed for manual
curation.

## Lifecycle CLI

Four verbs. All are propose-and-confirm by default; `--auto` unlocks
only the safe tiers (Watch + Demote).

```bash
# List every pending transition; no writes.
python -m ctx_lifecycle review --dry-run

# Apply all Watch/Demote transitions without prompting.
python -m ctx_lifecycle review --auto

# Archive a specific slug. Requires the demoted aging threshold to have passed.
python -m ctx_lifecycle archive <slug>

# Delete archived slugs that exceeded the delete threshold.
# Requires typed-slug confirmation per entry even with --auto.
python -m ctx_lifecycle purge

# List archived slugs with optional diffs, or restore one.
python -m ctx_lifecycle review-archived --show-diff
python -m ctx_lifecycle review-archived --restore <slug>
```

Filesystem moves: demote → `<skills_dir>/_demoted/<slug>/`, archive →
`<skills_dir>/_archive/<slug>/`. The scanner skips directories starting
with `_`, so demoted/archived skills no longer show up to the router.

Lifecycle state is persisted in a sibling sidecar at
`~/.claude/skill-quality/<slug>.lifecycle.json`. Each transition is
folded into the `history` array (capped at `history_max`) so you can
audit how a slug ended up where it did.

### The D-streak

A skill needs `consecutive_d_to_demote` consecutive D-or-F grades to
trigger a demote proposal. Any A/B/C grade resets the streak to 0. The
default is 2 — one bad session is a blip, two in a row is a trend.

## KPI dashboard

Pure read-only. Walks both quality sidecars and lifecycle sidecars,
joins them against `category:` in frontmatter (with inference
fallback), and emits Markdown or JSON.

```bash
# Dump Markdown to stdout.
python -m kpi_dashboard render

# Persist to a file — good target for the cron / pre-push hook.
python -m kpi_dashboard render --out ~/.claude/skill-quality/kpi.md

# Machine-readable.
python -m kpi_dashboard render --json --out kpi.json

# Terse one-screen summary.
python -m kpi_dashboard summary
```

### What's in the report

- **Grade distribution** — A/B/C/D/F counts + percentages. Blank grade
  (no score yet) rolls up to F so it surfaces in the "needs
  attention" bucket.
- **Lifecycle tiers** — counts across active/watch/demote/archive.
- **Hard floors active** — how many slugs are failing intake or
  never-loaded-stale.
- **By category** — per-category count, average score of
  scored entries, and a mini A/B/C/D/F mix table.
- **Top demotion candidates** — up to `--limit N` (default 10) active
  or watch-tier entries sorted by (D-streak desc, score asc). These
  are the first slugs `ctx_lifecycle review --auto` will act on.
- **Archived (restorable)** — every slug currently in the archive
  tier; still recoverable via `review-archived --restore <slug>` until
  `purge` deletes them.

## Configuration

All knobs live under `quality` in `src/config.json`:

```json
{
  "quality": {
    "lifecycle": {
      "archive_threshold_days": 14.0,
      "delete_threshold_days": 60.0,
      "consecutive_d_to_demote": 2,
      "demoted_subdir": "_demoted",
      "archive_subdir": "_archive",
      "history_max": 20
    },
    "dashboard": {
      "default_top_n": 10,
      "report_path": "~/.claude/skill-quality/kpi.md"
    }
  }
}
```

Tighten `consecutive_d_to_demote` to 1 for aggressive pruning, or
loosen `archive_threshold_days` if you want a longer grace window
before a demoted skill gets archived.

## Operational cadence

A reasonable default rhythm, given the defaults above:

- **Every session** — scorer hook runs automatically on session end.
- **Weekly** — `ctx_lifecycle review --auto` to sweep Watch/Demote.
- **Weekly** — `kpi_dashboard render --out …/kpi.md` for the digest.
- **Monthly** — `ctx_lifecycle review` (no `--auto`) to surface
  archive-ready demoted skills for manual approval.
- **Quarterly** — `ctx_lifecycle purge` with typed-slug confirmation
  to actually remove archived skills past the delete threshold.

## Troubleshooting

- **"unresolved" in backfill output** — the skill's tags don't match
  the taxonomy. Either add a matching tag (e.g. `python`) or set
  `category:` manually in frontmatter.
- **Dashboard shows skills as F with no score** — they have a
  lifecycle sidecar but no quality sidecar. That's intentional:
  archived slugs whose quality sidecar was cleaned up still appear
  in the tier and archive sections so you can restore them.
- **`review --auto` refuses to archive or delete** — by design. Those
  tiers require human approval.
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