skill-system-router

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill System Router

Skill System 路由

You are the Router. This skill teaches you how to orchestrate other skills.

你是路由管理者。这项技能会教你如何编排其他技能。

How It Works

工作原理

User goal → Read skills-index.json → Match capabilities → Read skill manifest
→ Check policy → Execute entrypoints → Parse JSON output → Decide next step → Log

用户目标 → 读取skills-index.json → 匹配能力 → 读取技能清单
→ 检查策略 → 执行入口点 → 解析JSON输出 → 决定下一步 → 记录日志

Step 0: Bootstrap (First Run Only)

步骤0：初始化（仅首次运行）

Check if the project's AGENTS.md contains

## Skill System

If found: skip to Step 1 (already bootstrapped).
If not found: follow
```
scripts/bootstrap.md
```
to embed the skill system into this project.

This only runs once per project. After bootstrap, every future session reads AGENTS.md and knows about the skill system automatically.

检查项目的AGENTS.md文件中是否包含

## Skill System

。

若存在：跳至步骤1（已完成初始化）。
若不存在：按照
```
scripts/bootstrap.md
```
中的说明将技能系统嵌入当前项目。

每个项目仅需执行一次初始化。完成后，后续所有会话都会自动读取AGENTS.md并识别技能系统。

Step 1: Discover Skills

步骤1：发现技能

Read

skills-index.json

(in the skills root directory, sibling to skill folders) to see available capabilities.

The index maps capabilities → skills and lists each skill's operations with descriptions and input params. Match the user's goal to capabilities. If no match, check if the goal can be decomposed into sub-capabilities.

skills-index.json

is missing or stale, regenerate it:

bash

bash "<this-skill-dir>/scripts/build-index.sh"

powershell

powershell.exe -NoProfile -ExecutionPolicy Bypass -File "<this-skill-dir>\scripts\build-index.ps1"

读取

skills-index.json

（位于技能根目录，与技能文件夹同级）查看可用能力。

该索引将能力映射到技能，并列出每个技能的操作、描述及输入参数。将用户目标与能力进行匹配。若无匹配项，检查目标是否可拆分为子能力。

若

skills-index.json

缺失或已过期，重新生成它：

bash

bash "<this-skill-dir>/scripts/build-index.sh"

powershell

powershell.exe -NoProfile -ExecutionPolicy Bypass -File "<this-skill-dir>\scripts\build-index.ps1"

Step 2: Read Skill Manifest

步骤2：读取技能清单

Open the target skill's

SKILL.md

and find the

`skill-manifest`

fenced block. This gives you:

operations: what the skill can do, with input/output schemas
effects: side effects (used for policy check)
entrypoints: OS-specific commands to run

Full manifest spec:

references/manifest-spec.md

打开目标技能的

SKILL.md

文件，找到

`skill-manifest`

代码块。其中包含：

operations：技能可执行的操作，包含输入/输出 schema
effects：副作用（用于策略检查）
entrypoints：特定操作系统的运行命令

完整清单规范：

references/manifest-spec.md

Step 3: Check Policy

步骤3：检查策略

Before executing, verify the skill's declared

effects

against the active policy profile:

sql

SELECT allowed_effects FROM skill_system.policy_profiles WHERE name = 'dev';

ALL effects in
```
allowed_effects
```
→ proceed
ANY effect NOT in
```
allowed_effects
```
→ ask the user before proceeding
No policy profile exists → ask the user

Standard effects:

db.read

db.write

proc.exec

fs.read

fs.write

net.fetch

git.read

git.write

执行前，验证技能声明的

effects

是否符合当前生效的策略配置：

sql

SELECT allowed_effects FROM skill_system.policy_profiles WHERE name = 'dev';

所有
```
effects
```
均在
```
allowed_effects
```
中 → 继续执行
存在任何不在
```
allowed_effects
```
中的
```
effects
```
→ 执行前询问用户
无策略配置存在 → 询问用户

