AgentEval：AI技能文件静态分析工具，提升开发效率与跨平台兼容性

1. 项目概述：为什么我们需要一个AI技能文件的“质检员”？

如果你正在为Claude Code、VS Code Copilot、Cursor这类AI编程助手开发自定义技能（Skill），那你肯定遇到过这样的场景：你花了好几个小时精心编写了一个SKILL.md文件，满心欢喜地提交到仓库，结果在CI流水线里莫名其妙地失败了。或者更糟，技能文件虽然通过了CI，但在VS Code里死活不显示，或者Claude Code调用时总是报错。你反复检查YAML语法，确认路径没错，但问题就是找不到。这种挫败感，我经历过太多次了。

问题的根源在于，当前AI技能生态的规范（如agentskills.io）虽然定义了标准，但各家平台（Claude Code、VS Code、Cursor）的实现细节、兼容性要求和“潜规则”各不相同。一个在Claude Code上运行良好的技能，放到VS Code里可能因为一个字段不匹配就被静默忽略。更不用说，技能描述的质量直接决定了AI助手能否正确理解并触发它——一个模糊的描述等于让技能“隐形”。

AgentEval就是为了解决这个痛点而生的。你可以把它理解为你技能文件的“专职质检员”。它不是一个运行时工具，而是一个静态分析器，在代码提交前、CI构建时，对你的SKILL.md和agent.md文件进行全方位的“体检”。从最基本的YAML字段校验、命名规范，到描述质量评分、文件引用检查，再到跨平台兼容性预警，它把那些容易踩坑、文档里又语焉不详的细节，全都给你明明白白地检查出来。

我最初接触这个工具，是因为团队里一个初级开发者提交的技能在VS Code上始终无法加载，排查了半天才发现是技能name字段和目录名差了一个连字符。自那以后，我就把AgentEval集成到了所有项目的CI流程里。它带来的不仅仅是错误拦截，更是一种开发范式的转变：将AI技能开发从“试错”模式转向了“质量门禁”模式。

2. 核心功能深度解析：AgentEval到底在检查什么？

AgentEval的检查规则不是凭空捏造的，其权威性主要来源于两个层面：一是对agentskills.io官方规范的严格遵循，二是对主流AI助手平台（Claude Code、VS Code Copilot等）实际行为的逆向工程和经验总结。它的检查可以归纳为以下六个核心维度，每一个维度都对应着开发中实实在在的坑。

2.1 元数据（Frontmatter）验证：筑牢技能的地基

技能文件开头的YAML块（Frontmatter）是技能的“身份证”和“说明书”，这里出问题，技能基本就废了。AgentEval的检查细致到了令人发指的程度。

基础字段完备性与类型检查：它首先确保name和description这两个必填字段存在。这里有个隐藏的坑：YAML的灵活性有时是魔鬼。如果你写name: 123，YAML解析器可能会将其识别为数字类型，而AgentEval的frontmatter.name.type规则会将其标记为错误，因为规范要求它是字符串。同样，description也不能是null或布尔值。

命名规范（Naming Convention）：这是重灾区，尤其是跨平台兼容时。

• 字符集：name只能包含小写字母、数字和连字符（-）。大写字母、下划线都是非法的。
• 连字符规则：不能以连字符开头或结尾（-my-skill或my-skill-），也不能有连续的连字符（my--skill）。这些规则主要是为了兼容URL和文件系统路径的通用规范。
• 长度限制：name不超过64字符，description不超过1024字符。超长不仅影响可读性，在有些平台的UI里还会被截断。
• 保留字检查：你不能把技能命名为claude或anthropic这类平台保留字，AgentEval的frontmatter.name.reserved-word规则会阻止你。

描述（Description）质量与合规：

• 内容禁忌：描述里不能包含XML/HTML标签（<b>等），也不能使用第一、二人称（如“我提供的功能是...”、“你可以用它来...”）。技能描述应该是客观的第三人称说明。
• 核心：描述质量评分：这是AgentEval最智能的功能之一。它通过一套启发式算法（而非调用大模型）为描述打分（0-100分）。评分主要考察：
  1. 行动动词：描述是否以明确的动作开头？例如，“格式化JSON数据”就比“这是一个处理JSON的工具”要好得多。
  2. 触发短语：描述中是否包含了AI助手可能识别的关键词？例如，“当用户需要美化代码时...”。
  3. 关键词密度：是否避免了过于空泛的词汇，包含了具体的技术栈或问题领域关键词？
  4. 长度适宜性：过短可能信息不足，过长则影响AI快速理解。 一个低于50分的描述，很可能意味着你的技能在AI助手的自然语言交互中被发现和调用的概率极低。AgentEval会给出具体的改进建议，比如“建议以行动动词开头”。

