skill-router

name	skill-router
description	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 and then attach to the same recommendation layer.

Skill Router

Scan a repo. Know what the current work needs. Recommend only that. Keep the wiki and graph as the durable catalog behind the decision.

Scope

The router manages runtime recommendations for:

• skills
• agents
• MCP servers

Harnesses are separate catalog entities. They are recommended when a user wants to run ctx with a non-Claude-Code host, local model, or API model. Once attached, the harness calls the same skills/agents/MCP recommendation engine.

Problem

Every loaded helper costs tokens, attention, and operational surface area. Most sessions need a small top-scored bundle from the shipped graph, not every entity ctx knows about. Loading too much:

• wastes context on irrelevant instructions,
• causes misfires when a helper matches the wrong task,
• slows the agent loop, and
• creates conflicting instructions.

Architecture

ctx/
|-- src/scan_repo.py                         # Repo scanner -> stack profile
|-- src/ctx/core/resolve/resolve_skills.py   # Profile -> load/unload manifest
|-- src/ctx/core/resolve/recommendations.py  # Shared scoring/ranking engine
|-- src/ctx/adapters/                        # Claude Code hooks + generic tools
|-- src/harness_install.py                   # Custom-model harness install flow
`-- graph/wiki-graph-runtime.tar.gz          # Shipped graph/wiki runtime

The router has three halves:

1. Scanner - analyzes a repo and produces stack/task evidence.
2. Resolver - scores graph/wiki entities and emits a capped manifest.
3. Wiki/graph - persistent catalog of entities, usage, quality, and links.

Startup Flow

1. Read the shipped graph/wiki metadata and local user overrides.
2. Run ctx-scan-repo --repo . --recommend for the active repo.
3. Resolve a load/unload manifest with the shared recommendation engine.
4. Present changes with reasons and require confirmation unless the user enabled automatic mode.
5. Record usage/quality changes after the user accepts or rejects suggestions.

Scanner

The scanner reads repo structure and files to produce a stack profile. Detection is evidence-based: every claim should map to a file, dependency, config value, or import pattern.

Detection Categories

• Languages - file extensions, shebangs, lock files.
• Frameworks and libraries - package manifests, imports, config files.
• Infrastructure and DevOps - Docker, CI/CD, IaC, cloud, Kubernetes.
• Data and storage - databases, migrations, queues, pipelines.
• Documentation and content - MkDocs, Docusaurus, Sphinx, API specs.
• Testing and quality - pytest, Jest, Playwright, Ruff, mypy, TypeScript.
• AI and agent tooling - MCP configs, LangGraph, CrewAI, prompt dirs, model config names.
• Build and package - package managers, build tools, monorepos.

Scanning Rules

1. Start with filenames and config files. Read source only when needed to disambiguate.
2. Do not include speculative signals below the configured confidence floor.
3. Skip generated/vendor directories such as .git, node_modules, __pycache__, venv, and .venv.
4. Keep initial scans bounded for large repos.
5. Redact secret values; only record secret/key names as evidence.

Resolver

The resolver produces a manifest containing the exact helper set to load or unload.

{
  "generated_at": "ISO-8601",
  "repo_path": "/absolute/path",
  "profile_hash": "sha256 of stack profile",
  "load": [
    {
      "name": "fastapi",
      "type": "skill",
      "reason": "FastAPI detected in pyproject.toml dependencies",
      "score": 0.94
    }
  ],
  "unload": [
    {
      "name": "react",
      "type": "skill",
      "reason": "No active frontend signal in the current repo window"
    }
  ],
  "suggestions": [
    {
      "name": "github",
      "type": "mcp",
      "reason": ".github/workflows exists and the repo uses GitHub Actions",
      "install_command": "ctx-mcp-add ..."
    }
  ],
  "warnings": []
}

Ranking Signals

Candidates can be scored by:

• tag/category/subcategory match
• semantic similarity edge weight
• direct wiki links
• source overlap
• type affinity
• usage score
• quality/security score
• user overrides (always_load, never_load)
• configured caps and minimum score gates

Recommendations are capped. ctx should not recommend at all costs; below-threshold candidates should be withheld and the gap should be explained.

Wiki And Graph Contract

The wiki follows a Karpathy-style durable memory pattern: schema, purpose, index, log, lint, review items, and entity pages that are machine-readable.

llm-wiki/
|-- SCHEMA.md
|-- index.md
|-- log.md
|-- raw/
|   |-- scans/
|   `-- external-catalogs/
|-- entities/
|   |-- skills/
|   |-- agents/
|   |-- mcp-servers/
|   `-- harnesses/
|-- concepts/
|-- comparisons/
`-- queries/