标准副作用：

db.read

db.write

proc.exec

fs.read

fs.write

net.fetch

git.read

git.write

Step 4: Execute

步骤4：执行操作

Determine OS:
```
OS
```
env =
```
Windows_NT
```
→ use
```
windows
```
entrypoint, otherwise
```
unix
```
Read the operation's
```
entrypoints
```
for your OS
Substitute
```
{param}
```
placeholders with actual values
Set cwd to the skill's directory
Run the command
Parse the last line of stdout as JSON — this is the result

Exit code ≠ 0 or last line not JSON → operation failed.

确定操作系统：
```
OS
```
环境变量为
```
Windows_NT
```
→ 使用
```
windows
```
入口点，否则使用
```
unix
```
入口点
读取当前操作系统对应的操作
```
entrypoints
```
将
```
{param}
```
占位符替换为实际值
将工作目录设置为技能所在目录
运行命令
将标准输出的最后一行解析为JSON —— 这就是执行结果

退出码≠0或最后一行不是JSON → 操作执行失败。

Step 5: Chain Operations

步骤5：串联操作

When a goal requires multiple skills/operations:

Execute first operation → parse JSON output
Use output values as input to the next operation (you decide the mapping)
Repeat until goal is met

You are intelligent — adapt based on intermediate results. This is better than a fixed pipeline because you can handle errors, skip unnecessary steps, and make contextual decisions.

当目标需要多个技能/操作时：

执行第一个操作 → 解析JSON输出
将输出值作为下一个操作的输入（由你决定映射关系）
重复直至完成目标

你具备自主决策能力——可根据中间结果调整流程。这比固定流水线更灵活，因为你可以处理错误、跳过不必要的步骤并做出上下文相关的决策。

Step 6: Log (Observability)

步骤6：日志记录（可观测性）

After non-trivial workflows, log for observability:

sql

INSERT INTO skill_system.runs(task_spec_id, status, started_at, effective_policy)
VALUES (NULL, 'running', NOW(), '{}'::jsonb) RETURNING id;

INSERT INTO skill_system.run_events(run_id, level, event_type, payload)
VALUES (<run_id>, 'info', 'step_completed',
  jsonb_build_object('skill', '<id>', 'operation', '<op>', 'status', '<ok|error>', 'duration_ms', <ms>));

UPDATE skill_system.runs SET status='succeeded', ended_at=NOW(),
  metrics=jsonb_build_object('steps', <n>, 'duration_ms', <ms>) WHERE id=<run_id>;

Skip logging for simple single-operation calls.

完成复杂工作流后，记录日志以实现可观测性：

sql

INSERT INTO skill_system.runs(task_spec_id, status, started_at, effective_policy)
VALUES (NULL, 'running', NOW(), '{}'::jsonb) RETURNING id;

INSERT INTO skill_system.run_events(run_id, level, event_type, payload)
VALUES (<run_id>, 'info', 'step_completed',
  jsonb_build_object('skill', '<id>', 'operation', '<op>', 'status', '<ok|error>', 'duration_ms', <ms>));

UPDATE skill_system.runs SET status='succeeded', ended_at=NOW(),
  metrics=jsonb_build_object('steps', <n>, 'duration_ms', <ms>) WHERE id=<run_id>;

简单的单操作调用可跳过日志记录。

Insight Suggestion

洞察建议

After completing a non-trivial session (multi-step work, significant discussion, or debugging), consider suggesting an insight pass:

"Want me to run an insight pass on this session? It helps me learn your preferences for better collaboration next time."

This is a lightweight, optional prompt. Only suggest when:

The session had meaningful interaction (not a single-line fix)
The user hasn't already triggered insight extraction recently
The session contained signals worth capturing (frustration, satisfaction, style preferences)

If the user agrees, load

skill-system-insight

and follow

scripts/extract-facets.md

完成复杂会话后（多步骤工作、重要讨论或调试），可考虑建议执行洞察分析：