2.2 文件引用与路径安全：避免“找不到文件”的噩梦

技能文件中经常会引用外部的代码示例、配置文件或数据文件（通过Markdown链接或source:指令）。AgentEval的引用检查能帮你提前发现路径错误和安全风险。

• 坏链检查：确保所有引用的相对路径（如[示例代码](./examples/demo.py)）指向的文件在磁盘上真实存在。这能防止技能文档看起来完美，但实际调用时因缺失依赖文件而失败。
• 路径深度限制：规范通常要求引用的文件必须在技能文件所在目录或其直接子目录内（不超过一级）。这是为了防止技能文件任意访问项目其他敏感部分。AgentEval的references.depth-exceeded规则会警告你引用到了../../config这类深层路径。
• 路径遍历攻击防护：这是一个重要的安全特性（对应CWE-59漏洞）。它会检查引用路径是否包含../等序列，可能试图逃逸出技能目录。虽然技能运行在沙盒环境，但良好的实践应从源头杜绝此类模式。

2.3 令牌预算与体积控制：别让技能“超重”

AI助手处理技能文件时有上下文窗口限制。AgentEval通过令牌估算和行数统计，帮你把技能文件控制在合理大小。

• 三层预算模型：这是基于agentskills.io规范的最佳实践。
  1. 元数据预算：Frontmatter部分应控制在约100个令牌内，确保AI能快速解析技能基本信息。
  2. 正文预算：技能说明正文应小于5000个令牌，这是核心指令的容量。
  3. 按需资源：大的代码块、数据应通过引用外部文件的方式提供，而非内嵌在文档中。
• 令牌估算：AgentEval默认使用一个轻量级启发式算法（约15%误差）估算令牌数。如果你追求更高精度，可以安装tiktoken库（OpenAI的分词器），能将误差降至5%左右。需要注意的是，Claude使用的分词器并未公开，因此任何估算都是近似值，但用于预算控制已经足够。
• 体积膨胀预警：它会特别标记文档中过大的代码块、Markdown表格或内嵌的Base64数据（如图片），这些是导致令牌数激增的“元凶”，建议将其移出到外部文件引用。

2.4 跨平台兼容性预警：一次编写，多端适配的桥梁

这是AgentEval区别于简单语法检查器的关键价值。它内置了针对不同AI助手平台的兼容性知识库。

• VS Code Copilot 的“潜规则”：VS Code对技能目录结构有严格要求。AgentEval的compat.vscode-dirname规则会检查技能name是否与父目录名完全一致。如果不一致，VS Code可能会静默忽略该技能，且不给出任何错误提示！这是最容易踩的坑之一。使用--strict-vscode参数可以将此警告提升为错误，强制要求匹配。
• Claude Code 专属字段：某些Frontmatter字段（如model）可能仅被Claude Code支持。在其他平台上，这些字段会被忽略，但AgentEval的compat.claude-only规则会给出提示，让你知道这个技能可能在其他平台功能受限。
• 未验证行为标注：对于Codex、Cursor等其他平台，某些字段的行为官方文档可能未明确说明。AgentEval会将其标记为compat.unverified（信息级别），提示你需要进行实际测试。

2.5 描述质量评分系统详解

前面提到了描述质量评分，这里展开讲讲其背后的逻辑和如何利用它。评分并非基于LLM的语义理解，而是基于一系列可量化的文本特征：

