> 文档版本：2.0.0
> 创建日期：2026-05-25
> 更新日期：2026-05-25
> 核心定位：融合TDD方法论与TRACE五维评测的Skill质量优化引擎
> 适用场景：Skill发布前自检、质量优化、TRACE评测、SkillHub合规检查
┌─────────────────────────────────────────────────────────────────────────┐
│ TDD-Skill质量优化工作流 v1.0 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ RED阶段：定义成功标准 │ │
│ │ • 分析目标Skill的当前状态 │ │
│ │ • 确定质量目标和评测维度 │ │
│ │ • 制定可衡量的改进标准 │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ GREEN阶段：生成达标输出 │ │
│ │ • 执行TRACE五维质量评测 │ │
│ │ • 执行SkillHub发布验证 │ │
│ │ • 识别P0/P1/P2级问题 │ │
│ │ • 生成基础达标版本 │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ REFACTOR阶段：优化完善 │ │
│ │ • 修复P0/P1级问题 │ │
│ │ • 优化文档结构和内容 │ │
│ │ • 增强功能和示例 │ │
│ │ • 验证优化效果 │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌───────────────────┐ │
│ │ 循环优化直到达标 │ │
│ └───────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
| 维度 | 优势 |
|---|---|
| ------ | ------ |
| 方法论融合 | 融合Red/Green/TDD + TRACE五维 + SkillHub验证 |
| 循环优化 | RED→GREEN→REFACTOR循环直到达标 |
| 全面评测 | 五维评测(T/R/A/C/E) + 发布合规性检查 |
| 智能修复 | P0/P1/P2问题自动识别和修复建议 |
| 开箱即用 | 纯内容Skill，无外部依赖 |
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| ------ | ------ | ------ | -------- | ------ |
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 |
何时调用：
调用方式：
# 直接调用示例
优化我的Skill：/path/to/skill
目标评分：4.5
评测深度：deep
| 维度 | 名称 | 核心问题 | 目标评分 |
|---|---|---|---|
| ------ | ------ | ---------- | ---------- |
| 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 |
| 评分 | 等级 | 说明 | 行动 |
|---|---|---|---|
| ------ | ------ | ------ | ------ |
| 4.5-5.0 | 优秀 | 达到发布标准 | 可直接发布 |
| 4.0-4.4 | 良好 | 基本达到发布标准 | 建议优化后发布 |
| 3.5-3.9 | 一般 | 有问题需修复 | 修复后发布 |
| 3.0-3.4 | 较差 | 需重大改进 | 重大改进后发布 |
| <3.0 | 不合格 | 阻塞发布 | 必须修复P0问题 |
每次优化前，先分析目标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
- [ ] 发布合规性通过（如果是发布目标）
| 深度 | 适用场景 | 评测耗时 |
|---|---|---|
| ------ | ---------- | ---------- |
| minimal | 快速预检 | <1秒 |
| normal | 标准评测 | 1-3秒 |
| deep | 发布前最终审核 | 5-10秒 |
对目标Skill执行完整的TRACE五维评测：
## TRACE评测检查项
### T - Trust 可信任度
- [ ] 安全性检查通过
- [ ] 国内适配性检查通过
- [ ] 无敏感信息泄露
### R - Reliability 可靠性
- [ ] 重试机制存在
- [ ] 超时处理完善
- [ ] 错误提示友好
### A - Adaptability 适用性
- [ ] 能力边界清晰
- [ ] 触发条件明确
- [ ] 输入输出示例完整
### C - Convention 规范性
- [ ] 文档结构分层
- [ ] FAQ完备
- [ ] 反模式说明存在
### E - Effectiveness 有效性
- [ ] 输出准确可靠
- [ ] 内容完整
- [ ] 开箱即用
## 问题分级
### P0级（阻塞发布-必须立即修复）
- SKILL.md不存在
- 缺少必需frontmatter字段
- __pycache__或.pyc文件存在
- 安全漏洞
- **目录结构错误**（Skill/子目录存在，文件未在根目录）
### P1级（严重-短期改进）
- 缺少FAQ文档
- 错误处理不完善
- 示例不完整
- 版本不一致
### P2级（一般-可选优化）
- .DS_Store存在
- 文档格式不规范
- 注释缺失
## 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
## 修复执行顺序
### 第一轮：P0问题修复
1. **修复目录结构错误**（如有Skill/子目录，移文件到根目录）
2. 补充缺失的必需文件
3. 修复缺失的frontmatter字段
4. 清理Python缓存文件
5. 修复安全漏洞
### 第二轮：P1问题修复
1. 补充FAQ文档
2. 完善错误处理说明
3. 增加输入输出示例
4. 同步版本号
### 第三轮：增强优化
1. 优化文档结构
2. 补充反模式说明
3. 增加使用场景
4. 完善验证清单
## FAQ文档模板
### 常见问题解答 (FAQ)
#### Q1: {问题1}
{详细解答}
#### Q2: {问题2}
{详细解答}
#### Q3: {问题3}
{详细解答}
## 反模式说明模板
### ❌ 错误用法
- 错误用法1 - 会导致什么问题
- 错误用法2 - 会导致什么问题
### ✅ 正确用法
- 正确用法1 - 为什么有效
- 正确用法2 - 为什么有效
生成的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
❌ 错误：文件放在子目录
skill-name/
└── Skill/ ← 错误！不应有子目录
├── SKILL.md
├── _meta.json
└── metadata.json
❌ 错误：空目录
skill-name/
├── examples/ ← 空目录！内容必须在根目录
├── references/ ← 空目录！
└── SKILL.md
✅ 正确：所有文件在根目录
RedGreen-TDD/
├── SKILL.md
├── _meta.json
├── metadata.json
├── README.md
├── FAQ.md
├── examples/
│ ├── 示例1-写文案.md
│ └── 示例2-代码开发.md
└── references/
└── TDD原理详解.md
## P0级问题：目录结构错误
IF 发现 "Skill/" 子目录存在 THEN
检测为 P0 问题：输出目录错误
修复方案：将 Skill/ 目录下的文件移到根目录
IF examples/ 或 references/ 目录存在但为空 THEN
检测为 P1 问题：辅助目录为空
修复方案：删除空目录或将内容移入
| 文件类型 | 放置位置 | 说明 |
|---|---|---|
| ---------- | ---------- | ------ |
| 核心文件 | 根目录 | SKILL.md, _meta.json, metadata.json |
| 说明文档 | 根目录 | README.md, FAQ.md, 使用指南.md |
| 示例内容 | examples/ | 有实际内容的示例文件 |
| 参考资料 | references/ | 有实际内容的参考文档 |
| 工具脚本 | tools/ | 需要工具功能时才创建 |
┌─────────────────────────────────────────────────────────────────────────┐
│ Step 1: RED - 定义成功标准 │
│ │
│ • 分析目标Skill当前状态 │
│ • 确定目标评分和评测深度 │
│ • 制定改进范围和优先级 │
└─────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────┐
│ Step 2: GREEN - 执行评测 │
│ │
│ • 执行TRACE五维评测 │
│ • 执行SkillHub合规检查 │
│ • 识别所有P0/P1/P2问题 │
│ • 生成详细评测报告 │
└─────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────┐
│ Step 3: REFACTOR - 优化修复 │
│ │
│ • 第一轮：修复P0问题 │
│ • 第二轮：修复P1问题 │
│ • 第三轮：增强优化 │
│ • 验证修复效果 │
└─────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────┐
│ 评分达标？ │
└──────┬──────┘
YES ↓ ↓ NO
┌──────────┐ 返回Step 1
│ 完成输出 │ 重新定义目标
└──────────┘
## 快速执行模板
### 输入
目标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}
输入：
目标：优化现有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
发布准备度：✅ 可发布
输入：
目标：学习如何用TDD方法开发Skill
深度：normal
执行：
## RED
目标：理解TDD开发Skill的完整流程
成功标准：
- [ ] 理解RED/GREEN/REFACTOR三阶段
- [ ] 能够应用到实际开发中
- [ ] 建立质量优化意识
## GREEN
展示TDD-Skill工作流的完整示例
提供学习方法和建议
## REFACTOR
补充学习资源推荐
提供练习项目建议
## 错误处理策略
### 错误类型与处理方式
| 错误类型 | 代码 | 策略 | 处理方式 |
|----------|------|------|----------|
| Skill路径不存在 | EH001 | error_message | 返回友好错误信息 |
| 评测执行失败 | EH002 | partial_result | 返回已完成的评测部分 |
| 文件读取失败 | EH003 | skip_continue | 跳过问题文件继续评测 |
| JSON解析错误 | EH004 | error_message | 指出具体文件和位置 |
| 版本不一致 | EH005 | auto_fix | 自动同步版本号 |
### 错误信息模板
提示："指定的Skill路径不存在，请检查路径是否正确"
帮助："支持的路径格式：绝对路径或相对路径"
提示："部分评测失败"
帮助："返回已完成的评测结果，剩余部分请手动检查"
提示："无法读取{filename}"
帮助："检查文件权限或文件是否损坏"
提示："{filename}的JSON格式错误（第{line}行）"
帮助："请使用JSON验证工具检查格式"
提示："检测到版本不一致，已自动同步为{version}"
帮助："建议检查各文件的version字段是否一致"
### 8.2 重试机制
| 场景 | 重试次数 | 重试间隔 | 说明 |
|---|---|---|---|
| ------ | ---------- | ---------- | ------ |
| 网络请求 | 2次 | 1秒 | 评测工具调用时 |
| 文件扫描 | 1次 | 0秒 | 立即重试 |
| 评测执行 | 1次 | 0秒 | 跳过继续 |
满足以下条件时触发重试：
以下情况不重试，直接报错：
### 8.3 超时配置
| 操作 | 超时时间 | 说明 |
|---|---|---|
| ------ | ---------- | ------ |
| minimal评测 | 10秒 | 快速文件扫描 |
| normal评测 | 30秒 | 完整五维评测 |
| deep评测 | 60秒 | 深度内容分析 |
评测超时后：
---
## 十、自验证清单
### 9.1 TDD-Skill工作流自验证
### 9.2 R-Reliability自检清单
---
## 十一、质量指标定义
### 10.1 评分标准体系
| 维度 | 指标名称 | 核心问题 | 目标评分 |
|---|---|---|---|
| ------ | ---------- | ---------- | ---------- |
| 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 |
---
## 十二、使用限制与故障排除
### 10.1 使用限制
| 评分 | 等级 | 说明 | 行动建议 |
|---|---|---|---|
| ------ | ------ | ------ | ---------- |
| 4.5-5.0 | 优秀 | 达到发布标准 | 可直接发布 |
| 4.0-4.4 | 良好 | 基本达到发布标准 | 建议优化后发布 |
| 3.5-3.9 | 一般 | 有问题需修复 | 修复后发布 |
| 3.0-3.4 | 较差 | 需重大改进 | 重大改进后发布 |
| <3.0 | 不合格 | 阻塞发布 | 必须修复P0问题 |
### 10.2 故障排除
症状：评测过程中报错或中断
排查步骤：
解决方案：
# 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
症状：评测结果显示评分与预期不符
排查步骤：
解决方案：
症状：评测报告提示版本号不一致
排查步骤：
解决方案：
# 同步版本号
# 确保三个文件的version字段一致
症状：SkillHub验证显示不可发布
排查步骤：
解决方案：
---
## 十三、相关资源
### 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质量优化工作流
共 1 个版本