SKILL审查

技能文档

---
name: skill-check
description: 审查、优化和改写技能（Skill）。支持三种工作模式：审查现有技能、优化技能结构、从文本/GitHub/已安装技能改写为标准 SKILL.md。当用户请求「优化技能」「审查技能」「改写技能」「把这个转成技能」或提供技能安装引导文本、GitHub 地址时触发。
title: SKILL审查
category: 通用技能
---

## SKILL 技能审查与改写器

支持两种工作模式：

| 模式 | 触发场景 | 输出 |
|------|----------|------|
| **审查模式** | 「审查技能」「检查技能」「优化技能」 | 审查报告 + 优化方案 |
| **改写模式** | 「改写技能」「把这个转成技能」+ 输入源 | 标准 SKILL.md + 目录结构 |

---

## 模式一：审查

## 技能工作流

调用 `todo_write` 工具创建待办任务：

结构分析 → 问题识别 → 逻辑审查 → 输出报告

## 审查维度

### 结构性维度（脚本检测）

| 维度 | 检查项 | 问题信号 |
|------|--------|----------|
| 渐进式披露 | SKILL.md 是否精简（< 500 行） | 正文过长、嵌套层级过深 |
| 脚本沉淀 | 固定行为是否脚本化 | LLM 反复推理相同逻辑、确定性操作无脚本 |
| 资源归位 | 资源文件是否在 assets/ | 模板、图片等散落在其他位置 |
| 参考分离 | 参考文档是否在 references/ | API 文档、Schema 等混入正文 |

### 逻辑性维度（LLM 分析）

| 维度 | 检查项 | 问题信号 |
|------|--------|----------|
| 逻辑漏洞 | 流程是否完整、边界是否覆盖 | 缺少异常处理、边界条件未说明 |
| 逻辑重复 | 是否存在冗余描述 | 相同规则多处重复、示例重复 |
| 逻辑冲突 | 内容是否自洽 | 前后规则矛盾、示例与规则不符 |
| 逻辑断层 | 步骤是否连贯 | 缺少前置条件、跳过关键步骤 |
| 执行可行性 | 指令是否可执行 | 描述模糊、缺少具体参数 |
| 执行确定性 | 路径、脚本、工具引用是否明确 | 使用「合适的位置」「相关脚本」等模糊指代 |
| 工作目录 | 是否明确指定工作目录 | 使用相对路径但未说明工作目录、AI 可能在错误目录执行 |
| 工作流展示 | 是否包含完整技能工作流章节 | 缺少技能工作流章节、步骤超过10个、步骤不清晰 |
| 工作流步骤详解展示 | 技能工作流每个步骤是否有独立章节（简单步骤除外） | 缺少技能工作流详细步骤章节、步骤详解不清晰、步骤详解散落在各处 |
| 使用说明章节 | 是否包含使用说明章节 | 缺少使用说明章节、使用方式不清晰、示例缺失 |

### 语义树维度（LLM 分析）

| 维度 | 检查项 | 问题信号 | 优化方案 |
|------|--------|----------|----------|
| 工作流步骤标注 | 章节标题是否标注对应工作流步骤 | 缺少步骤标注、标注不清晰 | 添加「（步骤N:阶段名）」标注 |
| 标题语义化 | 标题是否使用决策树、系统化命名 | 「指南」「方案」等模糊词 | 使用「决策树」「修复方案」「验证策略」 |
| 内容重复 | 相同内容是否多次出现 | 重复的模板、示例、说明 | 合并到单一位置,交叉引用 |
| 逻辑链条 | 是否遵循渐进式展开（抽象→具体） | 跳跃式叙述、缺乏过渡 | 诊断→识别→方案→示例 |
| 标题前缀 | 是否使用冗余前缀 | 「问题:xxx」「示例:xxx」 | 直接使用「xxx策略」「xxx方案」 |

### Agent 兼容性维度（脚本 + LLM 分析）

