audit-agents-skills

审计 Agent/技能/命令（高级技能）

面向 Claude Code Agent、技能和命令的综合质量审计系统。根据行业最佳实践，提供量化评分、比较分析和生产就绪度评级。

目的

问题：手动验证 Agent/技能容易出错且缺乏一致性。根据《LangChain Agent Report 2026》，29.5% 的组织在未进行系统评估的情况下部署 Agent，导致“Agent 故障”成为首要挑战（18% 的团队）。

解决方案：根据 16 项加权标准进行自动化质量评分，并设置生产就绪度阈值（80% = 生产部署的最低 B 级）。

主要功能：

• 量化评分（Agent/技能为 32 分，命令为 20 分）
• 加权标准（身份 3 倍、提示词 2 倍、验证 1 倍、设计 2 倍）
• 生产就绪度评级（A-F 等级，阈值为 80%）
• 与参考模板进行比较分析
• 提供 JSON/Markdown 双格式输出，支持程序化集成
• 为未通过的标准提供修复建议

---

模式

模式	用法	输出
快速审计	仅检查最关键的 5 项标准	快速通过/失败（审计 20 个文件需 3-5 分钟）
完整审计	检查每个文件的全部 16 项标准	详细评分 + 建议（10-15 分钟）
比较审计	完整审计 + 与模板进行基准比较	分析 + 差距识别（15-20 分钟）

默认值：完整审计（建议首次运行时使用）

---

方法论

为什么选择这些标准？

这套 16 项标准框架源自：

1. Claude Code 最佳实践（《Ultimate Guide》第 4921 行：Agent 验证清单）
2. 行业数据（《LangChain Agent Report 2026》：评估缺口）
3. 生产环境故障（社区对硬编码路径、缺少错误处理的反馈）
4. 组合模式（技能应引用其他技能，Agent 应模块化）

评分原则

权重依据：

• 身份（3 倍）：如果用户找不到或无法调用 Agent，质量就无关紧要（可发现性 > 质量）
• 提示词（2 倍）：决定输出的可靠性和准确性
• 验证（1 倍）：提升健壮性，但优先级低于核心功能
• 设计（2 倍）：影响长期可维护性和可扩展性

等级标准：

• A（90-100%）：已达到生产就绪，风险极低
• B（80-89%）：良好，达到生产阈值
• C（70-79%）：生产部署前需要改进
• D（60-69%）：存在重大缺陷，尚未达到生产就绪
• F（<60%）：存在严重问题，需要大幅重构

与行业标准一致：80% 的阈值符合生产部署的软件工程最佳实践（例如，代码覆盖率 >80%、安全扫描通过率）。

---

工作流

阶段 1：发现

1. 扫描目录：

   .claude/agents/
   .claude/skills/
   .claude/commands/
   examples/agents/      (if exists)
   examples/skills/      (if exists)
   examples/commands/    (if exists)
   

2. 按类型（Agent/技能/命令）对文件进行分类

3. 加载参考模板（仅比较审计模式）：

   guide/examples/agents/     (benchmark files)
   guide/examples/skills/     (benchmark files)
   guide/examples/commands/   (benchmark files)
   

阶段 2：评分引擎

从 scoring/criteria.yaml 加载评分标准：

agents:
  max_points: 32
  categories:
    identity:
      weight: 3
      criteria:
        - id: A1.1
          name: "Clear name"
          points: 3
          detection: "frontmatter.name exists and is descriptive"
        # ... (16 total criteria)

对于每个文件：

1. 解析 frontmatter（YAML）
2. 提取内容章节
3. 运行检测模式（正则表达式、关键词搜索）
4. 计算得分：(points / max_points) × 100
5. 分配等级（A-F）

阶段 3：比较分析（仅比较审计模式）

对于每个项目文件：

1. 查找最匹配的模板（按描述相似度）
2. 比较各项标准的得分
3. 识别差距：template_score - project_score
4. 标记重大差距（差异 >10 分）

示例：

Project file: .claude/agents/debugging-specialist.md (Score: 78%, Grade C)
Closest template: examples/agents/debugging-specialist.md (Score: 94%, Grade A)

Gaps:
- Anti-hallucination measures: -2 points (template has, project missing)
- Edge cases documented: -1 point (template has 5 examples, project has 1)
- Integration documented: -1 point (template references 3 skills, project none)

Total gap: 16 points (explains C vs A difference)

阶段 4：生成报告

Markdown 报告（audit-report.md）：

• 摘要表格（总体 + 按类型）
• 各文件的得分和主要问题
• 各文件的详细分析（可折叠）
• 按优先级排序的建议

JSON 输出（audit-report.json）：

