从入门到进阶：使用 Claude Code Skills 提升 AI 开发效率从入门到进阶：使用 Claude Code

从入门到进阶：使用 Claude Code Skills 提升 AI 开发效率

AI 代码助手正在迅猛发展，Claude Code 的 Skills 系统正是其中的亮点。通过将领域知识、规范和工作流程封装为 Markdown 文件，技能让 AI 代理能够快速适应不同项目。这篇文章基于你项目中的 .claude/skills 配置和官方技能目录 skills.sh，为不同阶段的开发者提供一份全面的指南，帮助你更好地理解、安装、编写和运用 Claude Code Skills。

1 什么是技能？

官方文档将技能定义为“可复用的 AI 代理能力”【10237718162004†L15-L16】。它们提供了操作流程、代码模式以及领域知识，帮助 AI 代理有效完成任务。你可以把它理解为插件：安装后，它会增强你的 AI 代理的能力，使其具备某个领域的专业知识【576132420462049†L12-L14】。

技能可以在多种 AI 代理中使用。通过 skills CLI 一条命令即可安装，例如：npx skills add <owner/repo>【10237718162004†L15-L20】。安装后的技能会自动为代理提供相应的能力，无需重复配置【576132420462049†L18-L22】。

2 项目目录与技能管理

在你的项目中，所有技能统一放在 .claude/skills/ 目录。典型的结构如下：

AI-code/
└── .claude/
    ├── settings.local.json   # 权限配置
    └── skills/              # 外部与自定义技能
        ├── next-best-practices/
        ├── vercel-react-best-practices/
        ├── vercel-composition-patterns/
        ├── web-design-guidelines/
        ├── vite-ssr-architecture/
        ├── project-structure/
        └── shared-packages/

settings.local.json 用于权限配置，skills/ 中既包含外部安装的技能，也包含自定义技能。注意： 使用 npx skills add 安装的技能默认在 .agents/skills/ 下，可在安装后移动到 .claude/skills/ 方便管理。

3 安装与使用外部技能（适合新手）

3.1 安装 `skills` CLI

对于刚接触技能系统的开发者，第一步是安装 CLI 工具：

# 推荐直接使用 npx
npx skills --version
# 或全局安装
npm install -g skills

3.2 查找合适的技能

官方目录 skills.sh 罗列了数千个技能，按照安装次数和热度排名。技能描述清晰，适配不同代理类型。下面列出几个与你项目相关的仓库：

仓库	技能示例	适用场景
`vercel-labs/next-skills`	`next-best-practices`	Next.js 15 App Router 应用
`vercel-labs/agent-skills`	`vercel-react-best-practices`、`vercel-composition-patterns`、`web-design-guidelines` 等	React 性能优化、组件 API 设计、设计规范

访问这些仓库，可在 README 中了解每个技能的用途及触发条件。

3.3 安装技能

安装技能非常简单，以 next-best-practices 为例：

npx skills add https://github.com/vercel-labs/next-skills \
  -a claude-code \
  --skill next-best-practices \
  -y

安装多个技能时可以重复使用 --skill 参数：

npx skills add vercel-labs/agent-skills \
  -a claude-code \
  --skill vercel-react-best-practices \
  --skill vercel-composition-patterns \
  --skill web-design-guidelines \
  -y

常用参数包括：

参数	说明
`<source>`	指定技能来源（GitHub URL 或 `owner/repo`）
`-a, --agent`	指定使用的代理（此处为 `claude-code`）
`--skill`	多次使用以选择多个技能
`-y, --yes`	自动确认提示
`-g, --global`	全局安装，所有项目可用

3.4 验证与整理

安装完成后，可通过 ls .claude/skills/ 查看已安装技能列表。由于默认安装路径是 .agents/skills/，建议将其移动至 .claude/skills/：

