skills-00.Agent Skills 学习路线与自建指南

发表于 | 分类于
Agent Skills 的概念、典型应用、在 Cursor 中的位置、分阶段学习路线，以及自建 SKILL.md 的步骤与最佳实践。

在 Cursor、Claude 等 Agent 产品中，Skill（常写作 Agent Skill）指：以 SKILL.md 为主文件、可附带脚本与参考材料的一组可复用指令包。它把「领域流程、工具用法、团队规范」从对话里抽出来，变成模型可按 description 自动检索并加载的长期记忆，适合反复出现的专项任务。
本文结构与站内「概述 → 概念 → 实践」类笔记一致：先弄清概念与边界，再谈应用场景，最后落到如何自建。

一、概念：Skill 是什么、不是什么

1. 本质

  • 是什么：面向 Agent 的 Markdown 程序说明——告诉模型「在什么情况下做什么、按什么顺序、输出什么形态」，可附带 脚本 / 参考文档 / 模板资源。
  • 不是什么：
    • 不是替代 MCP（外部工具与实时数据通道）；Skill 偏 知识与流程，MCP 偏 连接与调用。
    • 不是「越大越好」的知识库；Skill 强调 省 token、可触发、可渐进加载。

2. 为什么需要 Skill

  • 上下文窗口是公共资源：系统提示、历史对话、多文件、用户请求共享同一窗口；Skill 只在 description 命中 或用户显式提及时再展开正文，避免每轮塞满无关说明。
  • 模型已经很强：Skill 里应写 模型缺什么（内部规范、私有 API 形态、易错步骤），而不是重讲通用语法。

3. 最小载体：SKILL.md

典型结构（逻辑上）：

部分 作用
YAML 元数据 至少 name、description：供运行时做 技能发现与触发。
正文 步骤、约束、示例、何时读 references/ 等。
可选资源 scripts/、references/、assets/ 等，实现 渐进披露（先短后长）。
description 极其重要：要写清 做什么（WHAT） 与 何时用（WHEN），并包含用户可能说的 触发词，否则很难被自动选中。

二、应用：典型场景与价值

1. 适合用 Skill 的任务

  • 重复性高、步骤固定：按团队模板写 PR 描述、commit message、发布 checklist。
  • 领域规则多、易漏：公司代码规范、安全红线、特定框架的「唯一正确」写法。
  • 工具链长：某 CLI/API 的组合调用顺序、环境变量与常见报错对照。
  • 输出形态强约束：报告章节结构、表格字段、给下游系统的 JSON 形状。

2. 不太适合单独用 Skill 承载的

  • 强实时数据：股价、当前集群状态——更适合 MCP / API 工具。
  • 一次性探索：写进对话即可，不必固化 Skill。
  • 超大参考：整本手册应放 references/ 并在 SKILL.md 里说明 检索关键词，避免整文件进上下文。

3. 与「项目内文档」的分工

对象 读者 典型位置
Skill Agent ~/.cursor/skills/、.cursor/skills/（项目）
人类文档 人 仓库 README、docs/、本站 Hexo 文章
二者可 互相链接：Skill 里写「详细设计见仓库某篇笔记」，笔记里写「自动化步骤见某 Skill」。

三、学习路线（建议顺序）

可按 「会用 → 会选 → 会写 → 会维护」 四阶段推进。

阶段 1：建立心智模型（0.5～1 天）

  • 读清 Skill 与 MCP、与系统提示 的分工（见上文）。
  • 在 Cursor 中确认本机 个人技能目录、项目 .cursor/skills/ 是否存在，以及 内置 skill（如官方提供的 create-rule / create-skill 类）如何被触发。

阶段 2：阅读官方「作者指南」（1～2 天）

  • Cursor：关注 Skill 目录布局、SKILL.md 的 frontmatter、description 写法、渐进披露、行数与篇幅 建议。
  • Anthropic / Claude 生态：若有使用 Claude Code 等，可对照其 Skill Creator 类文档，原则多为 简洁、可触发、资源分包（与 Cursor 高度同构，细节以各平台文档为准）。

