Agent skill 迭代式编写实战


本文总结Agent Skill编写经验,将其定义为模块化领域知识资产,类似给AI的“操作手册”,适用于半自动化及专家经验导向场景。核心设计遵循三层渐进式披露架构,强调用决策树替代模糊判断、确定性操作脚本化,并建立内部自查与外部评估双重验证机制。Skill本质是以文件系统结构替代复杂运行时服务,实现零依赖部署。相比专用Agent框架,它更轻量但确定性稍弱,旨在将隐性专家经验转化为可复用、可验证的知识资产。


前言


本文是笔者年初以来摸索 agent skill 编写过程中的经验总结,配图生成自 QoderWork。分享的内容包括了:

  • 笔者对于 agent skill 概念和特性的理解,以及适用的场景

  • 迭代式编写 agent skill 的实践经验


关于 skill:概念、特性与应用场景


▐  什么是 Agent Skill


Agent Skill 是模块化的能力包,沉淀了领域知识的资产 bundle,资产包括自然语言指令、元数据和可选资源(脚本、模板),让 AI Agent 在需要时自动加载和使用。如果说 MCP 为 agent 提供了"手"来操作工具,那么 skill 就是"操作手册",教 agent 怎么用这些工具。

从时间线看,2025 年 10 月中旬 Anthropic 正式发布 Claude Skills,两个月后 Agent Skills 作为开放标准发布,Cursor、OpenCode、Qoder 等主流工具陆续跟进。

通俗理解:skill 就是给 agent 准备的业务 SOP 大礼包,涵盖执行流程、背景知识、工具使用说明、模板素材,以及常见问题的处理方式。


▐  Agent skill 的形态


skill 基于文件系统驱动,agent 工具通过 skill 标准的 tool 和终端/文件操作能力完成发现与加载。

标准 Skill 目录结构如下:



SKILL.md 是整个 skill 的核心,由两部分组成:

  • YAML frontmatter:skill 的元数据,agent 通过此判断是否触发。

    description 是关键,通常写明适用场景和关键触发词。

  • Markdown 正文:面向 agent 的执行 SOP,建议用「总-分」结构,先说核心规则,再展开约束细节。

references/ 放补充文档,如模板文件、详细规范、示例代码等,在 SKILL.md 中通过路径按需引用,不要把大量内容堆进主文件。

scripts/ 放确定性操作的执行脚本(Python/Bash 等)。能写成脚本的就不要靠 agent 推理——脚本的稳定性和可复现性远高于让 agent 猜。

扩展阅读:如何处理带有三方库依赖的 python 脚本:uv run + pep 723


▐  Agent Skill 的核心特性



▐  适合使用 Agent Skill 的场景


以下场景特别适合:

  • 半自动化重复流程:同一业务流程频繁执行,部分依赖主观判断,无法完全自动化

  • 领域知识导向:业务流程依赖专家知识,llm 泛化能力难以覆盖

  • 上下文受限:agent 职责多样且上下文窗口有限,处理其他任务时不希望无关知识占位

不适合的场景:

  • 简单任务:直接用基础提示词,靠 llm 泛化能力即可

  • 流程完全确定性:写代码自动化更合适

  • agent 职责高度单一:把 skill 内容放进 system prompt,脚本用 mcp/tools 代替,没必要包装成 skill


Agent Skill 编写经验


推荐先装好这两个元 skill 再上手:

  • https://skills.sh/anthropics/skills/skill-creator 用于生成 skill

  • https://skills.sh/softaworks/agent-toolkit/skill-judge 用于评估 skill


▐  设计时遵循三层渐进式加载架构



渐进式披露(Progressive Disclosure)是 Agent Skill 最核心的设计思想,把技能信息拆成三层:

  • 第一层:目录/概要(成本最低,agent 平时只需知道手册目录)

  • 第二层:详细指令(按需加载,需要时才打开具体章节)

  • 第三层:完整资源(包含详细步骤和工具脚本)

设计 skill 时就要想清楚:哪些内容必须在 skill.md,哪些可以下沉到 reference。



▐  迭代式开发



以下是开发过程中一些具体的可优化 skill 效果的实践


  • 用决策树替代模糊判断


决策树是正向约束,能让 agent 在需要做判断时行为可控。以下是一个异步消息问题排查的 skill 的片段示例


### 结果处理规则**补全未发出消息:** 若有序事件的前序有日志、后序无日志,在报告表格中补充后序事件行,tag以外字段留空,备注标记为"消息未发出"。**消费失败处理:** 判断某 tag 是否失败,标准为 `resultFlag = N` 且该 tag 后续无 `resultFlag = Y` 的记录。- 若后续**有** `Y`(重试成功)→ 取**第一条**失败行,调用错误详情查询- 若后续**无** `Y`(持续失败)→ 取**每一条**失败行,调用错误详情查询**错误详情查询(消费失败):**


skill-judge 把决策树列为高质量 skill 的明确标志,在 D1(知识增量)和 D8(实用性)两个维度都是加分项:

Green flags (indicators of high knowledge delta):- Decision trees for non-obvious choices…

— 以上为试看内容(约 40%),开通会员后阅读全文 —