AgentEval：AI技能文件的静态分析与质量门禁工具

1. 项目概述：为AI技能文件装上“质检仪”

在AI智能体（Agent）开发如火如荼的今天，无论是Claude Code、VS Code Copilot还是Cursor，一个核心的交互单元就是“技能”（Skill）。这些技能通常以SKILL.md或agent.md这样的Markdown文件为载体，里面定义了技能的名称、描述、触发方式以及核心指令。然而，你有没有遇到过这样的场景：精心编写的技能，在VS Code里死活不出现；或者描述写得天花乱坠，AI却从来不会调用它？问题往往就出在这些看似简单的元数据文件上——一个拼写错误、一个格式违规、一个命名不匹配，都可能导致整个技能“隐形”。

AgentEval正是为了解决这个痛点而生的。它不是什么复杂的AI模型训练框架，而是一个专为SKILL.md和agent.md文件设计的“静态分析器”或“质量门禁”。你可以把它理解为你代码仓库的ESLint或Prettier，但它的审查对象是AI技能的“说明书”。它的核心使命，是在你的技能文件被提交到代码仓库、进而被分发到各个AI平台之前，提前发现并拦截那些会导致兼容性、可发现性或功能性问题的低级错误和潜在隐患。

这个工具基于 agentskills.io 规范，但不止步于此。它融合了来自Claude、VS Code等主流平台的实际要求和最佳实践，将散落在各处的规则集中化、自动化。无论你是独立开发者维护几个自用技能，还是团队在构建一个包含数十个技能的插件库，AgentEval都能帮你建立起一道可靠的质量防线，确保你的技能在任何目标平台上都能被正确识别和稳定运行。

2. 核心功能深度解析：不止于语法检查

AgentEval的检查项远不止是“YAML语法是否正确”这么简单。它从多个维度对技能文件进行立体扫描，确保其既符合规范，又具备高质量。下面我们来逐一拆解它的核心检查模块，理解每一项检查背后的实际意义和可能引发的生产问题。

2.1 元数据（Frontmatter）验证：规范的基石

技能文件的头部通常是一个YAML格式的Frontmatter块，包含了name、description等关键信息。AgentEval对此的检查极为严格。

名称（name）合规性：这可能是最容易出错的地方。规范要求名称只能包含小写字母、数字和连字符（hyphen）。AgentEval会检查是否存在非法字符（如下划线、大写字母），以及是否有前导或尾随的连字符（如-my-skill或my-skill-）。更关键的是，它严格执行“禁止连续连字符”的规则（如my--skill）。在实际开发中，开发者很容易在拼接名称时误操作产生连续连字符，而某些AI平台的解析器对此处理不一致，可能导致技能无法注册。

目录名匹配检查：这是针对VS Code Copilot的硬性要求。VS Code要求SKILL.md文件所在的直接父目录名称必须与技能name字段完全一致。如果不匹配，VS Code会直接、且没有任何错误提示地忽略这个技能文件。AgentEval的frontmatter.name.directory-mismatch规则就是为了捕获这个“沉默的杀手”。例如，你的技能name是pdf-processor，但文件却放在skills/pdf-tool/目录下，这个技能在VS Code中将永远不可见。

描述（description）质量与合规：描述是AI发现和理解技能的关键。AgentEval首先进行基础合规检查：描述不能为空，长度不能超过1024字符。更重要的是，它引入了两个“语义级”的检查：一是禁止在描述中使用XML/HTML标签，因为这不是纯文本描述该有的内容；二是禁止使用第一、第二人称代词（如“我”、“你”、“我们”）。技能描述应该是对技能功能的客观陈述，而不是拟人化的自述，这有助于AI更准确地理解其用途。

2.2 描述质量评分：从“合规”到“优秀”

合规的描述不一定是个好描述。一个模糊的描述如“处理文件”，AI很难知道何时该调用它。AgentEval的description.quality-score规则（0-100分）通过一系列启发式规则来评估描述的可发现性：

1. 行动动词：描述是否以明确的行动动词开头？例如，“转换PDF为Markdown”、“查询数据库”、“部署应用到云端”。以动词开头的描述能最清晰地传达技能的功能意图。
2. 触发短语：描述中是否包含了可能触发AI联想的短语？例如，“当用户需要…时”、“针对…场景”。这些短语有助于AI在对话上下文中匹配到你的技能。
3. 关键词密度：描述是否包含了与技能核心功能相关的关键词？避免使用过于空泛的词汇。
4. 长度适宜：过短的描述信息量不足，过长的描述可能包含冗余。AgentEval会评估描述长度是否在一个理想的范围内。

