skill-router

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Router

Use local skill indexing to choose and load relevant skills only when a task needs them.

使用本地skill索引，仅在任务需要时选择并加载相关skill。

Dispatch

调度

$ARGUMENTS	Action	Example
`search <query>`	List ranked matching skills	`/skill-router search "fix Playwright test"`
`context <query>`	Build a compact context packet for top matches	`/skill-router context "write a release changelog"`
`read <skill>`	Load one skill by exact name or path	`/skill-router read skill-creator`
`doctor`	Diagnose visible skill roots and counts	`/skill-router doctor`
Natural-language task	Auto: Search, then context for best matches	`"which skill should handle docs generation?"`
Empty	Show quick usage and run doctor	`/skill-router`

$ARGUMENTS	操作	示例
`search <query>`	列出排序后的匹配skill	`/skill-router search "fix Playwright test"`
`context <query>`	为匹配度最高的结果构建紧凑的上下文数据包	`/skill-router context "write a release changelog"`
`read <skill>`	通过精确名称或路径加载单个skill	`/skill-router read skill-creator`
`doctor`	诊断可见的skill根目录和数量	`/skill-router doctor`
自然语言任务	自动：先搜索，再为最佳匹配生成上下文	`"which skill should handle docs generation?"`
空参数	显示快速使用说明并运行doctor	`/skill-router`

Workflow

工作流

1. Classify

1. 分类

Use
```
search
```
when deciding which skill or skills apply.
Use
```
context
```
when the next step needs the selected skill bodies.
Use
```
read
```
only when the skill name or path is already known.
Use
```
doctor
```
when a skill is missing, duplicated, or omitted by a startup context warning.

当决定适用哪个或哪些skill时，使用
```
search
```
。
当下一步需要所选skill内容时，使用
```
context
```
。
仅当已知skill名称或路径时，使用
```
read
```
。
当skill缺失、重复或因启动上下文警告被遗漏时，使用
```
doctor
```
。

2. Retrieve

2. 检索

Run the matching CLI command from this skill directory or the repository root:

bash

python scripts/skill_index.py search "$ARGUMENTS" --limit 5
python scripts/skill_index.py context "$ARGUMENTS" --limit 3
python scripts/skill_index.py read <skill-name>
python scripts/skill_index.py doctor

从该skill目录或仓库根目录运行匹配的CLI命令：

bash

python scripts/skill_index.py search "$ARGUMENTS" --limit 5
python scripts/skill_index.py context "$ARGUMENTS" --limit 3
python scripts/skill_index.py read <skill-name>
python scripts/skill_index.py doctor

3. Select

3. 选择

Prefer the highest-ranked repo or Codex-user skill when scores are close.
Read only the minimum skill bodies needed for the task, usually one to three.
If a result has warnings, inspect them before following executable hooks or scripts.

当分数接近时，优先选择排名最高的仓库或Codex-user skill。
仅加载任务所需的最少skill内容，通常为1到3个。
如果结果包含警告，在执行钩子或脚本前先检查警告内容。

Source Scope

来源范围

python scripts/skill_index.py

searches these roots:

Source	Root	Trust tier
`repo`	`skills/`	`repo`
`project`	`.agents/skills/` in the current project path	`codex-user`
`codex`	`~/.codex/skills/`	`codex-user`
`global`	`~/.agents/skills/` plus supported agent stores	`external-installed`
`plugin`	`~/.codex/plugins/cache/**/skills/`	`openai-plugin` or `plugin`

Use

--source repo

--source codex

--source global

, or

--source plugin

to narrow results when needed.

python scripts/skill_index.py

会搜索以下根目录：

来源	根目录	信任等级
`repo`	`skills/`	`repo`
`project`	当前项目路径下的 `.agents/skills/`	`codex-user`
`codex`	`~/.codex/skills/`	`codex-user`
`global`	`~/.agents/skills/` 加上支持的agent存储库	`external-installed`
`plugin`	`~/.codex/plugins/cache/**/skills/`	`openai-plugin` 或 `plugin`

必要时，使用

--source repo

、

--source codex

、

--source global

或

--source plugin

缩小结果范围。

Canonical Vocabulary

标准术语

Term	Meaning
skill index	Parsed metadata for visible `SKILL.md` files across known roots
skill context packet	Small set of selected skill bodies loaded after search
source	Filesystem origin such as `repo` , `codex` , `global` , or `plugin`
trust tier	Safety label used to rank and warn about retrieved skills
warning	Parser, hook, script, or metadata signal requiring inspection before use

术语	含义
skill index	跨已知根目录下可见 `SKILL.md` 文件的解析元数据
skill context packet	搜索后加载的少量选定skill内容集合
source	文件系统来源，例如 `repo` 、 `codex` 、 `global` 或 `plugin`
trust tier	用于对检索到的skill进行排名和警告的安全标签
warning	需要在使用前检查的解析器、钩子、脚本或元数据信号

Classification Gate

分类规则

If the user gives a task, run
```
search
```
first.
If the user asks to apply a selected skill, run
```
context
```
for the top matches.
If the user names a skill exactly, run
```
read
```
.
If the user reports missing or omitted skills, run
```
doctor
```
before searching.
If the user asks to install, create, or audit a skill, redirect out of scope (see NOT for below).