"是否需要我对本次会话执行洞察分析？这有助于我了解你的偏好，以便未来更好地协作。"

这是一个轻量级的可选提示。仅在以下场景中建议：

会话包含有意义的交互（而非单行修复）
用户近期未触发过洞察提取
会话包含值得捕捉的信号（如不满、满意、风格偏好）

若用户同意，加载

skill-system-insight

并按照

scripts/extract-facets.md

中的说明操作。

Common Patterns

常见模式

Single operation: Goal → index lookup → execute one entrypoint → return result

Multi-step chain: Goal → op1.search → parse results → op2.store(using results) → done

Cross-skill chain: Goal → skill-A.op1 → use output as context → skill-B.op2 → rebuild index → done

单操作： 目标 → 索引查找 → 执行一个入口点 → 返回结果

多步骤串联： 目标 → op1.search → 解析结果 → op2.store（使用结果） → 完成

跨技能串联： 目标 → skill-A.op1 → 将输出作为上下文 → skill-B.op2 → 重建索引 → 完成

Database

数据库

Uses tables from

skill-system-postgres

```
skill_system.policy_profiles
```
— effect allowlists
```
skill_system.runs
```
— execution records
```
skill_system.run_events
```
— step-level logs

skill

{
  "schema_version": "2.0",
  "id": "skill-system-router",
  "version": "1.0.0",
  "capabilities": ["skill-discover", "skill-execute", "skill-chain", "index-rebuild"],
  "effects": ["fs.read", "fs.write", "proc.exec", "db.read", "db.write"],
  "operations": {
    "rebuild-index": {
      "description": "Regenerate skills-index.json by scanning all skill manifests.",
      "input": {},
      "output": {
        "description": "Index file path and skill count",
        "fields": { "file": "string", "skill_count": "integer" }
      },
      "entrypoints": {
        "unix": ["bash", "scripts/build-index.sh"],
        "windows": ["powershell.exe", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "scripts\\build-index.ps1"]
      }
    },
    "bootstrap": {
      "description": "Embed skill-system into project AGENTS.md (first run only).",
      "input": {},
      "output": {
        "description": "Path to updated AGENTS.md",
        "fields": { "agents_md_path": "string" }
      },
      "entrypoints": {
        "agent": "Follow scripts/bootstrap.md procedure"
      }
    }
  },
  "stdout_contract": {
    "last_line_json": false,
    "note": "rebuild-index prints summary to stdout; bootstrap is agent-executed."
  }
}

使用

skill-system-postgres

中的表：

```
skill_system.policy_profiles
```
—— 副作用允许列表
```
skill_system.runs
```
—— 执行记录
```
skill_system.run_events
```
—— 步骤级日志

skill

{
  "schema_version": "2.0",
  "id": "skill-system-router",
  "version": "1.0.0",
  "capabilities": ["skill-discover", "skill-execute", "skill-chain", "index-rebuild"],
  "effects": ["fs.read", "fs.write", "proc.exec", "db.read", "db.write"],
  "operations": {
    "rebuild-index": {
      "description": "Regenerate skills-index.json by scanning all skill manifests.",
      "input": {},
      "output": {
        "description": "Index file path and skill count",
        "fields": { "file": "string", "skill_count": "integer" }
      },
      "entrypoints": {
        "unix": ["bash", "scripts/build-index.sh"],
        "windows": ["powershell.exe", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "scripts\\build-index.ps1"]
      }
    },
    "bootstrap": {
      "description": "Embed skill-system into project AGENTS.md (first run only).",
      "input": {},
      "output": {
        "description": "Path to updated AGENTS.md",
        "fields": { "agents_md_path": "string" }
      },
      "entrypoints": {
        "agent": "Follow scripts/bootstrap.md procedure"
      }
    }
  },
  "stdout_contract": {
    "last_line_json": false,
    "note": "rebuild-index prints summary to stdout; bootstrap is agent-executed."
  }
}