得分低于你通过--min-desc-score设定的阈值时，会触发警告。它会给出具体的改进建议，比如“建议以行动动词开头”。这个评分虽然基于规则而非LLM，但能有效过滤掉那些明显不利于AI发现的低质量描述。

2.3 文件引用与资源安全：防范路径遍历风险

许多技能需要引用同目录下的其他资源文件，比如配置文件、示例代码或图片。在Markdown中，我们通常使用相对路径链接。

AgentEval的引用验证模块会解析技能文件正文中的所有Markdown链接（[text](./file.py)）以及常见的资源指令（如source: ./config.yaml），并检查：

• 存在性：引用的文件是否真实存在于磁盘上？避免出现死链。
• 路径深度：引用是否超出了技能目录一级的范围？例如，技能在skills/a/目录下，却试图引用../../etc/passwd或甚至skills/b/下的文件。规范通常要求资源与技能文件紧耦合，限制引用深度是为了保证技能的可移植性和安全性。
• 路径遍历：这是一个重要的安全考量（类似CWE-59）。它会检查是否有引用试图通过../跳出技能所在的根目录，访问系统上的任意文件。虽然技能运行在沙盒环境中，但良好的实践应从源头杜绝此类模式。

2.4 令牌预算与体积控制：性能与成本的平衡

AI模型有上下文窗口限制，技能文件本身也会消耗令牌。AgentEval通过sizing和disclosure系列规则来监控文件的“体积”。

• 行数与令牌估算：它会统计文件总行数（默认阈值500行）并估算总令牌数（默认阈值8000 tokens）。一个过于庞大的技能文件不仅加载慢，也可能挤占用户对话的上下文空间。
• 预算分层检查：根据最佳实践，技能文件的令牌预算应分层管理：
  • 元数据预算（~100 tokens）：留给Frontmatter，确保核心信息简洁。
  • 正文指令预算（<5000 tokens）：留给技能的核心指令和示例。
  • 按需资源：引用的外部资源文件不计入主文件预算。
• 正文膨胀检测：它会标记正文中过大的代码块、Markdown表格或内嵌的Base64图片。这些内容极其消耗令牌，应考虑将其移至外部文件引用。

这些检查旨在引导开发者编写精炼、高效的技能指令，在提供足够信息和控制令牌成本之间取得平衡。

2.5 跨平台兼容性预警：避免平台“特供”坑

不同的AI平台对技能规范的支持程度和细节要求有差异。AgentEval的compat系列规则就像一个“兼容性矩阵”检查器。

• Claude Code专用字段：某些字段可能仅被Claude Code识别和使用。如果你的技能也打算用于VS Code，使用这些字段可能导致功能缺失或解析错误。AgentEval会将其标记为信息，提示你注意。
• VS Code目录名严格模式：通过--strict-vscode参数，你可以将目录名不匹配的警告提升为错误，确保技能100%符合VS Code的苛刻要求。
• 未验证行为：对于Codex、Cursor等其他平台，某些字段的行为可能没有公开文档明确说明。AgentEval会标记这些“未验证”字段，提醒你需要在目标平台上进行额外测试。

3. 从安装到集成：全流程实操指南

了解了AgentEval能做什么，接下来我们看看如何把它用起来。从本地命令行工具到集成到团队CI/CD流水线，它提供了灵活的接入方式。

3.1 安装与基础使用

安装非常简单，通过pip即可完成：

pip install agenteval

如果你需要从源码安装或参与开发，可以连同开发依赖一起安装：

pip install -e ".[dev]"

基础使用命令直观明了。最常用的场景是验证单个文件或扫描整个目录：

# 检查单个SKILL.md文件 agenteval path/to/my-skill/SKILL.md # 递归扫描某个目录下的所有技能文件 agenteval skills/ # 扫描整个插件目录，并生成一个带标签页的HTML报告（便于查看多个技能） agenteval plugins/my-awesome-plugin/

执行后，AgentEval会在终端输出彩色化的结果。✔ PASS表示通过，✗ FAIL表示存在错误（会阻塞CI），⚠ warning和· info则是需要你注意的建议和信息。错误信息会精确到行号，并给出规则ID，方便快速定位问题。

3.2 进阶参数与场景化配置

AgentEval提供了丰富的命令行参数来适应不同场景：

