Agent skill 迭代式编写实战
本文总结Agent Skill编写经验,将其定义为模块化领域知识资产,类似给AI的“操作手册”,适用于半自动化及专家经验导向场景。核心设计遵循三层渐进式披露架构,强调用决策树替代模糊判断、确定性操作脚本化,并建立内部自查与外部评估双重验证机制。Skill本质是以文件系统结构替代复杂运行时服务,实现零依赖部署。相比专用Agent框架,它更轻量但确定性稍弱,旨在将隐性专家经验转化为可复用、可验证的知识资产。
前言
本文是笔者年初以来摸索 agent skill 编写过程中的经验总结,配图生成自 QoderWork。分享的内容包括了:
笔者对于 agent skill 概念和特性的理解,以及适用的场景
迭代式编写 agent skill 的实践经验
关于 skill:概念、特性与应用场景
Agent Skill 是模块化的能力包,沉淀了领域知识的资产 bundle,资产包括自然语言指令、元数据和可选资源(脚本、模板),让 AI Agent 在需要时自动加载和使用。如果说 MCP 为 agent 提供了"手"来操作工具,那么 skill 就是"操作手册",教 agent 怎么用这些工具。
从时间线看,2025 年 10 月中旬 Anthropic 正式发布 Claude Skills,两个月后 Agent Skills 作为开放标准发布,Cursor、OpenCode、Qoder 等主流工具陆续跟进。
通俗理解:skill 就是给 agent 准备的业务 SOP 大礼包,涵盖执行流程、背景知识、工具使用说明、模板素材,以及常见问题的处理方式。
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
以下场景特别适合:
半自动化重复流程:同一业务流程频繁执行,部分依赖主观判断,无法完全自动化
领域知识导向:业务流程依赖专家知识,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…