引言

你可能遇到过这种情况：同一个任务（会议纪要、代码评审、发布流程、合规检查）每次都要把“长长的规则”再贴一遍；而当这些规则越来越复杂，又会把上下文挤爆、让模型抓不住重点。

这期视频把 Agent Skill 讲得很透：它不是“更强的提示词”，而是一种可复用的能力封装方式，并且通过 渐进式披露（progressive disclosure） 做到“只在需要时加载”。视频还强调了一个关键对比：Skill 和 MCP 能力有交集，但定位不同，很多场景应该组合使用。Agent Skill 从使用到原理，一次讲清

本文会基于视频主线，结合 Agent Skills 规范与主流工具文档，把“从使用到原理”讲清楚，并给你一套可直接复用的写 Skill 方法论。

Agent Skill 是什么

用一句话概括：Agent Skill 是一个目录（folder），里面包含 SKILL.md 指令文件，以及可选的脚本、参考资料、资源文件；AI 工具会在合适的时机发现并加载它们。Agent Skills 概览 Skills explained

从规范角度看，一个最小 Skill 的目录结构如下：Agent Skills Specification

1
2
skill-name/
  SKILL.md

而更实用的结构通常会把“长知识/长规则”放到 references/，把“可执行自动化”放到 scripts/：

1
2
3
4
5
6
meeting-minutes/
  SKILL.md
  references/
    FINANCE.md
  scripts/
    upload.py

核心机制：渐进式披露（Progressive Disclosure）

Agent Skills 的关键不是“把提示词收纳起来”，而是 加载策略。规范把它分成三层：Agent Skills Specification

  1. Metadata（约 ~100 tokens）：启动时只加载 name、description，让 agent 知道“有哪些技能”和“什么时候用”。
  2. Instructions（建议 < 5000 tokens）：当 agent 认为某个 Skill 相关时，才加载 SKILL.md 正文指令。
  3. Resources（按需）：只有当指令引用到 references/、scripts/、assets/ 等文件时，才会进一步读取/执行。

VS Code 文档也用类似的“三层加载”描述了这一点：Use Agent Skills in VS Code

注意：这套设计直接解决了“可复用规则很长”与“上下文很贵”之间的矛盾：你可以装很多 Skill，但每次只为当前任务付出必要的上下文成本。

基础用法：写一个会议纪要 Skill（可复用、可迁移）

1) 先写对目录名和 Frontmatter

Agent Skills 规范对 name 有硬性约束：小写字母/数字/连字符（hyphen），最长 64，且必须与父目录名一致。Agent Skills Specification

例如目录叫 meeting-minutes/，则 SKILL.md 的 frontmatter 应该是：

1
2
3
4
5
---
name: meeting-minutes
description: Summarize meeting transcripts into attendees, agenda items, and decisions. Use when the user asks for meeting minutes, meeting summary, or action items.
compatibility: Works with Agent Skills compatible tools. Requires ability to read local files.
---

2) 再写正文指令（Instruction）

建议把正文写成“可执行的 SOP”，包括输出格式、步骤、边界条件、示例输入输出：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
---
name: meeting-minutes
description: Summarize meeting transcripts into attendees, agenda items, and decisions. Use when the user asks for meeting minutes, meeting summary, or action items.
---

## Goal
Produce clear meeting minutes from a raw transcript.

## Output format (required)
### Attendees
- <name>

### Agenda
1. <topic>

### Decisions
- <decision>

### Action Items
- <owner>: <task> (due: <date or TBD>)

## Procedure
1. Read the transcript carefully and infer attendee names if stated.
2. Group discussion into agenda topics.
3. Extract explicit decisions; do not invent decisions.
4. If budgets, procurement, expenses, or payments are mentioned, follow the Finance Check section and read references/FINANCE.md.
5. If the user asks to upload/sync/send to a server, run scripts/upload.py with the minutes content.

注意：正文越长，触发 Skill 后的上下文成本越高。规范建议把 SKILL.md 控制在 500 行以内，把长材料下沉到 references/。Agent Skills Specification

高级用法一：Reference（按需读取长资料）

视频里用“集团财务手册”演示了 Reference 的价值：只有当会议内容提到费用/预算等关键词时，才加载财务规则；否则不占用上下文 token。Agent Skill 从使用到原理，一次讲清

你可以在 references/FINANCE.md 放合规规则（越聚焦越好）：

1
2
3
4
5
6
7
# Finance policy (excerpt)

## Hotel
- Max hotel reimbursement: 500 CNY per night

## Meals
- Max meal reimbursement: 300 CNY per person per day

然后在 SKILL.md 里写清楚“何时读取”与“读完要做什么”，并用相对路径引用：Agent Skills Specification

1
2
3
4
## Finance Check
Only when budget, procurement, expenses, reimbursement, or payments are mentioned:
- Read [references/FINANCE.md](references/FINANCE.md)
- Flag any amount that exceeds the policy and specify the required approver

高级用法二：Script（执行自动化，而不是堆更多上下文）