• 质量门槛控制：--min-desc-score 70要求描述质量得分不低于70，否则触发警告。
• 目标平台聚焦：--target-agent vscode只进行VS Code相关的兼容性检查，忽略其他平台的警告，让报告更简洁。
• CI环境适配：在CI中，构建环境可能是临时目录，导致目录名匹配检查失败。使用--skip-dirname-check和--skip-ref-check可以跳过需要真实文件系统上下文的检查。
• 机器可读输出：--format json将输出转换为JSON格式，方便其他脚本（如JQ）进行解析和处理，这是CI集成的关键。
• 报告生成：--html report.html会生成一个美观的HTML报告，特别适合一次性验证多个技能后分享结果。

一个综合性的使用示例如下：

# 在CI脚本中，以严格模式检查VS Code兼容性，要求高描述质量，并输出JSON供后续分析 agenteval skills/ \ --target-agent vscode \ --strict-vscode \ --min-desc-score 75 \ --format json \ --skip-dirname-check \ --quiet

3.3 无缝集成GitHub Actions

将AgentEval集成到GitHub Actions中，可以为你的技能仓库实现自动化的质量门禁。任何Pull Request一旦包含不合规的技能文件，CI就会失败，并将错误信息直接标注在代码Diff上，让贡献者一目了然。

配置极其简单，只需在你的工作流文件中添加一个步骤：

# .github/workflows/validate-skills.yml name: Validate AI Skills on: [push, pull_request] # 在推送和PR时触发 jobs: validate: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Run AgentEval uses: YoavLax/agenteval@v0 # 使用官方Action with: path: 'skills/' # 指定要检查的技能目录 # min-desc-score: 60 # 可选：设置描述质量最低分 # strict-vscode: true # 可选：启用VS Code严格模式

添加后，当有PR修改了skills/目录下的文件时，该工作流会自动运行。如果AgentEval发现任何错误，整个步骤会失败（exit code 1），从而阻止PR合并。更重要的是，错误和警告会以“注解”（Annotation）的形式显示在GitHub PR的“Files changed”标签页中，精确指向有问题的行，体验如同内置的代码检查。

你还可以利用Action的输出进行更复杂的流程控制，例如只当有文件验证失败时才通知某个频道：

- uses: YoavLax/agenteval@v0 id: skill-check # 给步骤一个ID with: path: '.' - name: Handle Failure if: failure() && steps.skill-check.outcome == 'failure' run: | # 这里可以执行失败后的操作，如发送通知 echo "有技能验证失败，阻止合并。"

4. 实际案例与排错指南

理论说再多，不如看几个实际案例。下面我们通过几个典型的错误场景，来深入理解AgentEval的报错信息，并掌握排查和修复的方法。

4.1 案例一：VS Code中“消失”的技能

问题现象：开发者alice创建了一个名为json-formatter的技能，文件路径为skills/json-tools/SKILL.md。在Claude Code中测试正常，但在VS Code Copilot中始终找不到这个技能。

AgentEval诊断：

✗ FAIL skills/json-tools/SKILL.md line 2 ✗ error frontmatter.name.directory-mismatch Name 'json-formatter' does not match parent directory 'json-tools'.

根因分析：这是VS Code Copilot的一个特定要求。为了让技能在VS Code的插件系统中被正确索引和加载，技能文件的name字段必须与其所在的直接父目录名完全一致。这里name是json-formatter，但目录名是json-tools，因此VS Code直接丢弃了这个技能，且无任何错误提示。

解决方案：二选一。

1. 修改目录名：将目录json-tools重命名为json-formatter。这是最规范的做法。
2. 修改技能名：将Frontmatter中的name改为json-tools。但前提是这个新名字依然符合命名规范且能准确描述技能。

实操心得：在团队协作中，这个错误非常常见。建议在项目README中明确强调此规则，并利用AgentEval的CI检查在PR阶段就将其拦截。对于仅在Claude Code中使用的技能，可以使用--target-agent claude来跳过此项检查。

4.2 案例二：AI从不调用的“隐形”技能

问题现象：开发者bob写了一个数据库查询技能，但AI在对话中似乎永远意识不到它的存在。

AgentEval诊断：

✔ PASS skills/db-query/SKILL.md · info description.quality-score Description quality score: 30/100. Suggestions: Start with an action verb; Add trigger phrases.

