Skill Router

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, API model, or external loop adapter. 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/                        # Host adapters + 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": "python -m 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.