跳转至

Skill

1. Skill ≈ Markdown

Skill 是一种电子说明书的宽松格式，最早由 Anthropic 在其 博文 中提出。它利用 Markdown 文件的 header 结构，通过 “渐进式披露” 的思想，让 Agent 能够只以较少的 context 加载大量“说明书”的简介，并能够正确使用说明书的数据结构。

Skill 是一个文件夹，文件夹中至少要有一个名为 SKILL.md的文档。Skills 的官方网站 定义，Skill 文件夹至少要有下面的结构：

skill-name/
├── SKILL.md          # 默认：metadata + instructions
├── scripts/          # 可选：可执行的代码
├── references/       # 可选：文档
├── assets/           # 可选：各种资料
└── ...               # 其他任意的参考文件噔噔

1.1. 渐进式披露 与 Skill

渐进式披露说：

  1. 不能将大量内容一次性提供给 Agent，这样 Agent 无所适从；
  2. 应当把数据做出一定的结构，这样 Agent 能够顺着数据结构，不断获取不同层级、不同颗粒度的信息，既方便查找，也节省 token，还能提高准确度。 Skill 就是这个思想指导下应运而生的数据结构。

常观察 Agent 工作流程的读者能发现， Agent 在探索文件夹的时候，往往会由浅到深，逐层搜索，即，先获得文件夹大致结构，然后根据结构来逐步深入文件夹层级，查看 Agent 感兴趣的文件内容。

Skill 能够把这种逐层的配置引入到文件的查看上。前面的教程讲过 ，Markdown 的开头，可以放置一段特殊格式的文本，用来描述一些基础信息和字段：

---
name: skill 名
description: 简要的介绍
tools:
---
Markdown 正文

description 同时描述“这个 Skill 做什么”和“什么情况下使用”。Agent 主要依靠这段描述完成自动匹配，因此触发词、任务边界和适用文件类型都适合写清楚。

渐进式披露在 Skill 里，由浅至深，可以分为三层。每轮对话发起时， Agent 的 prompt 中都会自动加载所有安装好的 Skill 的 name 和 description. Agent 在其中选择合适的 Skill ，并使用读文件的工具进一步读取相关的 SKILL.md 内容，再根据 SKILL.md 的内容来指导自己后续的工作流程。

层级 Agent 何时读取 适合放置的内容
元数据 会话开始或技能扫描时 name、description
主说明 Skill 被选中后 目标、步骤、判断规则、验收标准
附加资源 执行到相关步骤时 references/、scripts/、assets/

主 SKILL.md 应当保持简洁、明确，如同书写 AGENTS.md 一样。较长的 API 文档、格式规范和案例集可以分别放进 references/，需要稳定重复执行的解析、转换和验证步骤可以放进 scripts/，常用的参考文件可以放进 assets/ 。

1.2. 全局与局部 Skill

全局 Skill 面向个人在多个项目中都会使用的能力，而局部 Skill 面向当前仓库独有的流程。将一部分只和当前文件夹中的项目强相关的 Skill 配置为局部 Skill，这部分 Skill 就不会在别的项目中出现，能保持 Agent 上下文不受其他项目污染。

Agent 全局 Skill 项目 Skill
Codex ~/.agents/skills/<skill-name>/SKILL.md .agents/skills/<skill-name>/SKILL.md
Claude Code ~/.claude/skills/<skill-name>/SKILL.md .claude/skills/<skill-name>/SKILL.md
OpenCode ~/.config/opencode/skills/<skill-name>/SKILL.md .opencode/skills/<skill-name>/SKILL.md

安装 Skill 时是否安装为全局 Skill，可以参考下面的标准：

  • Obsidian Markdown、PDF 处理、表格处理、项目规划等通用能力，适合放在全局；
  • 当前仓库的构建、测试、发布和文档规范，适合放在项目目录；
  • 同名 Skill 会让不同 Agent 产生覆盖或并列展示行为，目录名和 name 适合保持唯一。

1.3. 安装一个 Skill

这里使用 kepano/obsidian-skills 作为例子。这个 Github 仓库包含一系列用来操控 Obsidian 的 Skill：

Skill 用途
obsidian-markdown 编写 wikilink、embed、callout、properties 等 Obsidian Markdown
obsidian-bases 创建和编辑 .base 数据视图
json-canvas 创建和编辑 .canvas 画布
obsidian-cli 通过 Obsidian CLI 搜索、读取和维护 vault
defuddle 将网页正文提取成干净的 Markdown

先确认 Node.js 和 npm 可用，然后运行交互式安装：

npx skills add https://github.com/kepano/obsidian-skills

安装器会让你选择目标 Agent、Skill 和全局或项目作用域。希望把仓库中的全部 Skill 全局安装到所有受支持 Agent 时，可以运行：

npx skills add https://github.com/kepano/obsidian-skills --all --global

安装前可以先查看仓库中的 SKILL.md 和 scripts/。Skill 可以携带可执行脚本，来源、依赖和权限范围都属于安装检查的一部分。