{
  "metadata": {
    "project_path": "/path/to/project",
    "audit_date": "2026-02-07",
    "mode": "full",
    "version": "1.0.0"
  },
  "summary": {
    "overall_score": 82.5,
    "overall_grade": "B",
    "total_files": 15,
    "production_ready_count": 10,
    "production_ready_percentage": 66.7
  },
  "by_type": {
    "agents": { "count": 5, "avg_score": 85.2, "grade": "B" },
    "skills": { "count": 8, "avg_score": 78.9, "grade": "C" },
    "commands": { "count": 2, "avg_score": 92.0, "grade": "A" }
  },
  "files": [
    {
      "path": ".claude/agents/debugging-specialist.md",
      "type": "agent",
      "score": 78.1,
      "grade": "C",
      "points_obtained": 25,
      "points_max": 32,
      "failed_criteria": [
        {
          "id": "A2.4",
          "name": "Anti-hallucination measures",
          "points_lost": 2,
          "recommendation": "Add section on source verification"
        }
      ]
    }
  ],
  "top_issues": [
    {
      "issue": "Missing error handling",
      "affected_files": 8,
      "impact": "Runtime failures unhandled",
      "priority": "high"
    }
  ]
}

阶段 5：修复建议（可选）

针对每项未通过的标准，生成可执行的修复建议：

### File: .claude/agents/debugging-specialist.md
**Issue**: Missing anti-hallucination measures (2 points lost)

**Fix**:
Add this section after "Methodology":

## Source Verification

- Always cite sources for technical claims
- Use phrases: "According to [documentation]...", "Based on [tool output]..."
- If uncertain, state: "I don't have verified information on..."
- Never invent: statistics, version numbers, API signatures, stack traces

**Detection**: Grep for keywords: "verify", "cite", "source", "evidence"

---

评分标准

完整定义请参阅 scoring/criteria.yaml。摘要如下：

Agent（最多 32 分）

类别	权重	标准数量	最高分
身份	3x	4	12
提示词质量	2x	4	8
验证	1x	4	4
设计	2x	4	8

关键标准：

• 名称清晰（3 分）：不能使用“agent1”这类泛泛的名称
• 描述包含触发条件（3 分）：包含“when”/“use”
• 定义角色（2 分）：包含“You are...”声明
• 3 个以上示例（1 分）：记录使用场景
• 职责单一（2 分）：专注明确，而非“通用”

技能（最多 32 分）

类别	权重	标准数量	最高分
结构	3x	4	12
内容	2x	4	8
技术	1x	4	4
设计	2x	4	8

关键标准：

• 有效的 SKILL.md（3 分）：命名规范
• 名称有效（3 分）：小写，1-64 个字符，不含空格
• 描述方法论（2 分）：包含工作流部分
• 不包含硬编码路径（1 分）：不含 /Users/、/home/
• 触发条件清晰（2 分）：包含“When to use”部分

命令（最多 20 分）

类别	权重	标准数量	最高分
结构	3x	4	12
质量	2x	4	8

关键标准：

• 有效的 frontmatter（3 分）：包含 name 和 description
• 参数提示（3 分）：使用 $ARGUMENTS 时提供
• 分步工作流（3 分）：包含编号章节
• 错误处理（2 分）：提及失败模式

---

检测模式

Frontmatter 解析

import yaml
import re

def parse_frontmatter(content):
    match = re.search(r'^---\n(.*?)\n---', content, re.DOTALL)
    if match:
        return yaml.safe_load(match.group(1))
    return None

关键词检测

def has_keywords(text, keywords):
    text_lower = text.lower()
    return any(kw in text_lower for kw in keywords)

# Example
has_trigger = has_keywords(description, ['when', 'use', 'trigger'])
has_error_handling = has_keywords(content, ['error', 'failure', 'fallback'])

重叠检测（重复检查）

def jaccard_similarity(text1, text2):
    words1 = set(text1.lower().split())
    words2 = set(text2.lower().split())
    intersection = words1 & words2
    union = words1 | words2
    return len(intersection) / len(union) if union else 0

# Flag if similarity > 0.5 (50% keyword overlap)
if jaccard_similarity(desc1, desc2) > 0.5:
    issues.append("High overlap with another file")

Token 计数（近似值）

def estimate_tokens(text):
    # Rough estimate: 1 token ≈ 0.75 words
    word_count = len(text.split())
    return int(word_count * 1.3)

# Check budget
tokens = estimate_tokens(file_content)
if tokens > 5000:
    issues.append("File too large (>5K tokens)")

---

行业背景

来源：LangChain Agent Report 2026（公开报告，第 14-22 页）

主要发现：

• 29.5% 的组织部署 Agent 时未进行系统性评估
• 18% 将“Agent 缺陷”列为主要挑战
• 仅 12% 使用自动化质量检查（88% 采用人工检查或完全不检查）
• 43% 表示难以长期维持 Agent 质量
• 主要问题：幻觉（31%）、错误处理不佳（28%）、触发条件不明确（22%）

影响：