1. 行动动词检测：扫描描述开头句子，识别是否以“Create”、“Generate”、“Format”、“Analyze”、“Validate”等明确动词开头。没有行动动词会扣分。
2. 触发短语库匹配：内置一个常见任务触发词库（如“format code”, “debug”, “write tests”, “explain”），描述中包含这些短语会加分。
3. 停用词与模糊词比率：计算描述中“a”, “the”, “is”, “something”, “various”等非信息性词汇的比例。比率过高表明描述不够具体。
4. 名词实体与技术栈关键词：识别并统计描述中出现的编程语言、框架、工具名（如“Python”, “React”, “Docker”, “API”）。关键词越具体、越相关，得分越高。
5. 句子长度与结构：过短的句子可能信息不全，过长的复杂句可能影响可读性。会寻求一个平衡点。

实操心得：不要试图“欺骗”评分系统去堆砌关键词。评分的最终目的是提升技能的被发现率。一个高分描述通常自然符合“动作 + 对象 + 上下文/价值”的结构。例如，“LintPython codeto enforce PEP 8 style guideandcatch common bugs before commit”（动作：Lint；对象：Python code；价值：遵循PEP 8，在提交前捕获错误）。这样的描述，无论是AI还是人类，都能一眼看懂其用途。

2.6 输出与集成：无缝融入开发流程

AgentEval设计之初就考虑了自动化集成。

• 多种输出格式：
  • 终端彩色输出：适合本地开发，问题一目了然。
  • JSON格式：--format json参数输出结构化的结果，方便被其他脚本（如CI报告生成器）解析。
  • HTML报告：--html参数生成一个漂亮的、可交互的HTML报告，特别适合扫描整个插件目录，可以分标签页查看每个技能的详情。
• 明确的退出码：0成功，1存在错误，2输入错误。这使它可以无缝接入任何基于退出码判断成功的CI/CD系统。
• GitHub Action原生支持：官方提供的Action让集成变得极其简单，能在PR上直接标注出问题所在的行，并提供完整的检查结果摘要。

3. 从安装到实战：打造你的技能质量流水线

3.1 环境准备与安装

AgentEval是Python工具，安装非常简单。建议使用虚拟环境以隔离依赖。

# 1. 创建并进入虚拟环境（可选，但推荐） python -m venv venv source venv/bin/activate # Linux/macOS # venv\Scripts\activate # Windows # 2. 安装AgentEval pip install agenteval # 3. （可选）安装tiktoken以获得更精确的令牌计数 pip install tiktoken

如果你想贡献代码或运行测试，可以克隆源码并安装开发依赖：

git clone https://github.com/YoavLax/AgentEval.git cd AgentEval pip install -e ".[dev]" # 注意引号，这对于zsh等shell是必需的

3.2 本地开发中的常用命令与场景

在本地编写或修改技能时，你应该养成保存后立即运行AgentEval的习惯。

基本扫描：

# 检查单个技能文件 agenteval my_skill/SKILL.md # 递归检查整个技能目录 agenteval path/to/all_skills/

针对性检查：

# 我主要用VS Code，开启严格模式确保兼容性 agenteval my_skill/SKILL.md --target-agent vscode --strict-vscode # 我觉得描述很重要，要求质量分至少70 agenteval my_skill/SKILL.md --min-desc-score 70 # 我内嵌了一个大表格，想看看令牌数是否超标 agenteval my_skill/SKILL.md --max-tokens 6000 # 临时放宽限制查看具体数值

集成到编辑器：你可以配置编辑器的“保存后运行”或“快捷键”功能，将agenteval ${file}绑定到当前文件。这样，每次保存都能即时得到反馈。

3.3 集成到CI/CD：为团队设立质量门禁

这是AgentEval价值最大化的地方。以下是一个完整的GitHub Actions工作流示例，它会在每次推送或拉取请求时，检查指定目录下的所有技能。

# .github/workflows/validate-skills.yml name: Validate AI Skills on: push: branches: [ main, develop ] pull_request: branches: [ main ] jobs: skill-check: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Validate Skills with AgentEval uses: YoavLax/agenteval@v0 # 使用稳定的v0标签 with: path: 'skills/' # 你的技能存放目录 min-desc-score: 60 # 描述质量最低要求 strict-vscode: true # 确保VS Code兼容性 # ignore: 'frontmatter.field.unknown' # 如果需要忽略某些规则

这个工作流会带来什么？