安装完成后检查列表：

npx skills list --global

如果 Agent 当前会话没有显示新 Skill，重新启动 Agent。第一次使用可以从一个小任务开始：

使用 obsidian-markdown Skill，把2026年菲尔兹奖的所有中国得主的信息和研究内容，整理成一篇带 properties、wikilink 和 tip callout 的测试笔记。写入前先展示拟采用的结构。

检查生成结果、内部链接和文件位置符合预期后，再将 Skill 用于正式笔记仓库。

2. 如何做一个自己的 Skill

2.1. 如何写一个 Skill

按照下面的结构组织文件夹即可

.codex/Skill-name
SKILL.md
Reference/
Scripts/

按照 Agent Skills 开放规范，更完整的目录结构如下：

skill-name/
├── SKILL.md          # 必需：元数据与主说明
├── scripts/          # 可选：可重复执行的脚本
├── references/       # 可选：按需读取的参考资料
├── assets/           # 可选：模板、图片和静态数据
└── examples/         # 可选：输入输出样例

Skill 的文件夹名和 name 应保持一致，并使用小写字母、数字和连字符。 Skill 的简单案例如下：

---
name: verify-doc-page
description: 检查单个 Markdown 教程页面的结构、内部链接和代码块。用户要求补全文档、检查文档或验证教程页面时使用。
---

# 目标

在保留作者原意的前提下，让教程页面结构完整、链接有效、示例可以照着执行。

# 步骤

1. 阅读目标页面和相邻页面，确认读者水平与文风。
2. 标记空标题、占位文字、空链接和未经验证的命令。
3. 只修改用户授权的范围。
4. 检查标题层级、代码围栏和相对链接。
5. 运行项目已有的文档检查命令。

# 输出

汇报修改文件、补充内容和验证结果。

一份可靠的 Skill 通常具备清楚的触发条件、可执行的步骤、明确的异常处理和具体的验收标准。 编写 Skill 时，需要反复思考下面几个问题：

  1. 哪些用户表达会触发这个 Skill？
  2. 这个 Skill 需要读取哪些输入？
  3. Skill 按什么顺序工作、判断和执行？
  4. 用户不希望 Skill 触碰哪些内容？用户希望哪些内容自己参与审核？
  5. 通过哪些证据或信号，来确认任务完成？

2.2. 如何从已有的工作流程和经验里面总结一个 Skill

适合沉淀为 Skill 的流程，通常已经成功执行过几次，而且每次都需要重复解释相似的步骤。可以按照下面的顺序整理：

  1. 收集两到三个真实案例，包括成功结果和中途遇到的问题；
  2. 把流程分成固定步骤、可变参数和环境依赖；
  3. 为 Skill 写出输入、输出、权限范围和完成标准；
  4. 把需要模型判断的内容写进 SKILL.md；
  5. 把适合确定性执行的内容写成脚本；
  6. 把较长的规范、模板和案例放进附加目录；
  7. 使用小样本重新运行，确认 Agent 能独立完成流程。

例如，一次文档发布工作可能包含“读取相邻页面、补充内容、检查格式、构建站点、汇报结果”。其中：

  • “根据上下文判断缺少什么”适合写成说明；
  • “运行固定格式检查命令”适合写进脚本或命令清单；
  • “项目的标题、链接和术语规范”适合放进 references/；
  • “构建成功、链接有效、改动范围正确”适合写成验收标准。

也可以在一次成功工作结束后，让 Agent 先生成草案：

请把刚才完成的工作流程提炼为一个 Agent Skill 草案。总结触发条件、输入、固定步骤、可变参数、权限边界、失败处理和验收标准；把长参考资料与可执行脚本分别规划到 references/ 和 scripts/。先展示目录和 SKILL.md，再进行三组触发测试。

2.3. 如何不断优化 Skill

Skill 的优化可以围绕三个指标展开：

指标 观察方法 常见调整
触发准确度 该触发的任务能否选中，普通任务是否保持安静 补充或收窄 description 中的触发词和边界
执行稳定度 多次运行是否遵循相同步骤并产出可验证结果 拆细步骤，增加失败分支，把机械操作移入脚本
上下文成本 Agent 是否读取了过多无关内容 缩短主文件，把长资料拆入 references/

每次修改后准备三类测试：

  1. 应当触发：典型任务能够自动选择 Skill；
  2. 不应触发：相邻但范围不同的任务不会误选；
  3. 边界情况：输入缺失、工具不可用或权限不足时，Agent 会先收集证据并给出明确处理方式。

优化过程适合保留简单记录：测试指令、实际行为、发现的问题、本次调整和复测结果。每轮只调整一类问题，更容易判断哪项修改真正提高了效果。

当 SKILL.md 逐渐变长时，可以再次应用渐进式披露：入口文件保留触发条件、核心流程和文件索引；细节进入参考文件；稳定的重复动作进入脚本。这样既能保持 Skill 易于发现，也能让复杂工作流持续扩展。