# Skill 格式规范与检查清单

本清单基于 `SKILL-DEV-GUIDE.md` 规范，用于技能创建指导和格式合规性检查。

---

## 1. 目录结构检查

### 1.1 必需文件

| 检查项 | 状态 | 说明 |
|--------|------|------|
| SKILL.md 存在 | ✅/❌ | 必需文件，缺失则无法加载技能 |

### 1.2 推荐结构

| 检查项 | 状态 | 说明 |
|--------|------|------|
| LICENSE.txt 存在 | ✅/⚠️ | 推荐包含许可证 |
| references/ 目录规范 | ✅/⚠️ | 参考文档应放在此目录 |
| scripts/ 目录规范 | ✅/⚠️ | 可执行脚本应放在此目录 |
| assets/ 目录规范 | ✅/⚠️ | 资源文件应放在此目录 |

### 1.3 不应存在的文件

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 无 `__pycache__/` | ✅/❌ | Python 缓存不应提交 |
| 无 `.env` 文件 | ✅/❌ | 敏感配置不应提交 |
| 无 `test/` 目录 | ✅/⚠️ | 开发测试文件不应在发布版中 |
| 无 `docs/` 目录 | ✅/⚠️ | 应使用 `references/` 替代 |
| 无根目录 `README.md` | ✅/⚠️ | 与 SKILL.md 重复，应删除 |

---

## 2. Frontmatter 检查

### 2.1 必需字段

| 检查项 | 状态 | 说明 |
|--------|------|------|
| `name` 字段存在 | ✅/❌ | 技能名称 |
| `name` 格式正确 | ✅/❌ | 小写字母、连字符，如 `skill-name` |
| `description` 字段存在 | ✅/❌ | 功能描述 |
| `license` 字段存在 | ✅/⚠️ | 许可证声明 |

### 2.2 description 格式

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 使用第三人称 | ✅/❌ | "本技能应在...时使用" |
| 包含触发场景 | ✅/❌ | 明确说明何时使用 |
| 包含负向触发条件 | ✅/⚠️ | "不要用于..."说明边界 |
| 长度 ≤ 1024 字符 | ✅/❌ | 保持简洁 |
| 无关键词堆砌 | ✅/⚠️ | 避免冗余 |

### 2.3 不应存在的字段

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 无 `version` 字段 | ✅/⚠️ | 版本信息应在 CHANGELOG.md 中 |

---

## 3. 内容规范检查

### 3.1 SKILL.md 内容

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 行数 ≤ 500 行 | ✅/⚠️ | 超出应拆分到 references/ |
| 无大段代码（>20行） | ✅/⚠️ | 代码应移至 scripts/ |
| 使用简洁示例 | ✅/⚠️ | 仅展示关键 API 调用 |
| 引用而非粘贴 | ✅/⚠️ | 指向 scripts/ 和 references/ |
| 聚焦工作流程 | ✅/⚠️ | 说明"做什么"和"怎么做" |

### 3.2 依赖说明

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 依赖章节格式规范 | ✅/⚠️ | 使用表格格式 |
| 系统依赖说明 | ✅/⚠️ | brew/apt-get 安装方式 |
| Python 包说明 | ✅/⚠️ | pip install 命令 |

---

## 4. 目录层级检查

### 4.1 扁平结构要求

| 检查项 | 状态 | 说明 |
|--------|------|------|
| references/ 扁平结构（一级） | ✅/⚠️ | 只允许一级子目录 |
| scripts/ 扁平结构（一级） | ✅/⚠️ | 只允许一级子目录 |
| assets/ 扁平结构（一级） | ✅/⚠️ | 只允许一级子目录 |

---

## 5. 文档一致性检查

### 5.1 文件引用

| 检查项 | 状态 | 说明 |
|--------|------|------|
| scripts/ 引用存在 | ✅/❌ | 引用的脚本文件存在 |
| assets/ 引用存在 | ✅/❌ | 引用的资源文件存在 |
| references/ 引用存在 | ✅/❌ | 引用的参考文档存在 |

### 5.2 冗余内容

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 无重复的 README.md | ✅/⚠️ | 与 SKILL.md 内容不重复 |
| 无过时的参考文档 | ✅/⚠️ | references/ 中的文档引用实际存在的文件 |
| 无废弃功能描述 | ✅/⚠️ | 文档描述与实际代码一致 |

---

## 6. 配置文件检查

### 6.1 命名规范

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 模板使用 `*.example.*` | ✅/⚠️ | 如 `config.example.yaml` |
| 实际配置被 .gitignore | ✅/⚠️ | 不提交敏感配置 |

### 6.2 配置一致性

| 检查项 | 状态 | 说明 |
|--------|------|------|
| example 字段与代码匹配 | ✅/❌ | 配置模板的字段被实际代码使用 |
| 无未使用的配置字段 | ✅/⚠️ | 删除未使用的字段 |

---

## 7. 技能协作检查