| 维度 | 检查项 | 问题信号 |
|------|--------|----------|
| 工具绑定 | 是否绑定特定 Agent 工具 | 出现 Qoder/ClaudeCode/OpenClaw/Cursor 等工具名硬编码 |
| API 依赖 | 是否使用特定工具独有 API | 调用特定工具的私有接口或 CLI |
| 触发限定 | description 是否限定特定工具 | 「在 Qoder 中...」「仅适用于 ClaudeCode」 |
| 路径耦合 | 是否依赖特定工具的目录结构 | 硬编码 .qoder/.claude/.cursor 等路径 |
| 配置格式 | 是否依赖特定工具的配置格式 | 使用特定工具独有的配置文件格式 |

**工作流展示模板**

```
## 技能工作流

调用 `todo_write` 工具创建待办任务：

步骤1 → 步骤2 → 步骤3 → 步骤4 → 步骤5

### 步骤1

步骤1详解

### 步骤2

步骤2详解

……

```

## 执行流程

**工作目录**: 必须先进入 skill-check 目录再执行脚本

```bash
cd /path/to/.qoder/skills/skill-check
python3 scripts/analyze.py <skill-dir>
```

| 步骤 | 任务 | 执行者 | 说明 |
|------|------|--------|------|
| 运行脚本 | `python3 scripts/analyze.py <skill-dir>` | 脚本 | 获取结构分析报告,失败则退出码非零 |
| 分析报告 | 识别问题优先级 | LLM | 基于脚本输出判断严重程度,优先处理 P0/P1 |
| 逻辑审查 | 分析逻辑漏洞、重复、冲突 | LLM | 深度内容分析,对照「审查维度」逐项检查 |
| 识别固定行为 | 找出确定性操作 | LLM | 判断是否应脚本化,参考「自由度匹配原则」 |
| 输出方案 | 汇总问题和建议 | LLM | 按优先级排序,给出可直接执行的修复步骤 |

**输入校验**:
- 必须先进入 skill-check 目录: `cd /path/to/skill-check`
- 参数 `<skill-dir>` 必须为有效目录路径(绝对路径或相对路径)
- 目标目录必须包含 `SKILL.md` 文件

**自我迭代模式**:
- 执行 `python3 scripts/review-loop.py <skill-dir>` 循环审查-修复直到无问题
- 自动检测结构性问题并修复,支持 `--max-iterations` 限制迭代次数

**异常处理**:
- 脚本不存在 → 跳过结构检查,LLM 手动分析
- 脚本执行失败(退出码非零) → 跳过结构检查,LLM 手动分析
- SKILL.md 不存在 → 输出 P0 问题,终止审查

**完成标准**：
- 所有 P0 问题已识别并给出建议
- 所有 P1 问题已识别并给出建议
- 输出可执行的优化方案

## 自由度匹配原则

| 自由度 | 适用场景 | 沉淀形式 |
|--------|----------|----------|
| 低 | 操作脆弱、需严格顺序、确定性高 | `scripts/` 脚本 |
| 中 | 有推荐模式、允许变体 | 伪代码/带参脚本 |
| 高 | 多种可行方式、决策依赖上下文 | 文本说明 |

