skill-router
- Repo stars 365
- Author updated Live
- Author repo ctx
- Domain
- Documentation
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 88 / 100 · community maintained
- Author / version / license
- @stevesolun · no license declared
- Token usage
- Lean
- Setup complexity
- Manual integration
- External API key
- Not required
- Operating systems
- Docker
- Runtime requirements
- Docker
- Permissions
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools,默认拥有全部工具权限。
---
name: skill-router
description: Repo-aware recommendation manager for ctx. Scans the active repository, identifies stack and wor…
category: documentation
runtime: Docker
---
# skill-router output preview
## PART A: Task fit
- Use case: 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..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “Scope / Problem / Architecture” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “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.”.
- **02** When the source has headings, the agent prioritizes “Scope / Problem / Architecture” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
## Running Rules
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options. The source does not require a stable slash command. After installation, invoke the skill by name and describe the task.
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files, run shell commands.
Start with a small task and check whether the result follows “Scope / Problem / Architecture”. Inspect diffs, logs, previews, or tests before expanding scope.
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: skill-router
description: Repo-aware recommendation manager for ctx. Scans the active repository, identifies stack and wor…
category: documentation
source: stevesolun/ctx
---
# skill-router
## When to use
- Repo-aware recommendation manager for ctx. Scans the active repository, identifies stack and workflow signals, recomme…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “Scope / Problem / Architecture” and keep inference separate from source facts.
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies. The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "skill-router" {
input -> user goal + target files + boundaries + acceptance criteria
context -> Scope / Problem / Architecture
rules -> SKILL.md triggers / order / output contract
runtime -> Docker | read files, write/modify files, run shell commands | mostly runs locally
guardrails -> usually needs no extra API key + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
} 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:
- Scanner - analyzes a repo and produces stack/task evidence.
- Resolver - scores graph/wiki entities and emits a capped manifest.
- Wiki/graph - persistent catalog of entities, usage, quality, and links.
Startup Flow
- Read the shipped graph/wiki metadata and local user overrides.
- Run
ctx-scan-repo --repo . --recommendfor the active repo. - Resolve a load/unload manifest with the shared recommendation engine.
- Present changes with reasons and require confirmation unless the user enabled automatic mode.
- 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
- Start with filenames and config files. Read source only when needed to disambiguate.
- Do not include speculative signals below the configured confidence floor.
- Skip generated/vendor directories such as
.git,node_modules,__pycache__,venv, and.venv. - Keep initial scans bounded for large repos.
- 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:
- Search the shipped graph/wiki first.
- Use additional sources only when the local graph is missing or stale.
- Deduplicate before adding.
- If an entity exists, emit an update review instead of replacing it.
- Run security checks before promotion.
- 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.
- Read wiki orientation and local overrides.
- Scan the target repo.
- Save the scan result.
- Resolve load/unload recommendations.
- Present reasons, scores, and install/update commands.
- Apply only after confirmation unless configured otherwise.
- 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:
- Search graph/wiki entity pages by tags and text.
- Use
find-skillsand configured sources for remote freshness when needed. - Show status, score, source, and risk notes.
- Suggest install/update commands, not silent installs.
- 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_loadand user rejection history.
Decide Fit First
Design Intent
How To Use It
Boundaries And Review