### 7.1 松耦合原则

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 不直接引用其他技能路径 | ✅/⚠️ | 不使用 `../../skills/xxx/` |
| 使用自然语言描述协作 | ✅/⚠️ | 说明"可以配合使用"而非直接调用 |

---

## 8. 模块化设计检查

### 8.1 独立功能解耦

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 独立功能抽取为单独脚本 | ✅/⚠️ | 可复用功能不应写在主脚本中 |
| 功能有清晰的输入输出 | ✅/⚠️ | 便于其他 skill 通过 AI 协调调用 |

### 8.2 模块间协调

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 同一 skill 内部可直接调用 | ✅/⚠️ | `evaluator.py` 调用 `pdf_ocr.py` |
| 跨 skill 不直接调用 | ✅/⚠️ | 不使用 `skill-a/main.py` 直接调用 `skill-b/main.py` |

---

## 9. 安全审计检查

### 9.1 基本原则

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 无硬编码 API keys | ✅/❌ | 敏感信息应在配置文件中 |
| 不读取 ~/.env | ✅/❌ | 不访问外部敏感配置 |

### 9.2 危险命令检查

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 无 `rm -rf ~` | ✅/❌ | 删除用户主目录 |
| 无 `rm -rf /` | ✅/❌ | 删除根目录 |
| 无 `rm -rf $HOME` | ✅/❌ | 删除用户主目录 |

### 9.3 安全删除规范

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 使用 `trash` 命令 | ✅/⚠️ | 移动到回收站 |
| 使用 `find -delete` | ✅/⚠️ | 清理目录内容（保留目录本身） |

---

## 10. 输出模式检查

### 10.1 输出模板

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 提供输出格式模板 | ✅/⚠️ | 对于需要一致性输出的技能，提供模板 |
| 模板严格度适中 | ✅/⚠️ | 严格需求用 `ALWAYS use this exact template`，灵活需求用 `use your best judgment` |
| 模板结构清晰 | ✅/⚠️ | 包含标题、摘要、正文、建议等章节 |

**严格模板示例**（API 响应、数据格式）：
```markdown
ALWAYS use this exact template structure:

# [Analysis Title]

## Executive summary
[One-paragraph overview]

## Key findings
- Finding 1 with supporting data
- Finding 2 with supporting data

## Recommendations
1. Specific actionable recommendation
```

**灵活模板示例**（分析报告、创意内容）：
```markdown
Here is a sensible default format, but use your best judgment:

# [Analysis Title]

## Executive summary
[Overview]

## Key findings
[Adapt sections based on what you discover]

Adjust sections as needed for the specific context.
```

### 10.2 示例模式

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 提供输入/输出示例 | ✅/⚠️ | 对于质量关键的输出，提供 input/output 对 |
| 示例覆盖典型场景 | ✅/⚠️ | 至少 2-3 个不同场景的示例 |
| 示例风格一致 | ✅/⚠️ | 所有示例遵循相同的格式和详细程度 |

**示例格式**：
```markdown
## Commit message format

**Example 1:**
Input: Added user authentication with JWT tokens
Output:
```
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware
```

**Example 2:**
Input: Fixed bug where dates displayed incorrectly
Output:
```
fix(reports): correct date formatting

Use UTC timestamps consistently
```
```

---

## 11. 工作流模式检查

### 11.1 顺序工作流

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 复杂任务有流程概览 | ✅/⚠️ | 在 SKILL.md 开头提供操作步骤概览 |
| 步骤编号清晰 | ✅/⚠️ | 使用 1. 2. 3. 编号 |
| 每步指向具体操作 | ✅/⚠️ | 说明运行什么脚本或执行什么动作 |

**顺序工作流示例**：
```markdown
Filling a PDF form involves these steps:

1. Analyze the form (run analyze_form.py)
2. Create field mapping (edit fields.json)
3. Validate mapping (run validate_fields.py)
4. Fill the form (run fill_form.py)
5. Verify output (run verify_output.py)
```

### 11.2 条件工作流

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 分支逻辑有决策点 | ✅/⚠️ | 明确说明何时走哪个分支 |
| 使用清晰的分支标识 | ✅/⚠️ | 使用粗体问题 + 箭头指向 |
| 每个分支步骤完整 | ✅/⚠️ | 每个分支都有完整的执行步骤 |

**条件工作流示例**：
```markdown
1. Determine the modification type:
   **Creating new content?** → Follow "Creation workflow" below
   **Editing existing content?** → Follow "Editing workflow" below

2. Creation workflow:
   - Step 1: ...
   - Step 2: ...

3. Editing workflow:
   - Step 1: ...
   - Step 2: ...
```

---

## 12. CHANGELOG 规范检查

### 12.1 文件存在性

| 检查项 | 状态 | 说明 |
|--------|------|------|
| CHANGELOG.md 存在 | ✅/⚠️ | 推荐包含变更日志 |