阶段 3：改造一个最小 Skill（半天～1 天）

  • 选一个 每周至少做两次 的琐事（如统一生成某类 Git commit 说明）。
  • 只写 name + description + 10～30 行步骤 + 1 个示例，先跑通 能否被稳定触发。
  • 再按需拆分 references/ 或加 scripts/。

阶段 4：工程化与协作（持续）

  • 版本化：Skill 与代码仓库同库时，走 Code Review，避免个人目录「不可复现」。
  • 安全：勿把密钥写进 Skill；引用 1Password / CI 密钥 的流程可以写，明文秘密不要写。
  • 复盘：触发过多 / 过少时，优先改 description 的 WHAT/WHEN 与关键词。

四、如何开发自己的 Skill（实操清单）

1. 写之前先回答的问题

  1. 目的与范围：要解决哪条工作流？边界在哪里？
  2. 放哪：仅个人（本机 skills 目录）还是 团队共享（仓库 .cursor/skills/）？
  3. 触发场景：用户常说哪些词、哪些文件类型、哪些命令？
  4. 输出格式：有无固定模板、JSON 字段、必须避免的表述？
  5. 是否已有范例：团队文档、历史对话里有无可提炼的「标准答案」？

2. 目录与文件（常见约定）

1
2
3
4
5
your-skill/
├── SKILL.md           # 必填：元数据 + 主流程
├── reference.md       # 可选：长文档、API 片段
├── examples.md        # 可选：输入输出对照
└── scripts/           # 可选：可执行脚本（校验、生成等）

注意：各产品对「内置技能目录」有保留路径（例如仅供系统管理的目录），自建 Skill 应放在文档指明的用户/项目目录，勿与系统内置目录混用。

3. SKILL.md 元数据要点

  • name：短、小写、连字符，便于区分（如 git-commit-conventional）。
  • description：
    • 用 第三人称 写能力（便于拼进系统提示）。
    • 同时包含 能力列表 与 触发条件（用户原话可能出现的词）。

4. 正文写作原则（与官方一致）

  • 能短则短：默认模型已具备通用知识；只补充 专有流程与约束。
  • 渐进披露：核心步骤在 SKILL.md；细节进 references/，正文中说明 何时打开。
  • 控制篇幅：主文件过长时拆文件，避免一次加载占满上下文。
  • 自由度分级：易错操作给 低自由度（固定命令/脚本）；开放题给 高自由度（原则 + 示例）。

5. 验收标准（自测）

  • 新对话里 不提 skill 文件名，仅用自然语言描述任务，Agent 能否稳定选用该 Skill。
  • 同事 clone 仓库 后，是否仅凭 .cursor/skills/ 就能复现行为（无「我本机另有一份说明」）。
  • 更新流程后，是否只改 一处 即可（避免 SKILL 与 README 长期分叉）。

五、延伸阅读与工具入口

类型 说明
Cursor 侧 编辑器内与文档中的 Creating Skills / create-skill 指引（SKILL.md 结构、description、目录约定）。
Claude 侧 Skill Creator 类文档（模块化、references//scripts/ 分工、简洁原则）。
本站 可与「工作流自动化」「Prompt/规范」类笔记交叉链接；新建 Skill 时优先 引用仓库内已有规范 而非重复粘贴。

小结

  • Skill = 可发现、可加载、可复用 的 Agent 指令包，核心是 SKILL.md 的 description + 精简正文，资源外置以省 token。
  • 应用 聚焦：重复流程、强规范、强输出形态；实时数据与大块静态手册应用 MCP 与 references/ 配合。
  • 自建 路径：澄清场景 → 写元数据 → 最短闭环 → 再拆 reference/script → 用触发率与可复现性验收。
    续篇（完整构建示例 + 字段说明 + Agent 解析/调用概念模型）：skills-01.Skill 构建示例与 Agent 解析机制。
    若后续在本系列补 「Skill 与 MCP 对照示例」 或 「团队 Skill 评审 checklist」，可与本文并列成篇，便于和站内其他开发笔记一样按主题检索。
-------------本文结束感谢您的阅读-------------