根因分析：技能通过了所有语法和规范检查（✔ PASS），但描述质量得分很低（30分）。AgentEval提示描述缺乏“行动动词”和“触发短语”。查看其描述，可能是“这是一个用于查询数据库的工具”或“Helper for database operations”。这类描述过于静态和模糊，AI在理解用户意图时，很难将其与“帮我查一下上个月的订单数据”这样的用户请求关联起来。

解决方案：重写描述，遵循“行动动词 + 关键对象 + 可选场景/触发词”的结构。

• 原始描述（差）：A tool to query databases.
• 改进描述（中）：Query structured data from SQL databases.
• 优秀描述（好）：Run SQL queries against your database to extract, filter, and analyze data. Use this when you need to find specific records, generate reports, or check data integrity.

修改后再次运行agenteval，描述得分通常会提升到70分以上，技能被AI发现和调用的概率将显著增加。

4.3 案例三：臃肿的技能文件与令牌超支

问题现象：一个图形处理技能文件非常大，导致在AI中使用时加载缓慢，甚至偶尔出现截断。

AgentEval诊断：

⚠ warning skills/image-processor/SKILL.md ⚠ warning sizing.body.token-estimate File exceeds token threshold (est. 9500 > 8000). · info disclosure.body-bloat Large code block detected (≈120 lines).

根因分析：技能文件的正文部分估计超过了8000令牌的默认阈值。进一步检查发现，文件中内嵌了一个约120行的完整图像处理算法示例代码。这段代码虽然具有参考价值，但极大地膨胀了文件体积。

解决方案：遵循“精炼指令，外置资源”的原则。

1. 移出大型代码块：将完整的示例代码移到一个独立的文件，例如examples/advanced_processing.py。
2. 在SKILL.md中引用：将原来的代码块替换为一个简短的说明和引用链接，如：

   ## 高级用法示例 对于复杂的处理流程，请参考 [advanced_processing.py](./examples/advanced_processing.py)。

3. 保留核心指令：在SKILL.md中只保留最关键的、指导AI如何调用核心库函数的指令和简短示例。

这样处理后，主技能文件变得轻量，令牌数大幅下降，而完整的示例依然可供用户或AI在需要时查阅。

4.4 常见问题排查速查表

问题现象	可能触发的规则	排查步骤与解决方案
技能在VS Code中不显示	frontmatter.name.directory-mismatch	1. 检查name字段。 2. 检查SKILL.md所在目录名。 3. 确保两者完全一致（大小写敏感）。
技能描述质量低，AI不调用	description.quality-score,description.min-score	1. 运行agenteval查看具体建议。 2. 确保描述以动词开头。 3. 补充说明技能适用的典型场景或触发词。
CI检查失败，但本地通过	多种可能	1. 检查CI中AgentEval的版本是否与本地一致。 2. 检查CI的工作目录路径是否不同（影响目录名检查）。 3. 使用--skip-dirname-check --skip-ref-check排除环境差异。
文件引用报错	references.broken-link,references.depth-exceeded	1. 确认被引用的文件是否已提交到仓库。 2. 检查引用路径是否正确（相对路径）。 3. 确保引用没有超出技能目录一级以上（如../../file）。
令牌数估算不准	sizing.body.token-estimate警告	1. 安装tiktoken包 (pip install tiktoken) 以获得更精确的GPT系列模型令牌计数。 2. 注意：这仍是估算，最准确的是目标平台（如Claude）的官方计数。
未知字段警告	frontmatter.field.unknown	1. 查阅 agentskills.io 最新规范。 2. 确认该字段是否为特定平台（如Claude Code）的扩展字段。 3. 如果是自定义字段，考虑是否必要，或使用--ignore忽略此警告。

5. 项目配置与团队最佳实践

将AgentEval融入个人或团队的开发流程，能系统性地提升技能库的质量。以下是一些经过验证的最佳实践。

5.1 为项目制定检查规范

在项目根目录创建一个agenteval-config脚本或Makefile目标，统一检查参数，确保所有开发者使用相同的标准。

#!/bin/bash # scripts/validate-skills.sh agenteval ./skills \ --min-desc-score 65 \ --target-agent all \ --strict-vscode \ --html ./reports/skill-validation.html

或者在Makefile中：

validate-skills: agenteval skills/ --min-desc-score 65 --strict-vscode .PHONY: validate-skills

这样，团队成员只需运行make validate-skills或./scripts/validate-skills.sh即可执行一套预设的严格检查。

5.2 集成到提交前钩子（Pre-commit）