1. PR注释：如果检查出错，错误和警告会直接显示在PR代码变更的行内，评审者一目了然。
2. 工作流摘要：整个检查结果的汇总表格会显示在Actions运行的详情页。
3. 门禁阻止：如果发现任何错误（exit-code 1），该步骤会失败，进而可以配置阻止PR合并，确保主分支上的技能都是合规的。

高级CI用法：你还可以将JSON输出传递给后续步骤，进行更复杂的处理，比如生成趋势报告或通知。

- name: Run AgentEval and Capture Output uses: YoavLax/agenteval@v0 id: agenteval # 给步骤一个ID，以便后续引用输出 with: path: 'skills/' format: json - name: Process Results (Example) run: | # 从步骤输出中读取JSON RESULTS='${{ steps.agenteval.outputs.json }}' # 使用jq解析，例如：统计失败文件数 FAIL_COUNT=$(echo $RESULTS | jq '.files_failed') echo "Number of files with errors: $FAIL_COUNT" # 可以根据结果决定后续操作，如上传报告等

3.4 处理常见冲突与例外情况

在实际团队协作中，你可能会遇到需要“破例”的情况。AgentEval提供了灵活的忽略机制。

• 忽略特定规则：假设团队决定暂时允许在描述中使用第一人称进行风格化表达，你可以忽略frontmatter.description.person-voice规则。

  agenteval skills/ --ignore frontmatter.description.person-voice

  在GitHub Action中，可以通过ignore输入传递多个规则前缀，用逗号分隔。

• 跳过文件系统检查：在某些CI环境中，代码被克隆到一个临时路径，目录结构可能与仓库内不同。此时，强制要求name匹配目录名的检查会失败。你可以使用--skip-dirname-check和--skip-ref-check来跳过这些依赖具体路径的检查。

  - uses: YoavLax/agenteval@v0 with: path: 'skills/' skip-dirname-check: true skip-ref-check: true

4. 避坑指南与最佳实践：来自实战的经验

在深度使用AgentEval并处理了上百个技能文件后，我总结出以下高频问题和应对策略。

4.1 命名与目录结构：VS Code兼容性的“头号杀手”

问题：技能在Claude Code上工作正常，在VS Code中却不显示。根因：VS Code Copilot对技能目录的命名有隐含要求，且错误处理是“静默失败”。解决方案：

1. 始终确保SKILL.md文件所在的直接父目录名称与技能Frontmatter中的name字段完全一致（包括大小写，通常都是小写）。
2. 在本地和CI中，都使用--strict-vscode参数运行AgentEval，将此问题提升为错误级别。
3. 项目结构标准化。我推荐的结构是：

   my-ai-plugin/ ├── skills/ │ ├── format-json/ # 目录名 │ │ └── SKILL.md # 其中 name: format-json │ └── generate-tests/ │ └── SKILL.md # 其中 name: generate-tests └── agent.md

4.2 描述写作：如何写出AI和人都能懂的“好描述”

低分描述示例：“这个技能可以用来处理数据。” (分数可能<30)问题：没有行动动词，没有触发点，没有具体价值。优化步骤：

1. 以强动词开头：将“处理”具体化为“清洗”、“转换”、“汇总”、“可视化”。
2. 明确对象和上下文：“处理数据” -> “清洗用户上传的CSV数据集”。
3. 点明价值或结果：“以确保数据质量” 或 “并生成初步分析报告”。
4. 融入触发短语：“当您需要从混乱的CSV中提取干净数据时...”

高分描述示例：“清洗并标准化用户上传的CSV文件，自动识别缺失值、重复项和格式错误，输出一个可用于分析的整洁表格。当您面对杂乱的原数据时使用此技能。” (分数可能>80)

实操心得：写完描述后，自己读一遍，并问：“如果我是AI，单看这句话，我能明白什么时候该调用这个技能吗？” 如果答案模糊，就继续修改。

4.3 令牌预算管理：与大代码块和表格的斗争

问题：技能文档因为内嵌了一个完整的100行示例代码而严重超重。解决方案：

1. 外部化：将大的代码示例、配置样本、数据片段移动到单独的文件中（如example_usage.py,config_template.yaml）。
2. 在SKILL.md中引用：使用Markdown链接或资源引用语法。

   请参考示例代码：[完整示例](./examples/full_demo.py)