### 12.2 格式规范

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 版本号格式正确 | ✅/⚠️ | 使用语义化版本 v1.0.0 |
| 日期格式统一 | ✅/⚠️ | 使用 YYYY-MM-DD 格式 |
| 变更类型清晰 | ✅/⚠️ | 新增/修改/修复/移除 |

**CHANGELOG 格式示例**：
```markdown
# Changelog

## [v1.1.0] - 2026-02-24

### 新增
- 添加了 XXX 功能

### 修改
- 优化了 YYY 逻辑

### 修复
- 修复了 ZZZ 问题

## [v1.0.0] - 2026-02-01

### 新增
- 初始版本发布
```

---

## 13. 版本号管理检查

### 13.1 版本位置

| 检查项 | 状态 | 说明 |
|--------|------|------|
| SKILL.md 无 version 字段 | ✅/⚠️ | 版本信息应在 CHANGELOG.md 中 |
| 版本统一在 CHANGELOG.md | ✅/⚠️ | 所有版本变更在 CHANGELOG.md 记录 |

### 13.2 版本一致性

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 版本号与 CHANGELOG 一致 | ✅/⚠️ | 如有版本号，应与最新 CHANGELOG 版本匹配 |

---

## 14. 可编排性设计检查

### 14.1 输入/输出声明

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 有明确的输入声明 | ✅/⚠️ | 在 SKILL.md 中说明必需/可选参数 |
| 有明确的输出声明 | ✅/⚠️ | 说明输出文件和副作用 |

**输入/输出声明格式**：
```markdown
## 输入/输出

### 输入
- 必需：`--input` 参数说明
- 可选：`--flag` 参数说明

### 输出
- 输出文件：`output/path.md` 说明
- 副作用：如创建目录、修改文件等
```

### 14.2 单一职责

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 技能只做一件事 | ✅/⚠️ | 核心功能单一明确 |
| 无不相关功能混入 | ✅/⚠️ | 避免多任务混合 |

### 14.3 幂等性

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 多次执行结果相同 | ✅/⚠️ | 无累积效应 |
| 无副作用累积 | ✅/⚠️ | 如追加写入应改为覆盖 |

### 14.4 复杂编排支持

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 复杂编排有 workflow.md | ✅/⚠️ | 涉及多技能协作时有详细说明 |

---

## 15. 问题严重程度定义

| 级别 | 图标 | 说明 | 处理建议 |
|------|------|------|----------|
| 严重 | ❌ | 阻塞技能正常使用 | 必须修复 |
| 警告 | ⚠️ | 影响可维护性或规范性 | 建议修复 |
| 信息 | ℹ️ | 优化建议 | 可选修复 |

---

## 16. 审查报告模板

```markdown
# [skill-name] 格式审查报告

**审查时间**: YYYY-MM-DD HH:MM
**技能路径**: /path/to/skill

## 审查摘要

| 检查项 | 状态 | 问题数 |
|--------|------|--------|
| 目录结构 | ✅/⚠️/❌ | N |
| Frontmatter | ✅/⚠️/❌ | N |
| description | ✅/⚠️/❌ | N |
| SKILL.md 行数 | ✅/⚠️ | N |
| 目录层级 | ✅/⚠️ | N |
| 文档一致性 | ✅/⚠️/❌ | N |
| 冗余内容 | ✅/⚠️/❌ | N |
| 配置文件 | ✅/⚠️/❌ | N |
| 技能协作 | ✅/⚠️/❌ | N |
| 模块化设计 | ✅/⚠️ | N |
| 安全审计 | ✅/❌ | N |
| 输出模式 | ✅/⚠️/❌ | N |
| 工作流模式 | ✅/⚠️/❌ | N |
| CHANGELOG | ✅/⚠️/❌ | N |
| 版本号管理 | ✅/⚠️/❌ | N |
| 可编排性 | ✅/⚠️/❌ | N |

## 详细问题

### ❌ 严重问题（必须修复）

1. **[问题标题]**
   - 位置: `文件路径:行号`
   - 规范: 违反的规范条款
   - 建议: 具体修复建议

### ⚠️ 建议优化

1. **[问题标题]**
   - 位置: `文件路径`
   - 建议: 优化建议

### ℹ️ 信息提示

- [提示信息]

## 建议操作

### 删除文件

| 文件路径 | 原因 |
|----------|------|
| `path/to/file.md` | 删除原因 |

### 更新文件

| 文件路径 | 修改内容 |
|----------|----------|
| `SKILL.md` | 修改说明 |

### 新增文件

| 文件路径 | 用途 |
|----------|------|
| `assets/config.example.yaml` | 用途说明 |

## 审查完成

- 总问题数: N
- 严重问题: N
- 建议优化: N
- 信息提示: N
```

---

## 规范参考

- **SKILL-DEV-GUIDE.md** - 项目根目录
- **Claude Code 官方规范** - skills/pdf, skills/skill-creator