1. 自动化缺口：大多数团队依赖人工检查清单（规模扩大后容易出错）
2. 质量债务：未经验证就部署的 Agent 会积累技术债务
3. 维护负担：43% 的团队难以长期维持质量（没有跟踪系统）

此技能解决的问题：

• 自动化：用量化评分取代人工检查清单
• 跟踪：JSON 输出支持分析长期趋势
• 标准：80% 的门槛为生产环境设置了明确的准入标准

---

输出示例

快速审计（前 5 项标准）

# Quick Audit: Agents/Skills/Commands

**Files**: 15 (5 agents, 8 skills, 2 commands)
**Critical Issues**: 3 files fail top-5 criteria

## Top-5 Criteria (Pass/Fail)

| File | Valid Name | Has Triggers | Error Handling | No Hardcoded Paths | Examples |
|------|------------|--------------|----------------|--------------------|----------|
| agent1.md | ✅ | ✅ | ❌ | ✅ | ❌ |
| skill2/ | ✅ | ❌ | ✅ | ❌ | ✅ |

## Action Required

1. **Add error handling**: 5 files
2. **Remove hardcoded paths**: 3 files
3. **Add usage examples**: 4 files

完整审计

完整结构请参见上文的阶段 4：报告生成。

对比（完整结果 + 基准）

# Comparative Audit

## Project vs Templates

| File | Project Score | Template Score | Gap | Top Missing |
|------|---------------|----------------|-----|-------------|
| debugging-specialist.md | 78% (C) | 94% (A) | -16 pts | Anti-hallucination, edge cases |
| testing-expert/ | 85% (B) | 91% (A) | -6 pts | Integration docs |

## Recommendations

Focus on these gaps to reach template quality:
1. **Anti-hallucination measures** (8 files): Add source verification sections
2. **Edge case documentation** (5 files): Add failure scenario examples
3. **Integration documentation** (4 files): List compatible agents/skills

---

用法

基础用法（完整审计）

# In Claude Code
Use skill: audit-agents-skills

# Specify path
Use skill: audit-agents-skills for ~/projects/my-app

使用选项

# Quick audit (fast)
Use skill: audit-agents-skills with mode=quick

# Comparative (benchmark analysis)
Use skill: audit-agents-skills with mode=comparative

# Generate fixes
Use skill: audit-agents-skills with fixes=true

# Custom output path
Use skill: audit-agents-skills with output=~/Desktop/audit.json

仅输出 JSON

# For programmatic integration
Use skill: audit-agents-skills with format=json output=audit.json

---

与 CI/CD 集成

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

# Run quick audit on changed agent/skill/command files
changed_files=$(git diff --cached --name-only | grep -E "^\.claude/(agents|skills|commands)/")

if [ -n "$changed_files" ]; then
    echo "Running quick audit on changed files..."
    # Run audit (requires Claude Code CLI wrapper)
    # Exit with 1 if any file scores <80%
fi

GitHub Actions

name: Audit Agents/Skills
on: [pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run quality audit
        run: |
          # Run audit skill
          # Parse JSON output
          # Fail if overall_score < 80

---

对比：命令与技能

方面	命令（/audit-agents-skills）	技能（此文件）
范围	仅当前项目	多项目对比
输出	Markdown 报告	Markdown + JSON
速度	快（5-10 分钟）	较慢（对比审计需 10-20 分钟）
深度	标准的 16 项标准	相同标准 + 基准分析
修复建议	通过 --fix 标志提供	内置建议
程序化处理	终端输出	JSON，可集成到 CI/CD
适用场景	快速检查、开发工作流	深度审计、质量跟踪

建议：日常检查使用命令；发布准入检查和质量跟踪使用技能。

---

维护

更新标准

编辑 scoring/criteria.yaml：

agents:
  categories:
    identity:
      criteria:
        - id: A1.5  # New criterion
          name: "API versioning specified"
          points: 3
          detection: "mentions API version or compatibility"

版本升级：标准变更时，递增 frontmatter 中的 version。

添加文件类型

要支持新的文件类型（例如“工作流”）：

1. 在 scoring/criteria.yaml 中添加：

   workflows:
     max_points: 24
     categories: [...]
   

2. 更新检测逻辑（文件路径模式）
3. 更新报告模板

---

相关内容

• 命令版本：.claude/commands/audit-agents-skills.md
• Agent 验证清单：guide 第 4921 行（手动检查 16 项标准）
• Skill 验证：guide 第 5491 行（规范文档）
• 参考模板：examples/agents/、examples/skills/、examples/commands/

---

更新日志

v1.0.0（2026-02-07）：

• 首次发布
• 16 项标准框架（agents/skills/commands）
• 3 种审计模式（快速/完整/对比）
• JSON + Markdown 输出
• 修复建议
• 行业背景（LangChain 2026 报告）

---

Skill 已就绪，可供使用：audit-agents-skills