2026 Agent Skills 完全指南： 从 SKILL.md 到 Cursor 可复用工作流（含云端 Mac）

根据 Cursor 官方文档，Skill 是便携、可纳入 Git 的能力包，可包含脚本、模板与参考文档，Agent 在判断任务相关时自动选用，也可通过 /skill-name 手动触发。Anthropic 在 2025 年底将同一格式发布为开放标准，规范仓库见 agentskills/agentskills，已被多家 Agent 产品采纳。

• 每次重讲流程：「先跑 lint → 再跑测试 → 再 commit → 再 gh pr create」写进对话，换一个新会话就要重来，且容易漏步骤。
• Rule 始终占上下文：.cursor/rules 里的命名规范、禁止注释等应持久生效，但若把 200 行部署手册也塞进 Rule，会固定消耗 Token，无关任务也被加载。
• 无法团队共享：口头约定无法 PR Review；Skill 目录可进仓库，新人 clone 即获得同一套「专项操作手册」。
• 与 MCP 混淆：MCP 连接外部 API（数据库、Issue 系统）；Skill 告诉 Agent按什么顺序调用已有工具——二者互补，不是替代关系。

一句话：Rule 是入职须知（始终在场），Skill 是部署/审计/开 PR 的专项手册（相关时才翻开）。

Cursor 2.4+ 提供内置 /migrate-to-skills，可将部分 dynamic rules 与旧 slash command 迁移为 Skill，避免 Rule 目录无限膨胀。迁移后建议：Rule 只保留 10 条以内的硬约束，其余流程性内容进 Skill。

每个 Skill 至少是一个目录 + SKILL.md（YAML frontmatter + Markdown 正文）。可选子目录：scripts/（可执行脚本）、references/（长文档）、assets/（模板与配置）。跨工具常见路径：

• Cursor 项目级：.cursor/skills/your-skill/SKILL.md
• 跨平台项目级：.agents/skills/your-skill/SKILL.md
• 用户全局：~/.cursor/skills/ 或 ~/.agents/skills/

开放规范建议的渐进式加载分三级：启动时仅读所有 Skill 的 name + description（约百级 Token 量级）；任务匹配后再读完整 SKILL.md 正文（建议控制在约 5000 Token 以内）；执行中才读取 references/ 或运行 scripts/——脚本输出进入对话，脚本源码不必占满上下文。

---
name: deploy-staging
description: >-
  当用户需要部署到 staging、提到「上线预发」「发布预发环境」时使用。
  关键词：deploy、staging、预发、发布。
paths:
  - "apps/web/**"
---

# 部署到 Staging

## 执行步骤
1. 运行 `scripts/validate.py` 检查环境变量与构建产物
2. 运行 `scripts/deploy.sh staging`
3. 用 curl 命中健康检查 URL，非 200 则停止并提示回滚

## 注意
- production 需用户二次确认

description 是路由键，不是摘要。 应写「何时触发、用户会怎么说」，而非「本 Skill 包含部署说明」。name 须与文件夹名一致，仅小写字母、数字与连字符，最长 64 字符（见 agentskills 规范）。

1. 选定单一职责：例如「创建 PR」或「跑安全审计」，避免一个 Skill 覆盖「从编码到部署到写博客」；复杂任务拆成多个 Skill 组合。
2. 用对话快速起稿：在 Cursor Agent 输入 /create-skill，用自然语言描述触发条件与步骤，让 Agent 生成初版目录结构。
3. 手工落盘与命名：在项目根创建 .cursor/skills/pr-release/，确认 name: pr-release 与文件夹名一致。
4. 编写可验证步骤：采用 Gather → Act → Verify：先读 git status / 分支名，再执行 gh pr create，最后用 gh pr view 核对 URL；失败分支写清楚（如未登录 gh auth login）。
5. （可选）添加 scripts：把重复 bash 放进 scripts/，正文只写「为何运行」——例如部署前校验是为避免缺环境变量导致进程起不来。
6. 实测触发与迁移：用真实任务语句测试 description 是否命中；在 Cursor Settings → Rules 确认 Skill 已被发现；旧 Rule 可用 /migrate-to-skills 批量转换后人工删冗余。

高质量 Skill 还遵循：术语一致（全文统一「部署」不混用「发布/上线」）、路径用正斜杠、正文控制在约 500 行内，细节放进 references/。

• frontmatter 必填字段：name（≤64 字符，小写+连字符）、description（≤1024 字符，非空，用于 Agent 相关性判断）——来源：Agent Skills Specification。
• 渐进加载量级建议：元数据层约百 Token；完整指令层建议 <5000 Token；scripts/ / references/ 仅在需要时加载——来源：同上规范「Progressive disclosure」章节。
• Cursor 可选字段：paths（glob 限定文件范围）、disable-model-invocation: true（仅允许 /skill-name 手动触发，禁止自动挂载）——来源：Cursor Skills 文档。
• 跨平台目录：Claude Code 常读 ~/.claude/skills，Codex CLI 常读 ~/.codex/skills，Cursor 读项目 .cursor/skills；同一 SKILL.md 可提交到 Git 供多工具共享（来源：agentskills.io 与各产品文档）。
• 热门能力方向（2026）：工程向含 PR 自动化、TDD 循环、React/Next 性能审计类 Skill；创意向含 Remotion 视频编排等——选型时优先官方或 Marketplace 签名来源，避免未审计脚本直接 chmod +x 执行。

FAQ 速答：Skill 不会覆盖模型自主性，而是提高一致性；全局 Skill 放 ~/.cursor/skills/（通用提交流程），项目 Skill 放仓库（与本代码库绑定的发布流程）。稳定支持版本：Cursor 2.4+。

Skill 再完善，也依赖一直在线的 macOS 环境：合盖笔记本会打断长时间 Agent 循环；个人 Mac 关机后 Telegram/OpenClaw 类网关会掉线；团队在笔记本上混跑 CI 与 Cursor 容易证书与 Apple ID 冲突。

推荐拓扑：笔记本负责日常编码与 /create-skill 迭代；在租用 Mac 上 clone 同一仓库，用 launchd 保持 Cursor CLI / 网关进程（可参考 OpenClaw launchd 排障文）；PR 类 Skill 在云端执行 gh pr create，避免个人机睡眠导致半拉子提交。与 CI 混部时，继续采用 混合 CI 指南 的 PR/Release 拆分，Skill 只管「怎么做」，构建机只管「跑多快」。

超卖云主机与「同事旧 Mac 借一台」的常见短板：① 构建与 Agent 抢磁盘 IO，Skill 里写的验证脚本超时；② 邻居抖动导致 SSH 断连，长时 Agent 循环中途失败；③ 非裸金属无法保证 Xcode 版本，Skill 中的 xcodebuild 步骤不可复现。

更稳妥的路径：在 JEXCLOUD 多区域裸金属 Mac 上按月开通节点，把项目级 .cursor/skills 与仓库一起部署——独占 Apple Silicon、7×24 在线、可按 sprint 弹性租期。规格与 M4 档位见 定价页；区域与下单见 订单页。