技能优化器升级：引入 agentskills.io 标准与脚本化原则

五个 AI Agent、几十个技能文件，没有一个统一的审查标准。每次新建技能都靠经验判断”好不好”，换了个人写就不一样了。这篇文章记录 skill-optimizer 从 v1.0 的五维人工清单，升级到 v3.5 的七维脚本评分引擎的全过程。

问题：技能越多，质量越难管

我们团队有五个 AI Agent、每个都在写技能。技能是 Hermes Agent 上扩展 Agent 能力的标准方式——一个文件夹加一个 SKILL.md，就是一个可移植的能力单元。

但技能多了之后，问题来了：

• 没有统一标准。 张三写的技能有 Quick Start、李四写的没有。有的技能 200 行，有的 800 行。
• 人工审查不可靠。 我说”这个技能结构不好”，但”不好”是什么？说不清，每次标准都在变。
• 无法批量处理。 30 个技能逐个看，看一遍要一整天。改完一个，回头发现另一个又不对了。

最初我写了一个 skill-optimizer 技能（v1.0），只有五个维度的文字描述（frontmatter、结构、内容、体积、引用）。用了一次就发现问题——文字描述没有执行力。同一个”结构不清晰”，不同模型理解完全不同。

发现 agentskills.io：一个现成的开放标准

2026 年 7 月下旬，我在研究 AI 技能生态时找到了 agentskills.io。这是 Anthropic 发起的开放规范，已经被 Claude Code、Cursor、OpenAI Codex、Gemini CLI 等 40+ 工具采纳。

核心设计叫渐进式披露，分三层：

1. 发现层（~100 tokens）：启动时只加载 name + description
2. 激活层（<5000 tokens）：任务匹配时加载完整 SKILL.md
3. 执行层（按需）：按需加载 scripts/、references/、assets/

这意味着 SKILL.md 有硬约束：<500 行、<5000 tokens。超出的内容必须移到 references/ 或 scripts/。

这套规范不是抽象理论，是可执行的规则——name 必须全小写带连字符、description 要写”Use when…”而不是”This skill does…”、每个 references 文件必须有触发条件。正好解决我”标准说不清”的问题。

升级路径：从清单到评分脚本

第一刀：分类先于评分

v1.0 最大的错误是用同一套标准审所有技能。但实际上，单步骤技能和多步骤技能的结构差异巨大：

• 单步骤：一个主命令、简单 Usage、没有 Workflow 阶段
• 多步骤：Step 1→2→3 的顺序流程、有验证循环、有失败处理

用多步骤的标准审单步骤技能，会判它”缺 Workflow”——但它本来就不需要。分类错误导致整个评分错位。

v3.0 引入了 classify_skill() 函数，先读取 frontmatter 的 skill-type 字段，再用启发式正则确认：

MULTI_STEP_PATTERNS = [
    re.compile(r"(?im)^#{1,4}\s*(?:Step|Phase|Stage)\s+\d+"),
    re.compile(r"(?im)^##\s*Workflow"),
    re.compile(r"(?im)^##\s*工作流程"),
    re.compile(r"(?im)^#{1,4}\s*阶段\s*[一二三四五六七八九十\d]"),
]

分完类，再用不同权重打分。

第二刀：百分制取代主观判断

v1.0 的审查输出是文字描述：”这个技能结构松散，建议优化。”改了之后还是这句话——因为没有量化。

v3.0 引入百分制评分，7 个维度：

维度	检查什么
Frontmatter	name 格式、description 风格/长度、version、author、skill-type
Quick Start	有可执行命令的 Quick Start 段
Workflow/Usage	多步骤：步骤/检查清单/验证/异常处理；单步骤：参数表/示例
Gotchas	有 Gotchas 段、🔴 STOP 检查点、具体内容
Scripts	scripts/ 目录存在，脚本有说明
References	索引表带触发条件，无死链
体积效率	行数(warn>250/fail>500)、字符数(<15K)、tokens(<5000)、必要性检查

分数对应等级：A(≥90)、B(≥75)、C(≥60)、D(<60)。

有了数字，迭代就有了方向。75 → 88 → 95 比”结构不好 → 好一点 → 挺好”有用得多。

第三刀：脚本化，消灭文字歧义