mv .agents/skills/* .claude/skills/
rm -rf .agents

然后查看每个技能的 SKILL.md 以了解具体规则。

4 自定义技能（中级开发者）

当项目需要特殊的开发流程或规范时，可以编写自定义技能。一个基本的 SKILL.md 包含以下部分：

标题与简介：简要说明技能用途。
Metadata：Name（与目录名一致）、Version、Trigger（何时触发）。
概述与关键文件：描述技能目的及涉及的项目文件。
操作清单：针对不同任务类型列出操作步骤及代码示例。
常见问题：列出潜在错误及解决方案。
相关命令/技能：方便快速跳转。

4.1 命名与内容规范

为了便于识别，技能目录应使用 kebab-case，例如 vite-ssr-architecture、shared-packages。避免使用 PascalCase 或带下划线的名称。

内容方面应遵循四个原则：

原则	含义	示例
具体	提供实际文件路径和代码	修改 `server/index.ts` 第 147 行
可操作	给出明确步骤	1. 创建文件 2. 添加路由 3. 测试
防错	列出常见陷阱	不要在 SSR 中使用 `window`
关联	链接相关文件	详见 `main.tsx`

4.2 编写 Trigger

Trigger 用于描述技能适用的场景。例如：

- **Trigger**: When modifying SSR logic, adding pages, or debugging hydration issues in apps/mobile

避免使用“当你工作在项目上”这样的模糊描述。Trigger 越具体，自动匹配越准确。

4.3 示例：`vite-ssr-architecture`

假设你的项目采用了 Vite + React 的 SSR 架构，可以编写一个名为 vite-ssr-architecture 的技能，其中包含：

SSR 数据流图解：介绍请求从服务器到客户端的流转。
关键文件表：列出 server/index.ts、main.tsx、App.tsx 等关键文件及作用。
操作清单：如“添加页面”、“添加 API 路由”等任务的详细步骤。
Hydration 问题排查：总结常见的 SSR 水合错误及解决方案。

通过这样的自定义技能，团队成员在修改 SSR 逻辑时会获得统一的指导。

5 技能使用方式（中级到高级）

Claude Code 提供多种使用技能的方式，你可以根据场景灵活选择：

方式	触发方法	适用场景
斜杠命令	`/skill-name`	明确需要某个技能时
自动触发	请求匹配 Trigger	日常开发，无需记忆
明确引用	对话中提及技能名	需要精确控制时
组合使用	同时引用多个技能	复杂任务
查询可用技能	`/skills list` 或询问 Claude	不了解当前项目有哪些技能时
预加载技能	在任务前手动加载多个技能	代码审查或复杂实现前

下面结合开发者成长阶段给出建议：

5.1 入门开发者

对于刚开始使用 Claude Code 的开发者来说，建议：

熟悉常用斜杠命令。例如 /vercel-react-best-practices 可自动加载 React 性能优化规则，避免明显的渲染问题。
在修改业务代码前先加载相应技能，如开发 Next.js 页面时执行 /next-best-practices。
遇到错误时可直接问 Claude：“你是否参考了 vite-ssr-architecture skill？” 观察回答中的引用，确认技能已生效。

5.2 中级开发者

当你对技能系统有初步了解后，可以：

自定义和修改技能。根据项目需要编写自己的 SKILL.md，设置清晰的 Trigger。
利用组合技能处理复杂任务，例如添加共享组件时同时加载 shared-packages 与 vercel-composition-patterns。
在代码审查前，手动加载性能优化、设计规范等技能，让 Claude 能从多个维度提供建议。

5.3 高级开发者

资深开发者则可以进一步利用技能提升团队协作：

跨项目配置：对 Monorepo 管理的多个应用分别创建技能，并在不同分支中维护版本。
流程自动化：编写技能触发自动化脚本，例如在合并请求触发代码审查技能。
知识沉淀：将团队经验抽象为技能模块，随代码库一同迭代。
隐性约束：在 AGENTS.md 中定义全局规则（如必须写单元测试、禁止跨应用依赖），并链接相关技能。

6 项目实践：添加设置页

以 vite-ssr-architecture 技能为例，假设你需要为 mobile 应用添加一个 /settings 页面，可以按如下步骤操作：

执行 /vite-ssr-architecture 加载技能，Claude 会掌握 SSR 架构细节。
创建页面组件 src/pages/SettingsPage.tsx，返回对应的 UI。
在 App.tsx 中添加路由 <Route path="settings" element={<SettingsPage />} />。
在 server/index.ts 的路由处理函数中添加对 /settings 的数据预取逻辑，并更新标题。
运行 pnpm --filter mobile dev:ssr，访问 /settings 验证 SSR 和 Hydration 是否正常。

利用技能的指导，以上步骤每一个细节都能在 SKILL.md 中找到对应说明，避免遗漏数据预取或路由配置。

7 最佳实践与团队协作

日常工作流：在开始任务前先思考是否需要加载技能，开发过程中让 Claude 自动匹配，代码审查时手动加载审查相关技能。
及时维护：当项目架构调整或新组件引入时，及时更新相关技能，并在 Metadata 中修改版本号。
统一存放：所有技能放在 .claude/skills 目录，随代码提交到版本库，确保团队成员始终使用同一套指导。
善用 Trigger：合理设置 Trigger 能提高自动匹配的准确度，减少误触发。
撰写清晰示例：技能中的示例需包含文件路径、上下文和行号，而不是孤立的代码片段。

8 常见问题解答

Q: 如何确认某个技能已经加载？
使用 /skill-name 命令后 Claude 会提示加载成功。你也可以直接询问：“你是否参考了 xxx skill？” 若 Claude 的回答包含技能内容，则说明已生效。

Q: 技能更新后如何重新加载？
在当前对话中重新使用斜杠命令，或开启新的对话，Claude 会读取最新的技能版本。

Q: 可以为不同分支使用不同的技能配置吗？
可以。技能文件跟随代码提交，不同分支可以拥有不同的 .claude/skills 目录。

Q: 自动触发不准确怎么办？
在请求中明确指出要使用的技能，如“请按照 vite-ssr-architecture skill 的指南…”。

Q: 如何禁用某个技能的自动触发？
在请求里声明不要使用某个技能，例如“不使用 vite-ssr-architecture skill，我只需要客户端实现”。

9 结语

通过本篇文章，你已经了解了 Claude Code Skills 的基本概念、目录结构、安装方法及编写规范，并掌握了针对不同阶段开发者的使用策略。官方文档指出，技能不仅提供知识，还通过匿名遥测排名帮助你发现最受欢迎的能力【576132420462049†L26-L31】。善用技能，可以让你的 AI 代理快速适应项目，提升团队协作效率。未来，你也可以在 skills.sh 上探索更多技能或贡献自己的技能，与社区一起完善这一生态。

从入门到进阶：使用 Claude Code Skills 提升 AI 开发效率