**脚本化信号**（详见 [references/structure-patterns.md#脚本化方案](references/structure-patterns.md)）：
- 相同代码反复写
- LLM 多次推理相同逻辑
- 操作步骤固定、易出错
- 需要高可靠性

## 目录结构规范

```text
skill-name/
├── SKILL.md         # 必需：核心工作流（< 500 行）
├── scripts/         # 可选：可执行脚本（确定性操作）
├── references/      # 可选：参考文档（按需加载）
└── assets/          # 可选：资源文件（输出中使用）
```

| 目录 | 使用场景 | 示例 |
|------|----------|------|
| `scripts/` | 确定性操作、反复执行的逻辑，优先用 Python 脚本 | `analyze.py`、`validate.py` |
| `references/` | 查阅类文档、API 规范、Schema | `api_reference.md`、`schema.md` |
| `assets/` | 模板、图片、样板代码 | `template.pptx`、`logo.png` |

## 审查报告模板

```markdown
# 技能审查报告：{skill-name}

## 结构概览

| 目录/文件 | 状态 | 说明 |
|-----------|------|------|
| SKILL.md | ✅/⚠️/❌ | {行数} 行 |
| scripts/ | ✅/❌ | {脚本数量} 个 |
| references/ | ✅/❌ | {文档数量} 个 |
| assets/ | ✅/❌ | {资源数量} 个 |

## 章节结构

| 章节 | 行数 | 状态 |
|------|------|------|
| {章节名} | {行数} | ✅/⚠️ |

## 问题清单

| 优先级 | 问题 | 建议 |
|--------|------|------|
| P0 | {问题描述} | {优化建议} |

## 优化方案

{具体执行步骤，可直接应用}
```

## 常见优化模式

| 模式 | 触发条件 | 详细参考 |
|------|----------|----------|
| SKILL.md 拆分 | 超过 500 行或章节过长 | [patterns.md#拆分策略](references/structure-patterns.md) |
| 固定行为脚本化 | 确定性操作无脚本 | [patterns.md#脚本化方案](references/structure-patterns.md) |
| 资源文件归位 | 文件散落根目录 | [patterns.md#资源归位](references/structure-patterns.md) |
| 参考文档分离 | 查阅类内容混入正文 | [patterns.md#文档分离](references/structure-patterns.md) |
| Agent 兼容性修复 | 绑定特定工具或 API | [patterns.md#Agent兼容性](references/structure-patterns.md) |
| 语义树优化 | 标题模糊、内容重复、缺少步骤标注 | [patterns.md#语义树优化](references/structure-patterns.md) |

### 逻辑问题修正

| 问题类型 | 检测方法 | 修正建议 |
|----------|----------|----------|
| 逻辑漏洞 | 检查流程完整性 | 补充缺失步骤或边界条件 |
| 逻辑重复 | 识别相同规则多处出现 | 合并到单一位置，引用指向 |
| 逻辑冲突 | 对比前后规则一致性 | 删除或标注例外情况 |
| 逻辑断层 | 检查步骤连贯性 | 补充前置条件或过渡说明 |
| 执行模糊 | 检查指令具体性、路径/脚本/工具引用明确性 | 替换模糊词为具体参数,替换模糊指代为具体路径、脚本名、工具名 |

---

## 模式二：改写

将非标准输入源改写为符合规范的 SKILL.md 及目录结构。

### 输入源类型

| 类型 | 识别方式 | 处理策略 |
|------|----------|----------|
| **引导文本** | 用户粘贴安装说明、功能描述、README 等文本 | 解析文本 → 提取核心功能 → 生成标准 SKILL.md |
| **GitHub 地址** | 用户提供 `github.com/xxx/xxx` 仓库 URL | 克隆仓库 → 读取 SKILL.md 及相关文件 → 改写为标准格式 |
| **已安装技能** | 用户指定技能名称（如「改写 xxx」） | 读取已安装技能的 SKILL.md → 审查 → 改写为标准格式 |

### 技能工作流

调用 `todo_write` 工具创建待办任务：

识别输入源 → 提取内容 → 结构分析 → 改写 SKILL.md → 自审查 → 输出

### 步骤1：识别输入源

| 输入 | 动作 |
|------|------|
| 粘贴文本 | 直接进入步骤2，文本即为内容源 |
| GitHub URL | `git clone` 到临时目录，扫描目录结构 |
| 技能名称 | 在 `~/.skills/` 和 `~/.qoder/skills/` 中查找，读取 SKILL.md |

**异常处理**：
- GitHub URL 无法访问 → 提示用户确认地址或提供 ZIP 下载链接
- 已安装技能未找到 → 列出可用技能供用户选择

### 步骤2：提取内容

从输入源中提取以下信息（缺失项标注为「待补充」）：

| 提取项 | 说明 |
|--------|------|
| 技能名称 | 用于 frontmatter `name`，必须为 kebab-case |
| 功能描述 | 一句话说明，用于 frontmatter `description` |
| 核心功能 | 技能能做什么，支持哪些操作 |
| 使用方式 | 命令、参数、示例 |
| 依赖要求 | 需要安装的包、工具 |
| 触发条件 | 什么场景下应调用该技能 |
| 错误处理 | 异常情况与处理方式 |

### 步骤3：改写 SKILL.md

按以下结构生成标准 SKILL.md：

```
---
name: {kebab-case-name}
description: {一句话功能描述}
title: {中文标题}
category: {分类}
---

# {标题}

## 技能工作流

{N步工作流，每步有独立章节}

## 使用说明

{命令示例、参数说明}

## 异常处理

| 异常 | 处理方式 |
|------|----------|
| {场景} | {方式} |
```

**改写规则**：
- frontmatter `name` 必须为 kebab-case，与目录名一致
- 移除所有 Agent 绑定字段（openclaw、metadata、特定工具 API）
- 移除冗余字段（slug、display_name、allowed_intents 等 SkillHub 专有字段）
- SKILL.md 正文控制在 500 行以内
- 详细参考文档移至 `references/`，模板资源移至 `assets/`
- 确定性操作优先脚本化至 `scripts/`

### 步骤4：自审查

对改写后的 SKILL.md 执行模式一（审查模式）的完整检查：
- 运行 `python3 scripts/analyze.py <skill-dir>` 做结构检查
- 对照审查维度做逻辑检查
- 若有 P0/P1 问题，自行修正后重新检查

### 步骤5：输出

| 输出项 | 说明 |
|--------|------|
| SKILL.md | 改写后的标准技能文件 |
| 目录结构 | 如需 `scripts/`、`references/`、`assets/` 则一并创建 |
| README.md | 50 行以内的用户说明 |
| 审查摘要 | 改写前后的主要差异（表格形式） |

**输出格式**：

```markdown
## 改写摘要：{skill-name}

| 改写项 | 改写前 | 改写后 |
|--------|--------|--------|
| {项目} | {原始值} | {新值} |
```

### GitHub 输入源补充说明

克隆后按以下优先级扫描文件：

| 优先级 | 文件 | 说明 |
|--------|------|------|
| 1 | `SKILL.md` | 技能核心定义 |
| 2 | `README.md` | 功能说明与使用方法 |
| 3 | `scripts/*.py` | 可执行脚本，保留并归位 |
| 4 | 其他 `.md` | 可能包含补充说明 |
| 5 | 代码文件 | 理解功能但通常不直接纳入 |

---

## 禁止事项

- ❌ 删除 SKILL.md 核心工作流
- ❌ 将脚本移出 scripts/ 目录
- ❌ 破坏现有脚本的执行能力
- ❌ 修改 frontmatter 中的 name 字段（必须与目录名一致）

## 参考资料

- 结构优化模式 → [references/structure-patterns.md](references/structure-patterns.md)

使用说明

# Skill Check - 技能审查器

一句话：技能写好了但不确定质量如何？让 Agent 帮你检查一遍，找出问题并给出优化建议。

## 能做什么

- **结构检查** —— 看看技能目录组织是否合理，有没有遗漏必要的文件
- **逻辑审查** —— 检查 SKILL.md 里的工作流是否完整、有没有矛盾或漏洞
- **兼容性评估** —— 确认技能是否能在不同环境下正常运行，没有硬编码的依赖

## 使用方法

推荐用 `/skill-check` 显式调用：

```
/skill-check 审查 /path/to/技能目录
```

**示例**：

> /skill-check 审查我的 diagram 技能
>
> /skill-check 检查 skill-create 是否符合规范
>
> /skill-check 帮我看看这个技能有什么问题

Agent 会分析技能的结构、逻辑和兼容性，输出一份问题清单和优化建议。

## 举个例子

你刚写了一个新技能，准备发布到技能市场前想确认一下质量：

> "帮我审查一下这个项目启动器技能"

Agent 会检查 SKILL.md 是否完整、脚本是否能正常运行，然后告诉你哪些地方需要修改才能通过审核。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。