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

skills-health.md

View on GitHub
# Skill health dashboard

[`src/ctx/adapters/claude_code/skill_health.py`](https://github.com/stevesolun/ctx/blob/main/src/ctx/adapters/claude_code/skill_health.py)
scans `~/.claude/skills/` and `~/.claude/agents/` for structural and
catalog issues, then produces a JSON or human-readable dashboard. It
also self-heals catalog drift — without ever modifying a SKILL.md.

## What it checks

For each skill (`~/.claude/skills/<name>/SKILL.md`) and each agent
(`~/.claude/agents/<name>.md`):

| Code | Severity | Condition |
|---|---|---|
| `missing-file` | error | Skill directory has no SKILL.md |
| `unreadable` | error | File exists but can't be decoded as UTF-8 |
| `no-frontmatter` | error | Missing or malformed `---` YAML fence |
| `frontmatter-missing-name` | error | Frontmatter has no `name:` field |
| `frontmatter-missing-description` | warning | Missing `description:` (router relevance suffers) |
| `empty-body` | error | Fewer than `min_body_lines` non-blank lines |
| `over-threshold` | warning | Line count exceeds `skill_transformer.line_threshold`; the packaged default is 180 and users can override it in `~/.claude/skill-system-config.json` |

## Drift detection

`DriftReport` cross-references three sources:

- on-disk entities (skills + agents),
- `~/.claude/skill-manifest.json` → `load[].skill` entries,
- `~/.claude/pending-skills.json` → `graph_suggestions[].name` and
  `unmatched_signals[]`.

Anything in the manifest or pending file that doesn't exist on disk
becomes an *orphan*. Orphans are the only thing `heal` is allowed to
touch.

## Self-healing

```bash
python -m ctx.adapters.claude_code.skill_health heal
```

- drops orphaned entries from `skill-manifest.json`
- drops orphaned entries from `pending-skills.json`
- writes atomically (`tempfile.mkstemp` + `os.replace`)
- never modifies SKILL.md files or agent .md files

If nothing needs healing, prints `[heal] nothing to do.` and exits 0.

## CLI

```bash
# Emit a full JSON report
python -m ctx.adapters.claude_code.skill_health scan

# Pretty dashboard
python -m ctx.adapters.claude_code.skill_health dashboard

# CI gate: exit 2 if any error-severity issue or drift is present
python -m ctx.adapters.claude_code.skill_health check --strict

# Apply safe autofixes to manifest + pending
python -m ctx.adapters.claude_code.skill_health heal
```

## Data model

```python
@dataclass(frozen=True)
class Issue:
    code: str
    severity: str      # "warning" | "error"
    message: str

@dataclass(frozen=True)
class EntityHealth:
    name: str
    kind: str          # "skill" | "agent"
    path: str
    lines: int
    has_frontmatter: bool
    issues: tuple[Issue, ...] = ()

@dataclass(frozen=True)
class DriftReport:
    orphaned_manifest: tuple[str, ...] = ()
    orphaned_pending: tuple[str, ...] = ()

@dataclass(frozen=True)
class HealthReport:
    generated_at: float
    entities: tuple[EntityHealth, ...]
    drift: DriftReport
    totals: dict[str, int]
```

`HealthReport.has_errors` is true when any entity has severity `error`
*or* drift is non-empty — that's the single predicate behind
`check --strict`'s exit code.

## Related

- [Memory anchoring](memory-anchor.md) — dead-reference detection for
  auto-memory notes.
- `src/skill_quality.py` (v0.5.0+) — the four-signal quality scorer
  (telemetry 0.40, intake 0.20, graph 0.25, routing 0.15) that writes
  per-entity sidecars and surfaces A/B/C/D/F grades. The `skill_health`
  CLI above focuses on *structural* correctness; `skill_quality`
  focuses on *behavioral* quality over time.
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: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated 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: 323kUpdated Claude CodeCodexVerifiedInstall