quality-audit

质量审计技能

用于从四个维度评估技能质量的系统化框架：清晰度、完整性、准确性和实用性。

何时使用此技能

• 在将新技能添加到注册表之前进行审核
• 审计现有技能，以提升质量
• 为技能验证制定质量评分标准
• 统一技能库中的技能质量
• 为技能投入生产使用做准备

核心原则

四个质量维度

维度	权重	关注点
清晰度	25%	结构、可读性、渐进式呈现
完整性	25%	覆盖范围、示例、边缘情况、反模式
准确性	30%	正确性、最佳实践、安全性
实用性	20%	现实应用、生产就绪度

评分等级（1-5）

分数	标签	含义
1	不可接受	存在根本性缺陷、危险或无法使用
2	需要改进	存在需要大幅修订的重大问题
3	可接受	达到最低标准，功能正常
4	良好	质量较高，仍有小幅改进空间
5	优秀	堪称典范，已达到生产就绪水平，表现出众

通过标准

• 最低要求：加权平均分达到 3.0（可接受）
• 目标：加权平均分达到 4.0（良好）
• 卓越：加权平均分达到 4.5+（优秀）
• 阻断项：准确性必须 ≥3.0（不得包含危险建议）

审计工作流

阶段 1：结构检查

checklist:
  structure:
    - [ ] Has valid YAML frontmatter
    - [ ] Contains required metadata (name, description)
    - [ ] Follows progressive disclosure (Tier 1 → 2 → 3)
    - [ ] Sections are logically ordered
    - [ ] Token estimate is reasonable (<5000 for core)

阶段 2：内容评估

checklist:
  content:
    - [ ] "When to Use" section is clear
    - [ ] Core principles are well-defined
    - [ ] Code examples are complete and runnable
    - [ ] Anti-patterns are documented
    - [ ] Troubleshooting guidance exists

阶段 3：维度评分

针对每个维度，根据具体标准进行评估：

清晰度标准：

• 各部分组织良好，逻辑连贯
• 解释简洁，避免术语过多
• 代码示例易读且注释充分
• 从简单到复杂逐步呈现

完整性标准：

• 全面涵盖核心概念
• 包含边缘情况和错误处理
• 同时说明应做和不应做的事项
• 为主要用例提供可运行的示例

准确性标准：

• 代码示例可编译或运行，且无错误
• 遵循当前最佳实践（不使用已弃用的做法）
• 安全注意事项正确无误
• 性能声明可验证

实用性标准：

• 示例能够解决现实问题
• 可立即应用
• 适用于生产用例并能随之扩展
• 包含故障排除指南

阶段 4：生成报告

## Audit Report: {skill_name}

**Date**: {date}
**Auditor**: {auditor}
**Status**: {PASS|FAIL|NEEDS_REVIEW}

### Scores

| Dimension | Score | Weight | Weighted |
|-----------|-------|--------|----------|
| Clarity | {x}/5 | 25% | {x*0.25} |
| Completeness | {x}/5 | 25% | {x*0.25} |
| Accuracy | {x}/5 | 30% | {x*0.30} |
| Usefulness | {x}/5 | 20% | {x*0.20} |
| **Total** | | | **{sum}/5** |

### Issues Found

- [CRITICAL] {issue description}
- [MAJOR] {issue description}
- [MINOR] {issue description}

### Recommendations

1. {actionable recommendation}
2. {actionable recommendation}

实施模式

模式 1：快速审计（5 分钟审查）

用于快速评估技能质量：

# Run automated structure checks
cortex skills audit <skill-name> --quick

# Output: Pass/Fail with basic metrics

快速审计检查项：

1. YAML frontmatter 是否有效？
2. 是否包含必需部分？
3. 代码块是否标注了语言？
4. 是否没有 TODO/FIXME 标记？
5. Token 数量是否合理？

模式 2：完整审计（15-30 分钟审查）

通过人工审查进行全面评估：