视频强调了 Script 的一个关键点：脚本是被执行的，通常不会被当作长文本读进上下文；因此你可以把复杂逻辑放到脚本里，避免把上下文“塞爆”。Agent Skill 从使用到原理，一次讲清

例如 scripts/upload.py（示例为安全起见使用环境变量，不要硬编码密钥）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
import os
import sys
import json
import urllib.request


def main() -> int:
    upload_url = os.environ.get("UPLOAD_URL", "https://example.com/upload")
    token = os.environ.get("UPLOAD_TOKEN", "")

    content = sys.stdin.read()
    if not content.strip():
        print("No content to upload.", file=sys.stderr)
        return 2

    payload = json.dumps({"content": content}).encode("utf-8")
    req = urllib.request.Request(upload_url, data=payload, method="POST")
    req.add_header("Content-Type", "application/json")
    if token:
        req.add_header("Authorization", f"Bearer {token}")

    with urllib.request.urlopen(req, timeout=30) as resp:
        body = resp.read().decode("utf-8", errors="replace")
        print(body)
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

警告：任何“会产生副作用”的脚本（发请求、改线上、发消息）都要做权限与确认机制。不同平台对脚本执行、自动批准（auto-approve）有不同的安全控制，务必先读文档、再在受控环境中试运行。Use Agent Skills in VS Code

Skill 放哪儿？不同工具的常见落地点

同一个 Skill 的目录结构与 SKILL.md 格式是通用的（Agent Skills 标准），但各工具的“扫描路径”和“优先级”不同。

Claude Code

Claude Code 文档给出了清晰的层级与路径：个人级 ~/.claude/skills/<skill-name>/SKILL.md，项目级 .claude/skills/<skill-name>/SKILL.md，并支持用 /skill-name 显式调用。Extend Claude with skills

OpenAI Codex

Codex 支持从 .codex/skills（以及用户/管理员等多个层级）加载 skills，并支持显式/隐式调用两种模式。Agent Skills (Codex)

VS Code GitHub Copilot

VS Code 推荐把项目 skills 放在 .github/skills/（同时兼容 .claude/skills/ 作为 legacy），并且目前处于预览阶段，需要开启 chat.useAgentSkills。Use Agent Skills in VS Code

Cursor

Cursor 也提供了 Agent Skills 的落地文档，并且把“目录结构、触发方式、如何查看/安装/迁移”写得很具体。Agent Skills | Cursor Docs

1) 技能目录（项目级 vs 全局）

根据 Cursor 文档，Cursor 会自动从以下位置发现并加载技能（优先用 .cursor/skills/ 做项目级管理，兼容 .claude/skills/ 和 .codex/skills/ 便于跨工具复用）：Agent Skills | Cursor Docs

  • 项目级：.cursor/skills/
  • 项目级（兼容 Claude）：.claude/skills/
  • 项目级（兼容 Codex）：.codex/skills/
  • 用户级（全局）：~/.cursor/skills/
  • 用户级（全局，兼容 Claude）：~/.claude/skills/
  • 用户级（全局，兼容 Codex）：~/.codex/skills/

2) 创建一个项目级 Skill（推荐）

Cursor 推荐的最小目录结构如下（每个 Skill 是一个文件夹，包含 SKILL.md）：Agent Skills | Cursor Docs

1
2
3
4
.cursor/
  skills/
    meeting-minutes/
      SKILL.md

SKILL.md 的写法与 Agent Skills 标准一致（YAML frontmatter + Markdown 正文）。示例（内容建议用英文写清楚关键词，提升匹配命中率）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
---
name: meeting-minutes
description: Summarize meeting transcripts into attendees, agenda items, decisions, and action items. Use when the user asks for meeting minutes or a meeting summary.
---

## Output format
### Attendees
- <name>

### Agenda
1. <topic>

### Decisions
- <decision>

### Action Items
- <owner>: <task> (due: <date or TBD>)

3) 在 Cursor 里如何触发 Skills

Cursor 文档明确了两种方式：Agent Skills | Cursor Docs

  • 自动触发：Cursor 启动时会发现并加载技能，Agent 会“看到”所有技能，并根据当前上下文决定何时调用。
  • 手动触发：在 Agent 对话中输入 /，搜索技能名称并显式调用。

如果你希望把某个 Skill 变成“只允许手动调用”的斜杠命令效果，可以在 frontmatter 里加 disable-model-invocation: true，这样它只有在 /skill-name 显式调用时才会被包含进上下文。Agent Skills | Cursor Docs

4) 如何在 Cursor UI 里查看已发现的 Skills

Cursor 提供了一个查看入口，便于排查“为什么我写了 Skill 但 Agent 没用”：Agent Skills | Cursor Docs

  1. 打开 Cursor Settings（Windows/Linux：Ctrl+Shift+J）
  2. 进入 Rules
  3. 技能会显示在 Agent Decides 部分

5) 从 GitHub 安装/导入 Skills（团队共享）