Entity pages use YAML frontmatter with at least:

title: Entity Name
type: skill | agent | mcp-server | harness | external-catalog
status: installed | available | deprecated | broken
tags: []
source: local | shipped | github | curated
source_url: ""
path: ""
quality_score: null
usage_score: 0
last_used: null
always_load: false
never_load: false

Entity Sources

Entity sources include shipped skill/MCP/harness sources, GitHub entity repositories, and local user assets. The public reference page is marketplace-registry.md, kept under that filename for backwards-compatible links.

Source rules:

1. Search the shipped graph/wiki first.
2. Use additional sources only when the local graph is missing or stale.
3. Deduplicate before adding.
4. If an entity exists, emit an update review instead of replacing it.
5. Run security checks before promotion.
6. Rebuild and validate graph/wiki artifacts before shipping.

Micro-Skill Gate

Every added or updated skill must pass the configured line-count gate before it is packed into the shipped wiki. The default threshold is 180 lines, read from ctx config. Skills above the threshold are converted into a short orchestrator plus staged reference files. Local .original backups may be preserved for traceability, but packaged runtime archives must omit those backups.

Core Operations

Full Scan

Triggers: repo open, repo switch, ctx-scan-repo --repo . --recommend, or explicit user request.

1. Read wiki orientation and local overrides.
2. Scan the target repo.
3. Save the scan result.
4. Resolve load/unload recommendations.
5. Present reasons, scores, and install/update commands.
6. Apply only after confirmation unless configured otherwise.
7. Record usage and decisions.

Incremental Scan

Triggers: changed config files, new dependencies, new MCP config, new tests, new infrastructure files, or user task change.

If a helper is no longer useful, ctx should suggest unloading it and ask for confirmation. If the user asks to skip unload prompts, ctx should respect that preference.

Manual Override

• "Always load the docker skill" -> set always_load: true.
• "Never load the react skill" -> set never_load: true.
• "Load the terraform skill for this session" -> temporary load.
• "What is loaded?" -> show current manifest with reasons.

Discovery

When the user asks what exists for a task:

1. Search graph/wiki entity pages by tags and text.
2. Use find-skills and configured sources for remote freshness when needed.
3. Show status, score, source, and risk notes.
4. Suggest install/update commands, not silent installs.
5. Log the query.

Maintenance Checks

• Stale installed helpers - used rarely or not used recently.
• Ghost helpers - installed status but missing local path.
• Orphan local helpers - present locally but missing entity page.
• Skill index freshness - shipped skill snapshot older than policy.
• Conflicts - overlapping helpers both marked always_load.
• Usage cold spots - low usage/quality score candidates for unload review.
• Wiki lint - broken links, missing frontmatter, index drift.

Reporting

After a scan, report only actionable details:

Skill Router Report - repo-name
Scanned: YYYY-MM-DD HH:MM

Loaded:
1. fastapi skill - score 0.94 - pyproject.toml dependency
2. github MCP - score 0.91 - GitHub Actions workflows detected

Unload candidates:
1. react skill - no active frontend signal

Suggestions:
1. openapi-generator skill - OpenAPI spec found

Warnings:
None

Configuration

Router behavior is controlled by ctx config and user overrides. Important knobs:

recommendations:
  max_total: 5
  min_score: 0.85
micro_skills:
  max_lines: 180
router:
  auto_scan: true
  auto_apply: false
  ask_before_unload: true

Pitfalls

• Never load all helpers just in case.
• Never replace an existing entity without an update review.
• Never execute external repo scripts while cataloging.
• Never treat conversation history as the source of workflow state.
• Never ship graph/wiki artifacts before validation passes.
• Respect never_load and user rejection history.