# Generate full audit report
cortex skills audit <skill-name> --full

# Interactive mode for scoring
cortex skills audit <skill-name> --interactive

完整审计流程：

1. 运行自动化检查
2. 手动通读内容
3. 测试代码示例
4. 为各维度评分
5. 记录问题和建议
6. 生成报告

模式 3：对比审计

将技能与参考实现进行比较：

# Compare against template-skill-enhanced
cortex skills audit <skill-name> --compare template-skill-enhanced

模式 4：批量审计

审计多个技能，检查注册表的健康状况：

# Audit all skills in a category
cortex skills audit --category security

# Audit skills below threshold
cortex skills audit --below-score 3.5

CLI 命令

# Basic audit
cortex skills audit <skill-name>

# Options
  --quick           Quick structural check only
  --full            Full audit with all dimensions
  --interactive     Interactive scoring mode
  --output FILE     Write report to file
  --format FORMAT   Output format (markdown|json|yaml)
  --compare SKILL   Compare against reference skill
  --fix             Auto-fix simple issues (formatting)

创建自定义评分标准

技能可以在 validation/rubric.yaml 中定义自定义评分标准：

# validation/rubric.yaml
version: "1.0.0"
skill_name: my-skill

dimensions:
  clarity:
    weight: 25
    criteria:
      - "API examples use realistic data"
      - "Error handling is shown for each operation"
  completeness:
    weight: 25
    criteria:
      - "Covers all HTTP methods"
      - "Includes pagination patterns"
  accuracy:
    weight: 30
    criteria:
      - "Follows REST conventions"
      - "Security headers documented"
  usefulness:
    weight: 20
    criteria:
      - "Examples work with common frameworks"

passing_criteria:
  minimum_score: 3.5  # Higher bar for this skill
  required_dimensions:
    - accuracy
    - completeness

最佳实践

应做事项

• 具体明确——写“第 45 行：SQL 查询存在注入漏洞”，而不是“存在安全问题”
• 可执行——说明如何修复每个问题
• 公平一致——始终使用同一套标准
• 记录依据——针对每项评分引用具体内容
• 区分优先级——先处理关键问题，最后给出建议

不应做事项

• 不要根据个人风格偏好评分
• 标记已弃用的模式时，不要遗漏替代方案
• 不要因缺少可选部分而判定技能不合格
• 不要因其他评分较高而忽视安全问题
• 不要仓促审计复杂技能

反模式

橡皮图章

问题：未经全面审查就批准技能 为何有害：低质量技能会削弱人们对技能库的信任 解决方法：使用完整的审查清单，测试代码示例

完美主义障碍

问题：因小问题而否决技能 为何有害：导致实用技能无法上线 解决方法：区分阻碍性问题和建议

评分虚高

问题：没有依据就给出高分 为何有害：评分会失去意义 解决方法：为每项评分记录具体证据

与 CI/CD 集成

# .github/workflows/skill-quality.yml
name: Skill Quality Gate

on:
  pull_request:
    paths:
      - 'skills/**'

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install cortex
        run: pip install cortex
      - name: Audit changed skills
        run: |
          for skill in $(git diff --name-only HEAD~1 | grep 'skills/' | cut -d'/' -f2 | uniq); do
            cortex skills audit "$skill" --quick --fail-under 3.0
          done

故障排除

“审查失败，但技能看起来没问题”

1. 检查 YAML frontmatter 语法
2. 确认所有必需的章节都存在
3. 确保代码块带有语言标签
4. 检查是否存在隐藏字符（复制/粘贴问题）

“评分似乎不一致”

1. 查看每个维度的评分指南
2. 先审查 template-skill-enhanced，以校准评分
3. 使用 --interactive 模式，让评判标准更清晰

外部资源

• 技能模板参考
• 评分标准架构
• 技能创建指南

更新日志

1.0.0 (2026-01-05)

• 首次发布
• 四维评分框架
• CLI 集成
• CI/CD 工作流示例