如果你想把 skills 放在一个 GitHub 仓库里共享给团队，Cursor 文档给出的操作路径是：Agent Skills | Cursor Docs

  1. Cursor Settings → Rules
  2. 在 Project Rules 部分点击 Add Rule
  3. 选择 Remote Rule (Github)
  4. 输入 GitHub 仓库 URL

6) 从 Rules/Slash Commands 迁移到 Skills（Cursor 2.4+）

如果你之前已经积累了不少“动态规则（Apply Intelligently）”或斜杠命令，Cursor 2.4 内置了 /migrate-to-skills，可以辅助迁移到 .cursor/skills/。Agent Skills | Cursor Docs

文档也给了迁移的边界条件（建议迁移前先读一遍，避免误解）：例如 alwaysApply: true 或带特定 globs 的规则不会被迁移；用户规则也不会被迁移（因为不存储在文件系统中）。Agent Skills | Cursor Docs

共享/可复用的 Agent Skills 项目（GitHub）

如果你不想从零写 Skill，最实用的方式就是“先复用、再改成自己的版本”。这里把你列出的 GitHub 项目按定位做了分组，并给出我建议的阅读顺序（先官方/准官方 → 再精选合集 → 最后按领域挑专用 skills）。

注意：无论从哪里拉取 skills，都建议先人工 Review 一遍 SKILL.md 与 scripts/，特别是会产生副作用的脚本（发请求、改配置、部署、删数据等）。必要时把这类技能设为 disable-model-invocation: true，只允许手动触发。

0) Skills 目录站（可检索/发现）

1) 官方/准官方 Skills Catalog（优先看）

2) 社区“技能包/技能合集”（适合快速找灵感/模板）

3) 面向特定产品/工程场景的 Skills（更“即插即用”）

4) AutoGen Studio（可直接复制粘贴的 skills）

5) 在 Cursor 里复用这些仓库的推荐姿势

结合 Cursor 的 skills 目录约定（项目级 .cursor/skills/ + 全局 ~/.cursor/skills/）以及其 GitHub 导入入口，你通常有两种落地方式：Agent Skills | Cursor Docs

  1. 直接复制某个 skill 文件夹到你的项目里（最稳、最可控）：
1
2
3
# Copy a skill folder into your project-level skills directory
mkdir -p .cursor/skills
cp -R /path/to/repo/skills/<skill-name> .cursor/skills/
  1. 用 Cursor 的 GitHub 导入入口做团队共享：Cursor Settings → Rules → Project Rules → Add Rule → Remote Rule (Github)，把 skills 仓库当作“可版本控制的共享来源”。

Skill vs MCP：到底该选哪个？

视频引用了 Anthropic 的一句话，非常精准：Skills explained

MCP connects Claude to data; Skills teach Claude what to do with that data.

把它翻译成工程视角就是：

  • MCP：解决“连得上”——把 agent 接到数据源/业务系统/工具上，让它能读写、能查、能操作。
  • Skills：解决“会做事”——把流程、规范、模板、判断规则固化下来，让 agent 用一致的方法处理数据并产出结果。

选型建议（实践向）

  1. 如果你现在的问题是“模型总是忘了规则/输出不稳定/每次都要贴提示词”——优先写 Skill。
  2. 如果你现在的问题是“模型拿不到数据/无法执行操作/需要对接系统”——优先上 MCP。
  3. 如果你要做的是“既要拿数据，又要按公司流程处理并输出”——Skill + MCP 组合通常最强：MCP 负责连接与能力暴露，Skill 负责步骤、格式、合规、边界条件。

常见坑与最佳实践清单

  • name/目录名不一致：规范要求 name 必须匹配父目录名，且必须小写+连字符。Agent Skills Specification
  • description 太泛：description 应该同时描述“做什么”和“什么时候用”，并包含关键词以便检索与匹配。Agent Skills Specification
  • SKILL.md 太长：把长材料拆到 references/，保持主文件精炼，避免触发后上下文暴涨。Agent Skills Specification
  • 带副作用的 Skill 让模型自动触发：在 Claude Code 里可以用 frontmatter 控制自动触发（例如 disable-model-invocation: true），把“部署/提交/发布”等动作收回到人工显式调用。Extend Claude with skills
  • 脚本依赖不清：脚本必须写清运行方式、依赖与错误提示，否则 agent 可能会退回去“读代码找怎么跑”，反而浪费上下文并引入风险（视频也提到了这一点）。Agent Skill 从使用到原理，一次讲清

总结

  • Agent Skill = 可移植的能力包：指令（SKILL.md）+ 参考资料（references/）+ 自动化脚本（scripts/）。
  • 渐进式披露是精髓：先元数据、再指令、最后按需资源，既复用又省上下文。
  • Skill vs MCP 不纠结：MCP 负责连接数据与工具，Skill 负责流程与规则；多数工程场景是组合拳。

参考资料

本文由 AI 辅助生成，如有错误或建议，欢迎指出。