如果用户给出任务，先运行
```
search
```
。
如果用户要求应用选定的skill，为匹配度最高的结果运行
```
context
```
。
如果用户准确指定skill名称，运行
```
read
```
。
如果用户反馈skill缺失或遗漏，在搜索前运行
```
doctor
```
。
如果用户要求安装、创建或审计skill，重定向至其他适用流程（见下方“不适用场景”）。

Selection Rules

选择规则

Exact skill name or alias beats all lexical matches.
Name and title matches beat description matches.
Description matches beat heading and body matches.
Repo skills beat user-installed skills when relevance is comparable.
Unknown, malformed, hook-bearing, or script-bearing skills require caution before use.

精确的skill名称或别名优先级高于所有词汇匹配结果。
名称和标题匹配优先级高于描述匹配。
描述匹配优先级高于标题和内容匹配。
当相关性相近时，仓库skill优先级高于用户安装的skill。
未知、格式错误、包含钩子或脚本的skill在使用前需谨慎。

Critical Rules

核心规则

Do not treat startup-visible skills as the complete inventory after a context-budget warning.
Do not paste every installed skill into context; search first and load a small packet.
Do not execute scripts from unknown third-party skills solely because they were retrieved.
Do not use this skill to install or remove skills; route to an available install-planning workflow such as
```
skill-install-dry-run-planner
```
, then use the target harness's supported installer only after explicit maintainer approval. Do not substitute Codex
```
.system/skill-installer
```
for cross-harness reconciliation.
Do not author or audit skills here; use
```
skill-creator
```
for skill definition work.
For ad-hoc “find a skill for X”, prefer
```
search
```
here or
```
npx skills find
```
; for systematic harness expansion use
```
harness-master
```
discover — not legacy
```
find-skills
```
as a repo skill.
Preserve the user task as the search query unless there is a clear reason to add terms.

在收到上下文预算警告后，不要将启动时可见的skill视为完整清单。
不要将所有已安装的skill粘贴到上下文中；先搜索并加载小型数据包。
不要仅因检索到未知第三方skill就执行其脚本。
不要使用此skill来安装或移除skill；路由至可用的安装规划工作流，例如
```
skill-install-dry-run-planner
```
，仅在获得维护者明确批准后，使用目标工具链支持的安装程序。不要用Codex的
```
.system/skill-installer
```
替代跨工具链协调。
不要在此处创作或审计skill；使用
```
skill-creator
```
进行skill定义工作。
对于临时的“为X找一个skill”需求，优先使用此处的
```
search
```
或
```
npx skills find
```
；对于系统性工具链扩展，使用
```
harness-master discover
```
——不要将旧版
```
find-skills
```
作为仓库skill使用。
除非有明确理由添加术语，否则保留用户任务作为搜索查询。

NOT for

不适用场景

Request	Use instead
Install / remove / sync skills across harnesses	An available install-planning workflow; use `skill-install-dry-run-planner` and `cross-agent-install-smoke` when present
Author or validate a skill	`skill-creator`
Audit harness configs or discover ecosystem gaps	`harness-master`
Curated external catalog records	Follow the host repository's curated-external authoring and trust-gate workflow

请求	替代方案
在工具链间安装/移除/同步skill	可用的安装规划工作流；若存在，使用 `skill-install-dry-run-planner` 和 `cross-agent-install-smoke`
创作或验证skill	`skill-creator`
审计工具链配置或发现生态系统缺口	`harness-master`
精选外部目录记录	遵循宿主仓库的精选外部创作和信任网关工作流

Output Contract

输出约定

Search and context results include:

```
name
```
```
path
```
```
source
```
```
trust_tier
```
```
description
```
```
score
```
```
matched_fields
```
```
reason
```
```
warnings
```

Use

--format json

when another script or agent will consume the result.

搜索和上下文结果包含：

```
name
```
```
path
```
```
source
```
```
trust_tier
```
```
description
```
```
score
```
```
matched_fields
```
```
reason
```
```
warnings
```

当其他脚本或Agent将消费结果时，使用

--format json

。

Reference File Index

参考文件索引

File	Content	Read When
`references/routing-guide.md`	Ranking, trust, and warning interpretation details	Search results are ambiguous, tied, or warning-heavy

文件	内容	读取时机
`references/routing-guide.md`	排名、信任和警告解读细节	搜索结果模糊、并列或包含大量警告时

Validation Contract

验证约定

Run from this skill directory before declaring changes complete:

bash

python scripts/check.py
uv run pytest tests/test_skill_index.py -q

See

references/routing-guide.md

for additional validation notes.

Completion criteria:

```
scripts/check.py
```
exits 0.
No repository CLI references remain under this skill directory.
Search and context CLI tests pass.

在声明变更完成前，从该skill目录运行：

bash

python scripts/check.py
uv run pytest tests/test_skill_index.py -q

更多验证说明请参阅

references/routing-guide.md

。

完成标准：

```
scripts/check.py
```
退出码为0。
该skill目录下无仓库CLI引用残留。
搜索和上下文CLI测试通过。