Skill质量优化专家 v2.0.0
> 文档版本：2.0.0
> 创建日期：2026-05-25
> 更新日期：2026-05-25
> 核心定位：融合TDD方法论与TRACE五维评测的Skill质量优化引擎
> 适用场景：Skill发布前自检、质量优化、TRACE评测、SkillHub合规检查
一、核心架构
1.1 技能定位
┌─────────────────────────────────────────────────────────────────────────┐
│ TDD-Skill质量优化工作流 v1.0 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ RED阶段：定义成功标准 │ │
│ │ • 分析目标Skill的当前状态 │ │
│ │ • 确定质量目标和评测维度 │ │
│ │ • 制定可衡量的改进标准 │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ GREEN阶段：生成达标输出 │ │
│ │ • 执行TRACE五维质量评测 │ │
│ │ • 执行SkillHub发布验证 │ │
│ │ • 识别P0/P1/P2级问题 │ │
│ │ • 生成基础达标版本 │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ REFACTOR阶段：优化完善 │ │
│ │ • 修复P0/P1级问题 │ │
│ │ • 优化文档结构和内容 │ │
│ │ • 增强功能和示例 │ │
│ │ • 验证优化效果 │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌───────────────────┐ │
│ │ 循环优化直到达标 │ │
│ └───────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
1.2 技能优势
| 维度 | 优势 |
|---|---|
| 方法论融合 | 融合Red/Green/TDD + TRACE五维 + SkillHub验证 |
| 循环优化 | RED→GREEN→REFACTOR循环直到达标 |
| 全面评测 | 五维评测(T/R/A/C/E) + 发布合规性检查 |
| 智能修复 | P0/P1/P2问题自动识别和修复建议 |
| 开箱即用 | 纯内容Skill，无外部依赖 |
1.3 输入参数说明
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
target_skill_path |
string | ✅ | - | 待优化/评测的Skill路径（绝对或相对路径） |
target_score |
number | ❌ | 4.0 | 目标综合评分（0-5） |
evaluation_depth |
string | ❌ | normal | 评测深度：minimal/normal/deep |
improvement_scope |
string | ❌ | standard | 改进范围：minimal/standard/full |
1.4 触发调用方式
何时调用：
- 需要优化现有Skill达到发布标准时
- 需要对Skill进行质量评估时
- 需要检查Skill是否符合SkillHub规范时
调用方式：
# 直接调用示例
优化我的Skill：/path/to/skill
目标评分：4.5
评测深度：deep
二、TRACE五维评测体系
2.1 五维定义
| 维度 | 名称 | 核心问题 | 目标评分 |
|---|---|---|---|
| T | Trust 可信任度 | 用着放心吗？ | 4.8-5.0 |
| R | Reliability 可靠性 | 每次都稳吗？ | 4.5-5.0 |
| A | Adaptability 适用性 | 该出手时出得来吗？ | 4.2-4.8 |
| C | Convention 规范性 | 写得清楚、改得动吗？ | 4.2-4.8 |
| E | Effectiveness 有效性 | 最终交付的结果好用吗？ | 4.5-5.0 |
2.2 评分等级
| 评分 | 等级 | 说明 | 行动 |
|---|---|---|---|
| 4.5-5.0 | 优秀 | 达到发布标准 | 可直接发布 |
| 4.0-4.4 | 良好 | 基本达到发布标准 | 建议优化后发布 |
| 3.5-3.9 | 一般 | 有问题需修复 | 修复后发布 |
| 3.0-3.4 | 较差 | 需重大改进 | 重大改进后发布 |
| <3.0 | 不合格 | 阻塞发布 | 必须修复P0问题 |
三、RED阶段：定义成功标准
3.1 核心要素
每次优化前，先分析目标Skill的当前状态：
## RED阶段分析清单
### 1. 当前状态分析
- Skill名称和版本
- 当前评分（如果有）
- 已有问题数量和级别
### 2. 目标定义
- 目标综合评分：≥4.0
- 目标维度评分：T≥4.8, R≥4.5, A≥4.2, C≥4.2, E≥4.5
- 是否需要发布：Y/N
### 3. 改进范围
- 最小改进：仅修复P0问题
- 标准改进：修复P0+P1问题
- 完整改进：修复所有问题+增强功能
### 4. 成功标准
- [ ] P0问题全部修复
- [ ] P1问题大部分修复
- [ ] 综合评分≥4.0
- [ ] 发布合规性通过（如果是发布目标）
3.2 评测深度选择
| 深度 | 适用场景 | 评测耗时 |
|---|---|---|
| minimal | 快速预检 | <1秒 |
| normal | 标准评测 | 1-3秒 |
| deep | 发布前最终审核 | 5-10秒 |
四、GREEN阶段：生成达标输出
4.1 评测执行
对目标Skill执行完整的TRACE五维评测：
## TRACE评测检查项
### T - Trust 可信任度
- [ ] 安全性检查通过
- [ ] 国内适配性检查通过
- [ ] 无敏感信息泄露
### R - Reliability 可靠性
- [ ] 重试机制存在
- [ ] 超时处理完善
- [ ] 错误提示友好
### A - Adaptability 适用性
- [ ] 能力边界清晰
- [ ] 触发条件明确
- [ ] 输入输出示例完整
### C - Convention 规范性
- [ ] 文档结构分层
- [ ] FAQ完备
- [ ] 反模式说明存在
### E - Effectiveness 有效性
- [ ] 输出准确可靠
- [ ] 内容完整
- [ ] 开箱即用
4.2 问题识别
## 问题分级
### P0级（阻塞发布-必须立即修复）
- SKILL.md不存在
- 缺少必需frontmatter字段
- __pycache__或.pyc文件存在
- 安全漏洞
- **目录结构错误**（Skill/子目录存在，文件未在根目录）
### P1级（严重-短期改进）
- 缺少FAQ文档
- 错误处理不完善
- 示例不完整
- 版本不一致
### P2级（一般-可选优化）
- .DS_Store存在
- 文档格式不规范
- 注释缺失
4.3 SkillHub合规检查
## SkillHub发布验证清单
### 必需文件
- [ ] SKILL.md存在
- [ ] _meta.json存在
- [ ] metadata.json存在
### Frontmatter必需字段
- [ ] name（小写字母/数字/连字符）
- [ ] version（x.y.z格式）
- [ ] description（20-500字符）
- [ ] tags（非空数组）
- [ ] icon（emoji）
- [ ] author
- [ ] license
- [ ] schema_version
### 文件规范
- [ ] 文件数<200
- [ ] 总大小<10MB
- [ ] 无__pycache__
- [ ] 无.pyc
五、REFACTOR阶段：优化完善
5.1 修复优先级
## 修复执行顺序
### 第一轮：P0问题修复
1. **修复目录结构错误**（如有Skill/子目录，移文件到根目录）
2. 补充缺失的必需文件
3. 修复缺失的frontmatter字段
4. 清理Python缓存文件
5. 修复安全漏洞
### 第二轮：P1问题修复
1. 补充FAQ文档
2. 完善错误处理说明
3. 增加输入输出示例
4. 同步版本号
### 第三轮：增强优化
1. 优化文档结构
2. 补充反模式说明
3. 增加使用场景
4. 完善验证清单
5.2 优化模板
## FAQ文档模板
### 常见问题解答 (FAQ)
#### Q1: {问题1}
{详细解答}
#### Q2: {问题2}
{详细解答}
#### Q3: {问题3}
{详细解答}
## 反模式说明模板
### ❌ 错误用法
- 错误用法1 - 会导致什么问题
- 错误用法2 - 会导致什么问题
### ✅ 正确用法
- 正确用法1 - 为什么有效
- 正确用法2 - 为什么有效
六、Skill目录结构规范 ⚠️
6.1 标准Skill目录结构
生成的Skill必须遵循以下目录结构，所有文件必须在根目录：
skill-name/
├── SKILL.md ← 必需：主文档
├── _meta.json ← 必需：Agent契约
├── metadata.json ← 必需：完整元数据
├── README.md ← 推荐：快速开始指南
├── FAQ.md ← 推荐：常见问题
├── examples/ ← 可选：示例目录（内容放根目录）
│ ├── 示例1.md
│ └── 示例2.md
├── references/ ← 可选：参考文档（内容放根目录）
│ └── 参考.md
└── tools/ ← 可选：工具目录（如需要搜索引擎等）
└── 搜索引擎/
├── search.py
└── 配置.json
6.2 常见错误 ❌
❌ 错误：文件放在子目录
skill-name/
└── Skill/ ← 错误！不应有子目录
├── SKILL.md
├── _meta.json
└── metadata.json
❌ 错误：空目录
skill-name/
├── examples/ ← 空目录！内容必须在根目录
├── references/ ← 空目录！
└── SKILL.md
6.3 正确示例 ✅
✅ 正确：所有文件在根目录
RedGreen-TDD/
├── SKILL.md
├── _meta.json
├── metadata.json
├── README.md
├── FAQ.md
├── examples/
│ ├── 示例1-写文案.md
│ └── 示例2-代码开发.md
└── references/
└── TDD原理详解.md
6.4 目录层级检测规则
## P0级问题：目录结构错误
IF 发现 "Skill/" 子目录存在 THEN
检测为 P0 问题：输出目录错误
修复方案：将 Skill/ 目录下的文件移到根目录
IF examples/ 或 references/ 目录存在但为空 THEN
检测为 P1 问题：辅助目录为空
修复方案：删除空目录或将内容移入
6.5 文件放置规则
| 文件类型 | 放置位置 | 说明 |
|---|---|---|
| 核心文件 | 根目录 | SKILL.md, _meta.json, metadata.json |
| 说明文档 | 根目录 | README.md, FAQ.md, 使用指南.md |
| 示例内容 | examples/ | 有实际内容的示例文件 |
| 参考资料 | references/ | 有实际内容的参考文档 |
| 工具脚本 | tools/ | 需要工具功能时才创建 |
七、执行流程
6.1 完整工作流
┌─────────────────────────────────────────────────────────────────────────┐
│ Step 1: RED - 定义成功标准 │
│ │
│ • 分析目标Skill当前状态 │
│ • 确定目标评分和评测深度 │
│ • 制定改进范围和优先级 │
└─────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────┐
│ Step 2: GREEN - 执行评测 │
│ │
│ • 执行TRACE五维评测 │
│ • 执行SkillHub合规检查 │
│ • 识别所有P0/P1/P2问题 │
│ • 生成详细评测报告 │
└─────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────┐
│ Step 3: REFACTOR - 优化修复 │
│ │
│ • 第一轮：修复P0问题 │
│ • 第二轮：修复P1问题 │
│ • 第三轮：增强优化 │
│ • 验证修复效果 │
└─────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────┐
│ 评分达标？ │
└──────┬──────┘
YES ↓ ↓ NO
┌──────────┐ 返回Step 1
│ 完成输出 │ 重新定义目标
└──────────┘
6.2 快速执行模板
## 快速执行模板
### 输入
目标Skill路径：{path}
目标评分：{target_score}
评测深度：{depth}
### 执行
## RED：定义标准
当前评分：{current_score}
目标评分：{target_score}
差距：{gap}
问题清单：
- P0: {p0_issues}
- P1: {p1_issues}
- P2: {p2_issues}
## GREEN：执行评测
[TRACE五维评测结果]
[SkillHub合规检查结果]
## REFACTOR：优化修复
[修复执行记录]
[验证结果]
### 输出
最终评分：{final_score}
修复问题：{fixed_issues}
剩余问题：{remaining_issues}
发布准备度：{readiness}
八、典型场景
场景1：Skill发布前优化
输入：
目标：优化现有Skill以达到发布标准
目标评分：≥4.0
深度：deep
执行：
## RED
当前状态：综合评分3.2，存在2个P0问题、5个P1问题
目标：综合评分≥4.0，P0问题全部修复
## GREEN
T-Trust: 3.8 - 需要增强安全性说明
R-Reliability: 3.5 - 需要添加超时处理
A-Adaptability: 3.0 - 需要完善输入参数说明
C-Convention: 3.2 - 需要添加FAQ
E-Effectiveness: 3.0 - 需要增加示例
P0问题：
1. SKILL.md缺少schema_version字段
2. 存在__pycache__目录
## REFACTOR
第一轮：补充schema_version，清理__pycache__
第二轮：完善五维内容
第三轮：添加FAQ和反模式
最终评分：4.2
发布准备度：✅ 可发布
场景2：TDD学习辅助
输入：
目标：学习如何用TDD方法开发Skill
深度：normal
执行：
## RED
目标：理解TDD开发Skill的完整流程
成功标准：
- [ ] 理解RED/GREEN/REFACTOR三阶段
- [ ] 能够应用到实际开发中
- [ ] 建立质量优化意识
## GREEN
展示TDD-Skill工作流的完整示例
提供学习方法和建议
## REFACTOR
补充学习资源推荐
提供练习项目建议
九、错误处理与重试机制
8.1 错误处理定义
## 错误处理策略
### 错误类型与处理方式
| 错误类型 | 代码 | 策略 | 处理方式 |
|----------|------|------|----------|
| Skill路径不存在 | EH001 | error_message | 返回友好错误信息 |
| 评测执行失败 | EH002 | partial_result | 返回已完成的评测部分 |
| 文件读取失败 | EH003 | skip_continue | 跳过问题文件继续评测 |
| JSON解析错误 | EH004 | error_message | 指出具体文件和位置 |
| 版本不一致 | EH005 | auto_fix | 自动同步版本号 |
### 错误信息模板
```markdown
## 错误信息规范
### EH001: Skill路径不存在
提示："指定的Skill路径不存在，请检查路径是否正确"
帮助："支持的路径格式：绝对路径或相对路径"
### EH002: 评测执行失败
提示："部分评测失败"
帮助："返回已完成的评测结果，剩余部分请手动检查"
### EH003: 文件读取失败
提示："无法读取{filename}"
帮助："检查文件权限或文件是否损坏"
### EH004: JSON解析错误
提示："{filename}的JSON格式错误（第{line}行）"
帮助："请使用JSON验证工具检查格式"
### EH005: 版本不一致
提示："检测到版本不一致，已自动同步为{version}"
帮助："建议检查各文件的version字段是否一致"
8.2 重试机制
## 重试机制说明
### 自动重试配置
| 场景 | 重试次数 | 重试间隔 | 说明 |
|------|----------|----------|------|
| 网络请求 | 2次 | 1秒 | 评测工具调用时 |
| 文件扫描 | 1次 | 0秒 | 立即重试 |
| 评测执行 | 1次 | 0秒 | 跳过继续 |
### 重试条件
满足以下条件时触发重试：
- 网络超时（>10秒无响应）
- 临时文件锁定
- 系统资源短暂不足
### 不重试条件
以下情况不重试，直接报错：
- Skill路径不存在
- 权限不足
- 文件格式严重错误
- 用户取消操作
8.3 超时配置
## 超时配置
| 操作 | 超时时间 | 说明 |
|------|----------|------|
| minimal评测 | 10秒 | 快速文件扫描 |
| normal评测 | 30秒 | 完整五维评测 |
| deep评测 | 60秒 | 深度内容分析 |
### 超时处理
评测超时后：
1. 返回已完成的评测结果
2. 标记未完成部分为"超时"
3. 提供手动继续的建议
十、自验证清单
9.1 TDD-Skill工作流自验证
## 自验证清单
### RED阶段
- [ ] 分析了目标Skill的当前状态
- [ ] 确定了明确的改进目标
- [ ] 制定了可衡量的成功标准
### GREEN阶段
- [ ] 执行了完整的TRACE五维评测
- [ ] 识别了所有P0/P1/P2问题
- [ ] 生成了详细的评测报告
### REFACTOR阶段
- [ ] 修复了所有P0问题
- [ ] 修复了大部分P1问题
- [ ] 验证了修复效果
### 最终验证
- [ ] 综合评分达到目标
- [ ] P0问题全部修复
- [ ] 发布准备度为可发布（如适用）
9.2 R-Reliability自检清单
## 可靠性自检
### 重试机制 ✅
- [ ] 网络请求有重试机制（2次）
- [ ] 文件操作有保护
- [ ] 错误后有恢复策略
### 超时处理 ✅
- [ ] minimal评测<10秒
- [ ] normal评测<30秒
- [ ] deep评测<60秒
- [ ] 超时后有友好提示
### 错误提示 ✅
- [ ] 错误代码明确（EHxxx）
- [ ] 错误信息易懂
- [ ] 提供修复建议
- [ ] 不泄露敏感路径
十一、质量指标定义
10.1 评分标准体系
## 质量指标定义
### TRACE五维评分标准
| 维度 | 指标名称 | 核心问题 | 目标评分 |
|------|----------|----------|----------|
| T | 可信任度 | 用着放心吗？ | 4.8-5.0 |
| R | 可靠性 | 每次都稳吗？ | 4.5-5.0 |
| A | 适用性 | 该出手时出得来吗？ | 4.2-4.8 |
| C | 规范性 | 写得清楚、改得动吗？ | 4.2-4.8 |
| E | 有效性 | 最终交付的结果好用吗？ | 4.5-5.0 |
### 评分等级定义
| 评分 | 等级 | 说明 | 行动建议 |
|------|------|------|----------|
| 4.5-5.0 | 优秀 | 达到发布标准 | 可直接发布 |
| 4.0-4.4 | 良好 | 基本达到发布标准 | 建议优化后发布 |
| 3.5-3.9 | 一般 | 有问题需修复 | 修复后发布 |
| 3.0-3.4 | 较差 | 需重大改进 | 重大改进后发布 |
| <3.0 | 不合格 | 阻塞发布 | 必须修复P0问题 |
十二、使用限制与故障排除
10.1 使用限制
## 使用限制
### 适用场景
- ✅ 评测本地Skill目录
- ✅ 评测下载的Skill包
- ✅ 提交SkillHub前的自检
- ✅ 改进现有Skill的质量
### 不适用场景
- ❌ Git仓库远程链接（需先克隆到本地）
- ❌ 加密或混淆的Skill
- ❌ 非标准结构的Skill
- ❌ 需要实际运行的Skill（仅静态分析）
### 能力边界
- 本技能基于静态分析，不能替代实际运行测试
- 评测结果仅供参考，不能完全替代人工审核
- 评分受Skill文档完整度影响
- 不能检测代码逻辑错误或运行时问题
10.2 故障排除
## 故障排除
### 问题：评测执行失败
**症状**：评测过程中报错或中断
**排查步骤**：
1. 检查目标Skill路径是否正确
2. 确认SKILL.md文件存在且格式正确
3. 检查文件权限是否足够
4. 尝试使用minimal深度重新评测
**解决方案**：
```bash
# 1. 验证路径存在
ls -la /path/to/skill
# 2. 检查SKILL.md
head -20 /path/to/skill/SKILL.md
# 3. 使用minimal深度重试
python3 evaluate.py --path /path/to/skill --depth minimal
问题：评分异常低
症状：评测结果显示评分与预期不符
排查步骤：
1. 检查是否使用了正确的评测深度
2. 确认文档是否包含所有必需章节
3. 检查是否有语法错误或格式问题
解决方案：
- 使用deep深度获得最准确的评测结果
- 补充缺失的文档内容（FAQ、反模式等）
- 参考评测报告的建议进行修复
问题：版本不一致警告
症状：评测报告提示版本号不一致
排查步骤：
1. 检查SKILL.md中的version字段
2. 检查_meta.json中的version字段
3. 检查metadata.json中的version字段
解决方案：
# 同步版本号
# 确保三个文件的version字段一致
问题：发布资格被拒绝
症状：SkillHub验证显示不可发布
排查步骤：
1. 检查是否有P0级阻塞问题
2. 确认所有必需文件存在
3. 验证frontmatter字段完整性
解决方案：
1. 修复所有P0问题（阻塞发布的问题）
2. 补充缺失的必需文件
3. 确保frontmatter包含所有必需字段
---
## 十三、相关资源
### 12.1 核心参考
| 技能 | 说明 | 路径 |
|------|------|------|
| skill-quality-evaluator | TRACE五维质量评测 | 好的Skill判定/ |
| skill-factory | Skill生成与验证 | 完整生成skills技能/ |
| skillhub-validator | SkillHub发布验证 | SkillHub 技能发布验证器/ |
| RedGreen-TDD通用经验 | AI对话TDD方法论 | RedGreen-TDD通用经验/ |
### 12.2 方法论融合
本技能融合了以下最佳实践：
1. **Red/Green/Refactor** - 来自RedGreen-TDD通用经验
- RED：定义清晰的成功标准
- GREEN：生成满足标准的输出
- REFACTOR：在达标基础上优化完善
2. **TRACE五维评测** - 来自skill-quality-evaluator
- T-Trust：可信任度
- R-Reliability：可靠性
- A-Adaptability：适用性
- C-Convention：规范性
- E-Effectiveness：有效性
3. **SkillHub发布验证** - 来自skillhub-validator
- Frontmatter规范
- 文件合规性
- 版本一致性
---
## 版本历史
| 版本 | 日期 | 变更 |
|------|------|------|
| 2.0.0 | 2026-05-25 | 全面优化显示名称、描述、Tags（SEO优化） |
| 1.0.3 | 2026-05-25 | 添加输入参数说明表格，添加触发调用方式章节 |
| 1.0.2 | 2026-05-25 | 添加Skill目录结构规范章节，将目录结构错误列为P0问题 |
| 1.0.1 | 2026-05-25 | 添加FAQ.md和使用指南.md |
| 1.0.0 | 2026-05-25 | 初始版本，融合TDD+TRACE+SkillHub验证 |
---
**文档版本**：2.0.0
**更新日期**：2026-05-25
**核心能力**：TDD驱动的Skill质量优化工作流
