SKILL.md 开放标准 · 三级渐进加载 · Cursor / Claude Code 通用 · 远程 Mac 验收
谁会遇到这个问题？你已在 Cursor、Claude Code 或 Gemini CLI 里用 Agent 写代码，却每次都要重复粘贴「怎么部署、怎么开 PR、怎么跑审计」——上下文被占满，Token 账单却不见少。结论：把流程封装成 Agent Skill（一个带 YAML 头的 SKILL.md 文件夹），Agent 按需加载，跨对话复用；涉及 macOS 脚本或 Xcode 步骤时，可在租用 VNC 远程 Mac上验收 scripts/ 输出。本文结构：Skill vs Rule → 文件规范 → 三级加载 → 创建迁移 → 最佳实践 → 2026 生态 → 实战案例 → FAQ。
AI Agent 的进化路径很清晰：聊天机器人 → 任务助理 → 具备专业领域能力的智能体。传统 Prompt 有三类痛点：每次对话重复描述复杂流程；无关规则占满上下文窗口；团队经验无法跨项目沉淀。
Agent Skill 把「如何做一件事」封装成可复用模块：按需加载、节省 Token、跨对话与跨团队共享。Anthropic 在 2025 年底推动 agentskills.io 开放标准后，Cursor、Claude Code、OpenAI Codex、Gemini CLI 均已兼容同一套 SKILL.md 目录结构。
一句话定义：Skill 是给 AI Agent 写的操作手册，让它在正确时机做正确的事——而不是每次从零推理。
重复劳动：部署、测试、PR 描述每次手写 Prompt，平均多消耗 2k–8k Token/次。
上下文污染：把 500 行规范塞进 Rules，无关文件编辑也带着整包规则。
不可版本化：口头约定无法 PR Review，新人 onboarding 靠复制粘贴聊天记录。
平台割裂：同一套部署流程在 Cursor 与 Claude Code 各写一遍——Skill 标准后可 Git 共享。
| 对比维度 | Rule（规则） | Skill（技能） |
|---|---|---|
| 加载时机 | 始终加载 | 按需 / 相关时加载 |
| 适用场景 | 持久约定（命名、风格） | 复杂工作流（部署、审计） |
| 上下文占用 | 固定占用 | 动态高效 |
| 触发方式 | 自动注入系统提示 | Agent 路由 + /skill-name |
| 类比 | 新人入职须知 | 专项操作手册 |
Skill 还能做什么？自定义 / 命令（如 /deploy）、多步骤工作流打包、领域知识注入、内嵌 Bash/Python/Node 脚本，以及与 Hooks、MCP 联动。站内OpenClaw 技能市场实战讲的是产品内插件；本文讲的是跨编辑器通用的 Skill 文件格式，二者概念相近但生态不同。
标准目录如下（文件夹名 = skill 名称）：
.cursor/skills/
└── deploy-app/
├── SKILL.md # 必须
├── scripts/ # 可选：可执行脚本
│ ├── deploy.sh
│ └── validate.py
├── references/ # 可选：按需加载的参考文档
└── assets/ # 可选：模板与静态资源兼容路径还包括 .agents/skills/（Claude Code、Codex、Gemini CLI）、~/.cursor/skills/（用户全局）、~/.agents/skills/（跨工具全局）。
--- name: deploy-app description: >- 当用户需要部署应用到 staging 或 production 时使用。 关键词：部署、发布、上线、环境切换。 paths: - "apps/web/**" disable-model-invocation: false --- # 部署应用 ## 执行步骤 1. 运行 `scripts/validate.py` 检查环境变量完整性 2. 执行 `scripts/deploy.sh <environment>` 3. 验证健康检查端点返回 200
| 字段 | 必填 | 说明 |
|---|---|---|
| name | 是 | 小写+连字符，必须与文件夹名一致 |
| description | 是 | 路由键：写触发条件，不是摘要 |
| paths | 否 | Glob 限定生效文件范围 |
| disable-model-invocation | 否 | true 时仅手动 /skill-name 触发 |
Agent Skills 采用渐进披露（Progressive Disclosure），官方文档与 agentskills.io 均描述为三个阶段：
发现阶段（启动时）：只读每个 Skill 的 name + description，判断是否与当前任务相关。
激活阶段（匹配时）：读取完整 SKILL.md 指令体，按步骤执行。
按需加载（执行中）：读取 references/ 详细文档；运行 scripts/ 时只把脚本输出回传上下文，脚本本体不占 Token。
触发方式：自动触发（Agent 判断相关，默认）；手动 /skill-name；附加上下文 @skill-name。若 Skill 含危险操作，设 disable-model-invocation: true 强制人工确认后再加载。
可引用数据：社区统计 2026 年初可用 Skill 已超 31,000 个；若全部塞进 Rules，单次对话上下文可能膨胀 10 倍以上——渐进加载让 Agent「知道有很多手册，但只翻开当前那一本」。
最快路径：在 Cursor Agent 对话框输入 /create-skill，描述你想要的 Skill，Agent 生成目录与 SKILL.md。
手动创建：在 .cursor/skills/your-skill-name/ 新建 SKILL.md，填写 frontmatter 与步骤。
可选脚本：把可重复命令放进 scripts/，在正文中用相对路径引用。
验证识别：Cursor Settings → Rules，或重启 Agent 会话，确认 Skill 出现在可用列表。
迁移旧规则：Cursor 2.4+ 可用 /migrate-to-skills 将 dynamic rules 与 slash commands 转为 Skill 文件夹。
Windows 主力机用户在 Cursor 里写好 Skill 后，若 scripts/ 含 bash、xcodebuild 或 notarytool，本地无法真实执行。推荐流程：Git 同步到租用远程 Mac → VNC 打开 Cursor 或终端 → 触发 Skill → 核对脚本 exit code 与日志。涉及钥匙串、公证、TCC 权限的步骤必须 VNC，与站内远程 Mac 权限清单一致。
① description 是路由键，不是摘要。错误写法：「这个 skill 包含部署相关指令」。正确写法：「当用户提到部署、上线、切换 staging/production 时使用」。
② 渐进披露：SKILL.md 控制在 500 行内；细节放 references/；执行逻辑放 scripts/。
③ 单一职责：一个 Skill 聚焦一个领域；「部署 + 安全审计 + 写测试」应拆成三个 Skill 组合使用。
④ 解释为什么：写「部署前运行 validate.py，避免缺失环境变量导致服务启动失败」，而非只写「运行 validate.py」。
⑤ Gather → Act → Verify：先收集信息、再执行、最后验证——Agent 遇到异常时能举一反三。
⑥ 术语一致、路径用正斜杠、错误处理写清楚：脚本失败时是重试、回滚还是中止，须在正文中明确。
| 类别 | 代表 Skill | 用途 |
|---|---|---|
| 开发效率 | Prompt Lookup、Skill Installer、Ralph 编码循环 | 提升指令质量、安装其他 Skill、测试驱动自主迭代 |
| 前端 / Web | React Best Practices、Web Design Audit、Next.js Cache Optimizer | Vercel 出品的性能与可访问性审计 |
| 工作流 | PR Skill、TDD Skill、Skill Writer | 提交→推送→开 PR、测试驱动、 meta 技能 |
| 创意 | Remotion Video Editor | 用 React 描述视频并生成剪辑 |
生态要点（2026）：agentskills.io 跨平台通用；Cursor Marketplace 支持一键安装 Rules + Skills + MCP 组合包；Monorepo 下可用嵌套目录 .cursor/skills/shipping/deploy-staging/SKILL.md 做作用域隔离。
与 MCP 的关系：MCP 连接外部 API（数据库、浏览器、GitHub）；Skill 编排「何时、按什么顺序」调用这些工具。例如 PR Skill 可写：先 git status，再调 GitHub MCP 创建 PR——两者互补而非替代。
场景：每次发布都要提交 → 推送 → 创建 PR → 写描述。Skill 指令：提交所有修改 → 推送到新分支 → 用 gh pr create 开 PR → 按模板填描述。一个 /pr 完成全流程。
场景：反复改代码直到测试通过。Skill 逻辑：运行测试 → 失败则 Agent 修改 → 重跑 → 循环至通过。配合 Hooks 可在 CI 失败时自动唤醒 Agent。
场景：Windows 开发者维护含 xcodebuild archive、notarytool submit 的 Skill。本地 Cursor 只能编辑 Markdown；真实验收在 VNCMac 远程 Mac：VNC 连接 → 触发 Skill → Agent 执行脚本 → 图形界面点钥匙串「始终允许」。这与公证 staple 验收清单同一类「SSH 不够、须 VNC」刚需。
| 验收项 | 本地 Windows | 远程 Mac + VNC |
|---|---|---|
| 编辑 SKILL.md | 可以 | 可以 |
| 跑 bash 部署脚本 | WSL 部分可 | 完整 macOS 环境 |
| xcodebuild / 公证 | 不可 | 必须 |
| 钥匙串 / TCC 弹窗 | 不可 | VNC 图形点击 |
Skill 是结构化指导，不是强制执行。Model 仍自主决策；description 与步骤越清晰，一致性越高。安装社区 Skill 前建议阅读 scripts/ 内容。
用真实任务测试 description 中的触发词；未自动加载时可手动 /skill-name；仍失败则补充同义词到 description 首段。
通用工作流（提交代码、写测试）放 ~/.cursor/skills/；项目特有逻辑（本仓库部署路径、内部 API）放仓库内 .cursor/skills/ 并提交 Git。
格式理念相似（可复用能力模块），但 OpenClaw 技能市场走 ClawHub 安装与 Gateway 插件体系；Cursor Agent Skill 走 SKILL.md + agentskills.io 标准。可并存：OpenClaw 跑 7×24 Gateway，Cursor Skill 管日常编码工作流。
Agent Skill 把团队里「只有老员工知道」的操作流程，变成可版本化、可 Review、可跨平台共享的 SKILL.md。description 写触发条件、正文写 Gather-Act-Verify、脚本放 scripts/ 省 Token——这三条做到，Agent 就从「每次重新教」变成「翻开手册就能干」。
局限也很现实：含 macOS 编译、公证、钥匙串的 Skill，在 Windows 本地只能写不能验；纯 SSH 远程 Mac 又点不了系统弹窗。自购 Mac mini 适合已全年跑 Agent 的团队；仍在搭建 Skill 库、或只需按月验收 iOS/macOS 脚本的用户，租用 VNC 远程 Mac把「写 Skill」与「跑 Skill」拆到两台机器——主力机 Cursor 编辑，云端 Mac 图形验收——比为 occasional 需求买断硬件更划算。
Skill 的价值在复用，复用的前提是环境跑得通。下方进入远程 Mac 套餐，为 macOS 专属 Skill 准备一台可 VNC 验收的节点。