❧ Skills 使用指南详尽版
Agent Skills 权威使用指南
本指南基于 Awesome Agent Skills 和 Vercel Labs Skills 官方文档编写，旨在帮助开发者全面掌握 Agent Skills（智能体技能）的使用、管理与开发。
1. 什么是 Agent Skills？
Agent Skills 是一种轻量级的开放标准，用于通过专业知识和工作流程来扩展 AI Agent（如 GitHub Copilot, Claude Code, Cursor, OpenCode 等）的能力。
当你需要执行可重复的工作流程时，无需在每次对话中重复解释流程、知识和偏好。Skills 让你只需教导一次，便能让 AI 学会相关的技能。
核心价值
- 一次配置，处处生效：在多个 AI 工具间共享相同的技能。
- 上下文增强：无需手动粘贴文档，AI 自动读取技能中定义的知识。
- 标准化流程：团队内部统一代码规范、Code Review 标准和开发流程。
2. 快速入门 (CLI 工具)
Vercel Labs 提供了一个强大的命令行工具 skills，用于快速发现、安装和管理 Skills。这是目前最推荐的管理方式。
2.1 安装与基础命令
直接使用 npx 运行，无需全局安装：
# 1. 交互式搜索并安装 Skillsnpx skills find
# 2. 交互式列出已安装的 Skillsnpx skills list
# 3. 交互式移除 Skillsnpx skills remove2.2 安装 Skills 的多种方式
skills add 命令支持极其灵活的安装源：
# 从 GitHub 简称安装 (Owner/Repo)npx skills add vercel-labs/agent-skills
# 从完整的 GitHub URL 安装npx skills add https://github.com/vercel-labs/agent-skills
# 安装仓库中特定的子目录 (只安装单个 Skill)npx skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
# 从本地路径安装 (适用于开发调试)npx skills add ./my-local-skills
# 安装时指定特定的 Skill 名称 (支持通配符)npx skills add vercel-labs/agent-skills --skill frontend-design --skill "Convex Best Practices"2.3 安装范围 (Scope) 与 目标 Agent
你可以控制 Skill 是安装在当前项目还是全局环境，以及对哪些 AI 工具生效。
| 参数 | 说明 | 对应路径示例 |
|---|---|---|
| 默认 (Project) | 安装到当前项目的 .agents/skills/ 或特定工具目录。随项目代码提交到 Git，团队共享。 | ./.copilot/skills/ |
-g, --global | 安装到用户主目录。仅对你个人生效，跨项目可用。 | ~/.copilot/skills/ |
指定目标 Agent：
默认情况下，CLI 会自动检测你安装了哪些 AI 工具。你也可以通过 -a 参数手动指定：
# 仅安装给 GitHub Copilot 和 Claude Codenpx skills add vercel-labs/agent-skills -a github-copilot -a claude-code3. 手动管理与目录结构
了解底层目录结构有助于你手动调整或排查问题。虽然 CLI 是首选，但手动管理依然有效。
3.1 兼容的 AI 工具与路径
目前主流 AI 工具均支持 Skills，只是存放路径略有不同：
| AI 工具 | 项目级路径 (Project Scope) | 全局路径 (Global Scope) |
|---|---|---|
| VS Code (Copilot) | .copilot/skills/ 或 .github/skills/ | ~/.copilot/skills/ |
| Claude Code | .claude/skills/ | ~/.claude/skills/ |
| Cursor | .cursor/skills/ 或 .agents/skills/ | ~/.cursor/skills/ |
| OpenCode | .opencode/skills/ | ~/.config/opencode/skills/ |
| Gemini CLI | .gemini/skills/ | ~/.gemini/skills/ |
| Windsurf | .windsurf/skills/ | ~/.codeium/windsurf/skills/ |
提示：大部分工具现在都支持通用的
.agents/skills/目录，建议优先尝试此通用路径。
3.2 Skill 的内部结构
根据标准定义，每个 Skill 是一个独立的文件夹，包含以下内容：
my-cool-skill/├── SKILL.md # [必需] 核心定义文件（元数据 + 指令）├── scripts/ # [可选] 可执行脚本（Python/Node.js/Shell）├── references/ # [可选] 知识库文档（API Specs, 规范文档）└── assets/ # [可选] 模板文件、图片等静态资源4. 如何开发自定义 Skill
4.1 使用 CLI 初始化
# 在当前目录下创建一个新的 Skill 模板npx skills init my-new-skill4.2 编写 SKILL.md
SKILL.md 是 Skill 的灵魂，它由 YAML Frontmatter 和 Markdown 正文 组成。
---name: vue-composition-api-expertdescription: 能够编写高质量 Vue 3 Composition API 代码的专家，精通 <script setup> 和 Hooks 封装。version: 1.0.0---
# Vue 3 Composition API Expert
## Role Definition (角色定义)你是一个资深的 Vue 3 开发者。当用户要求编写 Vue 组件时，你必须严格遵守以下规则。
## Rules (核心规则)1. **Script Setup**: 必须使用 `<script setup lang="ts">` 语法。2. **No Mixins**: 绝对禁止使用 Mixins，复用逻辑必须提取为 Composable 函数 (useXxx)。3. **Explicit Imports**: 虽然有自动导入，但在示例代码中尽量显式导入 `ref`, `computed` 等，以便用户理解。
## Workflow (工作流程)1. 先分析组件的 Props 和 Emits 定义。2. 思考状态管理需求，决定使用 `ref` 还是 `reactive`。3. 编写代码，最后补充简要的实现说明。
## References (参考资料)详细的 API 风格指南请参考 [references/style-guide.md](references/style-guide.md)4.3 最佳实践技巧
- 引用外部文件：不要把所有内容塞进
SKILL.md。将长文档放在references/下，并在SKILL.md中用相对路径链接引用（如[API文档](references/api.md)），AI 会自动读取链接内容。 - 提供正反示例：像编写 Prompt 一样，给出 “Good Cases” 和 “Bad Cases” 能显著提高 AI 的表现。
- 使用
metadata.internal：如果你正在开发一个还在测试中的 Skill，可以在 Frontmatter 中设置metadata: { internal: true }，防止意外被他人发现或安装（需配合INSTALL_INTERNAL_SKILLS=1环境变量使用）。
5. 热门 Skills 资源精选
以下资源整理自 Awesome Agent Skills，你可以直接使用 npx skills add 安装。
5.1 官方与大厂出品
| 厂商/项目 | GitHub 仓库 | 描述 | 安装命令示例 |
|---|---|---|---|
| Vercel | vercel-labs/agent-skills | Next.js, React, Vercel 部署等全栈开发技能 | npx skills add vercel-labs/agent-skills |
| Anthropic | anthropics/skills | Claude 官方示例，包含代码审查、文档生成等 | npx skills add anthropics/skills |
| Supabase | supabase/agent-skills | PostgreSQL 最佳实践，Supabase 客户端使用指南 | npx skills add supabase/agent-skills |
| Microsoft | microsoft/agent-skills | Azure 云服务开发与管理技能 | npx skills add microsoft/agent-skills |
| Stripe | stripe/ai | Stripe 支付集成指南 | npx skills add stripe/ai |
5.2 编程开发与 UI 设计 (Development & Design)
这是开发者最常使用的分类，涵盖了从 UI 设计到全栈开发的各个环节。
| 类别 | 仓库 (GitHub) | Skill 名称 / 亮点 | 安装/使用说明 |
|---|---|---|---|
| UI/UX 设计 | nextlevelbuilder/ui-ux-pro-max-skill | ui-ux-pro-max-skill 提供从配色、布局到交互设计的专业建议，甚至能生成详细的设计系统文档。 | npx skills add nextlevelbuilder/ui-ux-pro-max-skill |
| 前端开发 | cloudai-x/threejs-skills | Three.js Skills 专用于 WebGL 和 3D 网页开发的技能，包含常见场景的代码片段。 | npx skills add cloudai-x/threejs-skills |
| 全栈流程 | obra/superpowers | Superpowers 涵盖了从需求分析、功能实现到测试部署的完整编程工作流，适合作为通用的编程助手增强。 | npx skills add obra/superpowers |
| 技术栈特定 | czlonkowski/n8n-skills | n8n Skills 指导 AI 编写和调试 n8n 自动化工作流的 JSON 配置。 | npx skills add czlonkowski/n8n-skills |
| 代码质量 | clean-code-guardian | Clean Code Guardian 强制 AI 使用《Clean Code》原则生成代码，如更具表现力的命名和单一职责函数。 | 搜索关键词: clean-code |
| Git 协作 | conventional-commits | Conventional Commits 自动生成符合 Angular 规范的 Git 提交信息（feat, fix, chore…）。 | 搜索关键词: conventional-commits |
5.3 生产力与内容创作 (Productivity)
| 类别 | 仓库 (GitHub) | 技能亮点 |
|---|---|---|
| 浏览器自动化 | browser-use/browser-use | 指导 AI 使用 Playwright/Puppeteer 控制浏览器，进行爬虫或测试。 |
| 多媒体分析 | op7418 (歸藏) | 包含 YouTube 视频总结、分析等技能，适合从视频中快速提取知识。 |
| 文案写作 | JimLiu/baoyu-skills | 知名博主宝玉的自用技能库，包含公众号文章润色、PPT 大纲生成等。 |
6. 常见问题 (Troubleshooting)
Q: 安装后 AI 似乎没有读取到 Skill？
- 检查路径：确认 Skill 文件夹是否在正确的
.copilot/skills/(或其他工具对应路径) 下。 - 重启工具：VS Code 或 Claude Code 有时需要重启窗口才能重新加载 Skills 索引。
- YAML 格式：检查
SKILL.md头部的 YAML Frontmatter 是否格式正确（缩进、冒号后空格）。
Q: 如何更新已安装的 Skills？ 使用 CLI 的更新命令，它会检查并拉取远程仓库的最新更改：
npx skills check # 检查更新npx skills update # 执行更新Q: 如何卸载？
npx skills remove my-skillnpx skills remove --all # 慎用：删除所有 Skills