内容
# 技能导航
<p align="center">
<strong>为您的代码库找到、审计和安装合适的人工智能代理技能。</strong>
</p>
<p align="center">
<a href="https://www.npmjs.com/package/skillranger"><img src="https://img.shields.io/npm/v/skillranger?color=blue&style=flat-square" alt="npm 版本"></a>
<a href="https://github.com/Narek-Khachikyan/SkillRanger/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="许可证"></a>
<a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen?style=flat-square" alt="Node 版本"></a>
<a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Supported-purple?style=flat-square" alt="MCP 服务器"></a>
<a href="https://github.com/Narek-Khachikyan/SkillRanger/actions/workflows/ci.yml"><img src="https://github.com/Narek-Khachikyan/SkillRanger/actions/workflows/ci.yml/badge.svg" alt="CI 状态"></a>
</p>
---
**公开 MVP / 测试版** · 本地优先 · 命令行界面 + MCP · 零运行时依赖
技能导航扫描您的代码库，检测其技术栈和开发环境，推荐兼容的技能，审计安全风险，并在写入任何内容之前创建可审查的安装计划。
例如，当您要求人工智能代理审查 Next.js 应用程序时，技能导航可以选择相关的 Next.js、可访问性、性能和测试指令，而不是使用通用提示。
## 快速开始
### 1. 在项目中运行设置
技能导航需要 Node.js 20 或更高版本。
```bash
cd your-project
npx -y skillranger@latest setup
```
交互式设置将：
1. 扫描当前代码库；
2. 询问您使用的人工智能代理；
3. 推荐兼容的技能；
4. 显示将安装的内容；
5. 在写入文件之前询问确认。
您可以在排查问题时先运行诊断：
```bash
npx -y skillranger@latest doctor
```
### 2. 通用任务路由器
将任何任务提示路由到最佳、有限的技能集和生命周期运行。在您希望运行安装的技能导航工作流时，以 `@skillranger`、`skillranger` 或 `/sr` 结尾：
```text
审查此 Next.js 应用程序的可访问性并修复关键的键盘导航问题。@skillranger
```
或通过命令行界面：
```bash
# 为以终端触发器结尾的自然语言任务执行命令行界面路由
skillranger task . --intent "Review accessibility and fix critical focus traps @skillranger" --target codex --json
# 在执行前读取强制生命周期指令
skillranger task:read . --router-run <router-run-id> --mandatory-next --expected-read-revision 0 --json
```
> 🌐 **双语自然语言**：提示可以以英语、俄语或混合术语编写（例如 *"Создай современный сайт по Bleach с плавной анимацией @skillranger"*）。匹配使用所有者范围的领域包路由词汇表 100% 确定。注意：当您希望运行安装的技能导航工作流时，请以 `@skillranger`、`skillranger` 或 `/sr` 结尾。
设置完成后，在同一代码库中打开 Codex、Claude Code、Cursor、OpenCode 或 Gemini CLI，并像平常一样编写任务：
```text
审查此 Next.js 应用程序的可访问性并修复关键的键盘导航问题。@skillranger
```
技能导航的管理代理上下文在任务提示以 `@skillranger`、`skillranger` 或 `/sr` 结尾时激活，指导代理哪些已安装的技能指令必须在实施前读取。
您不需要手动运行高级生命周期命令进行正常的交互式使用。
### 设置内容
对于代码库范围的 Codex 设置，技能导航可以创建或更新：
- `.agents/skills/<skill>/` — 代码库本地技能包；
- `AGENTS.md` — 有限的技能导航管理上下文块；
- `skillranger.lock.json` — 已安装的版本、校验和、目标和审计元数据。
技能导航安装静态指令。它不调用模型或在不显式的情况下修改您的应用程序代码。
## 为什么选择技能导航？
| 功能 | 含义 |
| :--- | :--- |
| **上下文感知推荐** | 技能从代码库证据和用户任务中选择，而不是从固定的全局列表中选择。 |
| **无盲安装** | 在应用建议之前审查建议、审计结果和计划的文件更改。 |
| **确定性路由** | 英文、俄文和混合语言任务在无需外部 LLM 路由调用的情况下匹配。 |
| **锁定文件完整性** | 已安装的版本、校验和、目标代理和审计数据在 `skillranger.lock.json` 中跟踪。 |
| **本地优先操作** | 捆绑的发现和推荐无需 API 密钥或网络令牌。 |
| **多个代理目标** | 一个项目可以为 Codex、Claude Code、Cursor、OpenCode、Gemini CLI 或 MCP 主机准备就绪。 |
## 工作原理
```text
代码库 + 任务
│
▼
检测技术栈和项目上下文
│
▼
选择一个兼容的技能集
│
▼
审计和预览安装
│
▼
安装审查的指令和锁定文件元数据
│
▼
您的代理读取所选的指令并执行任务
```
## 支持的代理
技能导航支持代码库本地设置的：
- **Codex** (`codex`)
- **Claude Code** (`claude-code`)
- **Cursor** (`cursor`)
- **OpenCode** (`opencode`)
- **Gemini CLI** (`gemini-cli`)
- **模型上下文协议** 主机通过_stdio MCP 服务器
## 捆绑的前端技能
技能导航目前提供 18 种预审计、仅限指令的前端技能，涵盖：
- React 和 Next.js 架构；
- 组件设计和 Tailwind UI 润色；
- 视觉设计、UX、交互和动画；
- 可访问性、性能、测试和 Playwright 调试；
- 发布审计和人工智能代理项目上下文。
<details>
<summary><strong>查看所有 18 种捆绑技能 ID</strong></summary>
| 类别 | 技能 ID | 目的 |
| :--- | :--- | :--- |
| 框架和核心 | `frontend.next-app-router-review` | Next.js 应用程序路由器架构和数据流审查。 |
| | `frontend.react-app-review` | React 状态所有权、提供者和渲染性能。 |
| | `frontend.react-component-design` | 组件 API、组合和道具边界。 |
| | `frontend.tailwind-ui-polish` | 响应式布局和 Tailwind UI 清理。 |
| | `frontend.design-to-code` | 响应式实现从设计和模型。 |
| 设计和动画 | `frontend.visual-design-polish` | 艺术指导、层次结构、排版和美学。 |
| | `frontend.design-system` | 令牌、主题、基元和一致性。 |
| | `frontend.ux-critique` | 信息架构、可用性和用户流程。 |
| | `frontend.interaction-polish` | 对话框、抽屉、焦点和微交互。 |
| | `frontend.motion-design` | 动画编排和减少动画行为。 |
| | `frontend.motion-audit` | 动画性能和帧丢失诊断。 |
| | `frontend.visual-critic` | 独立视觉比较和批评。 |
| 质量和发布 | `frontend.accessibility-review` | WCAG、ARIA、键盘导航和焦点行为。 |
| | `frontend.performance-review` | 核心 Web 重要指标、包和渲染瓶颈。 |
| | `frontend.testing-strategy` | 集中的单元、集成和端到端规划。 |
| | `frontend.playwright-debug` | Playwright 波动、等待和跟踪。 |
| | `frontend.audit` | 宽泛的前端发布准备度审计。 |
| 代理上下文 | `frontend.agents-md-bootstrap` | 代理的项目命令和架构指导。 |
</details>
## MCP 集成
将技能导航添加为_stdio MCP 服务器：
```json
{
"mcpServers": {
"skillranger": {
"command": "npx",
"args": ["-y", "skillranger@latest", "mcp"]
}
}
}
```
MCP 接口可以分析项目、推荐和审计技能、预览或确认安装、准备路由任务，并为代理主机提供强制技能指令。
<details>
<summary><strong>可用的 MCP 工具</strong></summary>
- `analyze_project`
- `recommend_skills`
- `audit_skill`
- `plan_skill_install`
- `install_skill`
- `prepare_task`
- `read_run_skill_file`
</details>
## 高级命令行界面用法
以下命令是可选的。它们对于检查各个阶段、编写技能导航或将其集成到代理主机中很有用。
### 手动推荐和安装
```bash
# 检测代码库上下文
npx -y skillranger@latest scan .
# 解释某个任务的建议
npx -y skillranger@latest recommend . \
--target codex \
--intent "Review this Next.js app before release" \
--explain
# 审计一个包
npx -y skillranger@latest audit frontend.next-app-router-review
# 预览安装
npx -y skillranger@latest install frontend.next-app-router-review \
--project . \
--target codex \
--scope repo \
--dry-run
# 应用审查计划
npx -y skillranger@latest install frontend.next-app-router-review \
--project . \
--target codex \
--scope repo \
--yes
# 检查已安装的技能
npx -y skillranger@latest installed .
```
### 直接任务路由器
当集成需要结构化的路由结果而不是正常的交互式设置流程时，请使用此模式：
```bash
npx -y skillranger@latest task . \
--intent "Review accessibility and fix critical focus traps" \
--target codex \
--json
```
代理主机或手动集成可以读取所需的指令块：
```bash
npx -y skillranger@latest task:read . \
--router-run <router-run-id> \
--mandatory-next \
--expected-read-revision 0 \
--json
```
有关持久化和严格的生命周期命令、证据处理、验证状态和恢复行为，请参见 [`docs/workflow-runtime.md`](docs/workflow-runtime.md)。
## 安全模型
- **捆绑的本地注册表** — 捆绑包随分发一起提供；正常的推荐不会获取任意远程技能。
- **静态指令** — 已安装的技能包是指令，而不是在安装期间执行的脚本。
- **显式写入** — 命令行界面安装可以使用 `--dry-run` 预览；MCP 写入需要显式确认。
- **完整性跟踪** — 已安装的文件被哈希并记录在 `skillranger.lock.json` 中。
- **主机管理的执行** — 您选择的 AI 代理拥有模型调用、工具和应用程序代码更改。
## 开发
```bash
git clone https://github.com/Narek-Khachikyan/SkillRanger.git
cd SkillRanger
pnpm install
pnpm build
pnpm check
pnpm test
pnpm release:check
```
## 许可证
在 [MIT 许可证](LICENSE) 下分发。