3. 保持文档精简：文档正文应专注于说明技能的目的、输入、输出、使用步骤和注意事项。具体的实现细节放在外部文件。
4. 定期使用agenteval --max-tokens 5000来检查，确保核心文档体积受控。

4.4 处理“未验证”字段与平台差异

策略：

1. 分级处理：将技能字段分为“核心功能字段”（所有平台必需）和“增强字段”（平台特定）。
2. 使用条件注释：在技能文档中，可以为平台特定字段添加注释。

   # @claude-only: 此字段仅对Claude Code生效 model: claude-3-5-sonnet

3. 创建平台变体：对于核心技能，如果不同平台需求差异巨大，可以考虑维护多个变体文件，如SKILL.claude.md和SKILL.vscode.md，在CI中分别用--target-agent参数检查。

4.5 将AgentEval纳入团队开发规范

1. 预提交钩子：在项目中配置pre-commit钩子，在本地提交前自动运行AgentEval，防止低级错误进入仓库。
2. CI作为强制关卡：如上所述，在PR流程中设置必须通过的检查。
3. 新人入职清单：将“运行AgentEval并通过所有检查”作为技能开发流程的第一步。
4. 定期扫描存量技能：对仓库中已有的技能目录定期（如每月）执行全面扫描，使用--html生成报告，回顾并优化整体技能库质量。

5. 故障排除与高级技巧

即使工具很智能，有时你也会遇到令人困惑的输出。这里是一些常见问题的排查思路。

5.1 误报与规则调优

场景：AgentEval报告了一个你认为不是问题的问题。

• 检查规则来源：首先看规则ID（如compat.claude-only）。如果是spec（规范）要求的，那么你需要修改技能文件来符合规范。如果是advisory（建议），则代表这是最佳实践，你可以根据团队情况决定是否遵循。
• 使用--ignore：如果确定要忽略某条规则，可以在命令中临时忽略，或在CI配置中永久忽略。但请记录原因，避免技术债。
• 理解警告与错误的区别：错误（error）通常意味着技能可能无法正常工作（如缺少必填字段）。警告（warning）和建议（info）则提示有优化空间或潜在兼容性问题。在CI中，通常只让错误导致失败。

5.2 令牌计数不准怎么办？

现象：AgentEval估算的令牌数与你在其他工具（如OpenAI的Tokenizer工具）中看到的不同。

• 原因：AgentEval默认使用启发式估算，tiktoken使用GPT的分词器，而Claude使用其私有的分词器。三者均不相同。
• 对策：关注相对值，而非绝对值。工具的目的是控制规模。只要你的文档远低于阈值（如正文目标4000令牌，阈值5000），使用哪种估算方式的差异通常不影响判断。安装tiktoken能获得更接近通用LLM的估算值，对于跨平台技能更有参考意义。

5.3 在复杂项目结构中运行

场景：你的技能分散在多个子仓库或非常深的目录中。

• 使用Shell命令批量检查：

  # 查找所有SKILL.md文件并逐一检查 find . -name "SKILL.md" -type f -exec agenteval {} \;

• 使用--format json进行聚合分析：将每个文件的JSON结果收集起来，编写脚本进行汇总分析，找出共性问题。
• 注意路径上下文：--skip-ref-check和--skip-dirname-check在扫描整个代码库时可能有用，但会降低检查的严格性。更好的做法是规范项目结构，让所有技能都位于一个约定好的根目录下（如/ai/skills/）。

5.4 自定义检查规则（高级）

目前AgentEval本身不支持自定义规则。但你可以通过其JSON输出进行二次开发。

1. 运行agenteval --format json > report.json。
2. 编写一个Python脚本读取report.json。
3. 在脚本中添加你自己的业务逻辑检查（例如，检查技能名称是否遵循公司内部前缀规范，检查描述中是否包含了指向内部文档的链接等）。
4. 将这个自定义脚本作为CI流水线中的一个额外步骤。

我个人体会是，将AgentEval作为技能质量保障的第一道防线，已经能拦截90%以上的常见问题。它强迫开发者在早期就关注规范、兼容性和可发现性，这种“左移”的质量意识，其价值远超过工具本身。最后一个小技巧是，在团队内部分享那些由AgentEval捕获的、修复后显著提升了技能使用率的案例，这比任何文档都更能说服大家重视这项检查。