对于使用Git的团队，可以通过 pre-commit 框架，在每次提交代码前自动运行AgentEval，防止有问题的技能进入版本库。

创建.pre-commit-config.yaml文件：

repos: - repo: local hooks: - id: agenteval name: Validate SKILL.md files entry: bash -c 'pip install agenteval >/dev/null 2>&1 || true; agenteval skills/ --min-desc-score 60' language: system files: ^skills/.*\.md$ # 只检查skills目录下的md文件 pass_filenames: false # 检查整个目录

安装pre-commit后，每次执行git commit，如果skills/目录下的技能文件有问题，提交就会被阻止。

5.3 在CI中实现分级检查策略

在GitHub Actions等CI环境中，可以设计更精细的检查策略：

1. PR检查（严格）：在pull_request事件中，使用严格参数（--strict-vscode，较高的--min-desc-score），任何错误都导致失败，确保合并到主分支的代码质量最高。
2. 主干构建（信息收集）：在push到主分支的事件中，可以运行检查并生成HTML报告，作为构件存档，方便后续审计。此时可以不使用--strict-vscode，仅收集信息。
3. 定时检查（监控）：通过schedule事件，每周对主分支所有技能进行一次全面检查，生成报告并发送到团队频道，监控技能库的整体健康度。

5.4 处理误报与规则忽略

没有任何静态检查工具是完美的。AgentEval的某些“建议性”（advisory）规则可能在某些特定场景下不适用。例如，你有一个内部使用的技能，其描述就是故意写得简单，不需要高分。

此时，可以使用--ignore参数来忽略特定规则或一类规则。规则ID是分级的，你可以忽略整个类别：

# 忽略所有关于描述质量的检查 agenteval skills/ --ignore description. # 忽略所有关于未知字段的警告 agenteval skills/ --ignore frontmatter.field.unknown # 同时忽略多个规则 agenteval skills/ --ignore frontmatter.description.person-voice --ignore compat.unverified

注意事项：忽略规则应谨慎，并最好在团队内达成共识。建议将忽略规则的理由以注释的形式写在CI配置或项目文档中，避免后来者困惑。

6. 深入原理与扩展思考

AgentEval虽然是一个工具，但其背后体现的工程思想值得深入探讨。它本质上是在AI应用开发中，将“基础设施即代码”（Infrastructure as Code）和“配置即代码”（Configuration as Code）的成熟实践，引入到了“技能即代码”（Skills as Code）的领域。

静态分析的威力：在软件工程中，Linter、Formatter、静态类型检查器等工具能在代码运行前发现大量潜在问题，显著提升代码质量和开发效率。AgentEval将这一思想应用于AI技能配置，在技能被部署到各平台Agent之前进行预检，避免了后期调试的困难。因为一旦技能在AI中表现异常，其调试过程往往比传统软件更黑盒、更困难。

规范与兼容性的平衡：AgentEval基于一个社区规范（agentskills.io），但同时也尊重不同平台的实现差异。它没有强制要求所有技能在所有平台表现一致，而是通过compat规则清晰地揭示差异，让开发者做出知情选择。这种设计哲学非常实用：它促进标准化，但不扼杀平台创新和特性。

质量指标的量化：描述质量评分是一个有趣的尝试。它试图将“描述写得好不好”这个主观问题，通过一系列可观测、可度量的启发式规则（动词、触发词、长度等）进行量化。虽然它不能替代人类对语义的判断，但它为开发者提供了一个快速、客观的基准线，尤其适用于在大型技能库中快速筛选出需要人工复审的低质量描述。

未来的演进方向：从AgentEval的设计中，我们可以窥见AI技能开发工具链的未来。它可能会向两个方向延伸：一是更深度集成，例如与VS Code、Cursor等编辑器的插件结合，提供实时的、行内的错误提示和修复建议；二是更智能的分析，例如引入轻量级LLM来分析技能描述的语义清晰度、指令的逻辑完整性，甚至模拟AI对技能的理解过程，从而提供更精准的优化建议。

将AgentEval纳入你的AI技能开发工作流，就像为你的项目请来了一位不知疲倦的代码审查员。它强制你关注那些容易被忽略的细节——命名、格式、兼容性、文档质量。这些细节，恰恰是区分业余作品与专业产品的关键。在AI智能体生态早期就养成规范开发的习惯，随着技能库的增长和团队规模的扩大，你所节省的调试成本和维护心力将是巨大的。