Skip to content
Back to search

Skill-Routing-Kit

Skill Routing Kit 是一个本地优先的 Codex 插件,用来提升 skill 和插件的命中率,同时避免引入缓慢、强侵入的运行时路由层。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/juew--skill-routing-kit/badge.svg)](/listings/juew--skill-routing-kit)

HTML

<a href="/listings/juew--skill-routing-kit"><img src="/api/listings/juew--skill-routing-kit/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 197 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="assets/logo.png" alt="Skill Routing Kit logo" width="160" />
  3. </p>
  4. <h1 align="center">Skill Routing Kit</h1>
  5. <p align="center">
  6. Make Codex pick the right skill or plugin more often.
  7. </p>
  8. <p align="center">
  9. <a href="README.zh-CN.md">中文说明</a>
  10. ·
  11. <a href="README.en.md">Full English docs</a>
  12. ·
  13. <a href="docs/demo.md">Demo</a>
  14. ·
  15. <a href="docs/release-v0.1.0.md">Release notes</a>
  16. </p>
  17. <p align="center">
  18. <img alt="Codex plugin" src="https://img.shields.io/badge/Codex-plugin-22D3EE">
  19. <img alt="Local first" src="https://img.shields.io/badge/local--first-no%20network%20by%20default-10B981">
  20. <img alt="CI" src="https://github.com/juew/Skill-Routing-Kit/actions/workflows/ci.yml/badge.svg">
  21. <img alt="License" src="https://img.shields.io/badge/license-MIT-111827">
  22. </p>
  23. ## Why This Exists
  24. Codex can have dozens of skills and plugins installed, but the correct one does not always trigger.
  25. That creates a quiet productivity tax:
  26. - a PDF input gets mistaken for the final artifact;
  27. - a routing/debugging question gets handled by the wrong domain skill;
  28. - connector plugins are considered even when the user's work is local;
  29. - new skills are installed, but nobody remembers when to use them.
  30. Skill Routing Kit adds a small local-first routing layer for Codex. It helps Codex answer:
  31. ```text
  32. What kind of task is this?
  33. Where is the source of truth?
  34. What is the final artifact?
  35. Which skill should be primary?
  36. Which plugin is only a helper?
  37. When should a tempting skill not be used?
  38. ```
  39. ## What You Get
  40. - `skill-router`: a Codex skill for diagnosing skill/plugin routing decisions.
  41. - Local registry: a JSON capability index with categories, use cases, negative examples, and provenance.
  42. - Routing guard: an `AGENTS.md` snippet that makes routing a quiet default behavior.
  43. - Diagnostic scripts: route a request, refresh the registry, and check stale or broken entries.
  44. - Local-first safety: no background scan, no telemetry, no connector content reads, no network by default.
  45. ## 30-Second Install
  46. If you use Codex, ask it to install the plugin for you:
  47. ```text
  48. Please install the Skill Routing Kit plugin from https://github.com/juew/Skill-Routing-Kit. Install the plugin source globally at ~/plugins/skill-routing-kit, register it in ~/.agents/plugins/marketplace.json, run codex plugin add skill-routing-kit@personal, and enable the routing guard globally in ~/.codex/AGENTS.md. Do not install it into the current project. Do not ask me to create directories manually; use the repository installer and verify the plugin after installation.
  49. ```
  50. Or run one command:
  51. ```bash
  52. /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/juew/Skill-Routing-Kit/main/scripts/install.sh)" -- --install-agents --codex-add
  53. ```
  54. The installer creates directories, updates your personal Codex marketplace, enables the plugin, and backs up older local copies.
  55. ## Before And After
  56. ### Routing Diagnostic
  57. ```bash
  58. python3 scripts/route_request.py "为什么 pdf skill 没有命中这个请求"
  59. ```
  60. Expected result:
  61. ```text
  62. Recommended skill/plugin:
  63. - Skill Router (skill-router)
  64. Helper skills/plugins:
  65. - PDF (pdf)
  66. Why:
  67. - routing diagnostic request prefers the skill-router capability
  68. - local-first preference
  69. ```
  70. ### Final Artifact Routing
  71. ```bash
  72. python3 scripts/route_request.py "把这个 PDF 整理成一份 PPT"
  73. ```
  74. Expected result:
  75. ```text
  76. Recommended skill/plugin:
  77. - Presentations (presentations)
  78. Helper skills/plugins:
  79. - PDF (pdf)
  80. ```
  81. The final artifact is the presentation. The PDF skill is useful context, not the primary route.
  82. More examples: [docs/demo.md](docs/demo.md)
  83. ## How It Works
  84. Skill Routing Kit turns skill/plugin selection into a lightweight recall-and-rerank loop.
  85. ```mermaid
  86. flowchart LR
  87. A["User request"] --> B["Routing guard"]
  88. B --> C["Classify task, source, artifact, process"]
  89. C --> D["Recall candidates from registry"]
  90. D --> E["Rerank by final artifact, source, action, risk"]
  91. E --> F["Use primary skill/plugin"]
  92. E --> G["Keep helper skills contextual"]
  93. ```
  94. The methodology is simple:
  95. - describe **when to use** each capability;
  96. - classify capabilities into layered routing categories such as `process`, `source`, `artifact`, `domain`, and `risk`;
  97. - describe **when not to use** each capability with negative examples;
  98. - recall broad candidates first, then rerank by final artifact, source, task action, and permission risk.
  99. ## Safety Model
  100. This project is intentionally conservative.
  101. - It reads local `SKILL.md`, `plugin.json`, and registry metadata.
  102. - It does not read Gmail, Slack, Notion, Drive, or other connector content.
  103. - It does not check connector authorization.
  104. - It does not install hooks, telemetry, daemons, or background scanners.
  105. - It can be removed by deleting the `AGENTS.md` block and uninstalling the plugin.
  106. ## Common Commands
  107. ```bash
  108. # Validate the plugin
  109. python3 /Users/zhonghao/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .
  110. # Run tests
  111. python3 -B -m unittest discover -s tests
  112. # Route one request
  113. python3 scripts/route_request.py "帮我把这个 PDF 做成 PPT 并保留版式"
  114. # Check registry health
  115. python3 scripts/route_request.py --check-registry
  116. # Refresh generated registry
  117. python3 scripts/build_registry.py --yes
  118. ```
  119. ## Who Should Star This
  120. Star this repo if you are:
  121. - building Codex skills or plugins;
  122. - using many AI agent capabilities and seeing missed triggers;
  123. - designing local-first agent workflows;
  124. - maintaining a team skill library;
  125. - interested in explainable routing for AI tools.
  126. ## Roadmap
  127. - Registry diff after skill/plugin install or removal.
  128. - Better negative-example authoring tools.
  129. - Optional embedding-based reranker.
  130. - Route quality evaluation suite.
  131. - UI screenshots and short demo GIF.
  132. - More connector-aware but still local-first policy cards.
  133. ## Documentation
  134. - [Chinese README](README.zh-CN.md)
  135. - [Full English documentation](README.en.md)
  136. - [Demo scenarios](docs/demo.md)
  137. - [Release notes](docs/release-v0.1.0.md)
  138. - [Promotion kit](docs/promotion-kit.md)
  139. - [Contributing guide](CONTRIBUTING.md)
  140. - [Changelog](CHANGELOG.md)
  141. ## License
  142. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.