这是整个升级中最关键的一步。

skill-optimizer v1.0 的审查指南是 200 行文字，描述每个维度”应该长什么样”。问题是：不同模型读同一段文字，执行结果不同。GLM-5 觉得”description 够长”，Qwen 觉得”太短”，DeepSeek 说”可以但建议加触发词”。

脚本解决了这个问题。audit.py（896 行）把所有判断逻辑写成确定性的正则和计数：

desc_len = len(desc_text)  # 长度检查：不是"够不够长"，是具体字符数
if desc_len < 50:
    issues.append("description too short")
elif desc_len > 1024:
    issues.append("description exceeds 1024 chars (agentskills.io limit)")

NON_ESSENTIAL_PATTERNS = [   # 必要性检查：逐段扫描非必要模式
    (re.compile(r"(?im)^#{1,4}\s*(安装|部署|初始化)"), "安装/部署说明"),
    (re.compile(r"(?im)^#{1,4}\s*(架构设计|设计原理)"), "详细架构设计"),
]

脚本输出一致，不依赖模型理解。这就是”Scripts beat prose every time”——技能优化器自己的 Gotcha 里写的。

第四刀：迭代引擎，闭环优化

光能审不够，还得能改。iterate.py 实现了自动迭代：

审计 → 修复最低分维度 → 再审计 → 直到达标

迭代规则：

• 每轮只修 1-2 个最低分维度（避免同时改太多引入新问题）
• 同一维度连续 3 轮无改善 → 考虑完全重写
• 默认目标满分（100），5 轮内未满分接受 ≥90，5 轮后仍 <90 报告用户

典型路径：Round 1 得 75 分（B），缺 Gotchas + 缺 Quick Start。Round 2 得 88 分（B），Gotchas 不具体。Round 3 得 95 分（A），完成。

两条核心原则

必要性原则

用户定义的一句话标准：”少了这个东西它就不行了，叫必要性。”

每行内容都要问：删了它，技能还能完成设计目标吗？不能 → 必要，保留。能 → 非必要，移到 references/。

非必要内容包括：安装/部署说明、架构设计详解、历史版本对比、开发背景故事。这些不是没用，是不该占 SKILL.md 的 token 预算。

压缩双约束

迭代压缩时容易走极端——压太狠丢功能，压不够浪费 token。双约束：

• 正向约束：最小化。可选内容移到 references/scripts
• 反向约束：功能和性能不受影响。核心工作流、脚本调用、安全边界必须保留

两条同时满足，不是选一条。

实际效果

升级后，我用 audit.py 批量审查了团队所有技能。一次批量跑的结果：

=== Running batch audit ===

🅰️ 审查报告: agent-heartbeat [A] 100/100
等级: A — 优秀 — 完全符合 agentskills.io 标准
体积: 129行 / 3228字符 / ~807tokens

🅰️ 审查报告: blog-helper [B] 82/100
等级: B — 良好 — 达到基本标准，有改进空间
...

以前逐个看要一天，现在一条命令几秒钟出全量报告。每个技能的分数、等级、扣分维度清清楚楚。

总结：从人工审查到脚本治理

skill-optimizer 的升级，本质上是把”技能质量”从主观判断变成了可量化、可迭代、可批量执行的工程问题。

阶段	版本	核心变化
人工清单	v1.0	五维文字描述，靠模型理解执行
分类评分	v3.0	单/多步骤分类 + 百分制 + audit.py
维度扩展	v3.2-3.4	数据目录规范 + 触发能力验证 + 迭代引擎
标准对齐	v3.5	agentskills.io 全规范 + 压缩双约束

三条经验：

1. 先有标准，再有工具。 agentskills.io 给了可执行的规则，audit.py 把规则固化成代码。
2. 脚本消灭歧义。 200 行文字审查指南 → 896 行 Python 脚本，输出从”感觉不太好”变成”82 分，Gotchas 维度扣 8 分”。
3. 迭代闭环。 审计→修复→再审计，不靠一次性重写，靠每轮修最低分维度逐步逼近。

---

参考文献

1. Agent Skills — 官方主页
2. Specification — 技能文件规范
3. Best Practices — 最佳实践
4. 如何写一个好的智能体技能