import PromptScenarios from '../components/PromptScenarios';

# 如何使用 Skill

本文档介绍如何在项目中使用 CloudBase AI Skills。Skills 是一套包含指令与资源的「技能包」，用于把云开发的专业知识与步骤注入 AI；**搭配 MCP 使用时，MCP 提供连接与权限，Skills 提供规则与直觉**，效果更好。

---

## 方式 1：安装 Skills（推荐）

通过 [Skills 开放规范](https://agentskills.io/) 安装 CloudBase Skills 到本地项目，适用于支持 Skills 的 AI 工具（如 Claude Code、Cursor、VS Code、GitHub Copilot、OpenCode 等）。

### 安装 Skills

在项目根目录执行：

```bash
npx skills add tencentcloudbase/cloudbase-skills
```

按提示选择你的 AI 工具，安装完成后 Skills 会出现在当前项目中（如 `.cursor/skills`、`.claude/skills` 等，视工具而定）。

如果你希望直接通过自然语言触发安装，也可以先对 AI 说“安装 CloudBase Skills”。

如果只想安装单个 Skill，可以执行：

```bash
npx skills add https://github.com/tencentcloudbase/skills --skill auth-tool
```

如果想先在线查看某个 Skill 的内容，可以直接打开：

- [cloudbase-platform](https://skills.sh/tencentcloudbase/skills/cloudbase-platform)

### 触发 Skills

目前 Skills 不易被稳定激活，与模型和工具有关，但可通过工程化手段提升。Skills 采用**渐进式加载**：AI 先根据 Skill 的名称与描述判断是否相关，再在需要时加载完整指令，避免占满上下文。

若希望 AI 更稳定地使用 CloudBase 相关 Skill，可以：

- **首行注入**：在提问开头加一句，例如：*「You MUST identify the CloudBase scenario first, then read `auth-tool` / `http-api` / `miniprogram-development` / `ui-design` as appropriate before implementation.」*
- **项目级规则**：在项目根目录的 `CLAUDE.md` 或 `AGENT.md` 中写入同样的路由约束，无需每次在对话里重复。
- **Hooks（编辑器钩子）**：在发送前通过编辑器钩子强制 AI 先做“场景识别 -> first-read -> before-action 检查”再回答，激活率最高。完整思路与配置见 [CloudBase Skills：后发制人的“岗位手册”](https://mp.weixin.qq.com/s/aFjz4D3VMNH98-7oPKnISw)。

推荐直接把高频路由写成显式规则：

- 登录 / 注册 / 认证配置：先读 `auth-tool`，再读平台实现 skill。
- 原生 App / Flutter / React Native：先读 `http-api`，不要先走 Web SDK。
- 小程序 + 云开发：先读 `miniprogram-development`，再看 `auth-wechat` 或数据库 skill。
- 页面 / 组件 / 样式：先读 `ui-design`，先输出设计规格，再写 UI 代码。

**激活率**：未做任何干预时较低；首行注入或项目规则可明显提升；Hooks 对“必须先读关键知识”这类场景最稳定。

### 搭配 MCP 使用

建议同时配置 **CloudBase MCP**：MCP 负责与云开发环境的安全连接与工具调用，Skills 负责开发规范与最佳实践。两者一起用，AI 既能「有权限」操作云资源，又能「懂规矩」按生产级方式写代码。

- 连接方式（本地模式 / 托管模式）与配置步骤见 [快速开始](/ai/cloudbase-ai-toolkit/getting-started)。
- 在 IDE 中配置好 MCP 后，再安装上述 Skills，即可在对话中同时使用工具与技能。

---

## 方式 2：手动复制

若当前环境无法使用 `npx skills add`（或你希望完全自定义内容），可以手动把规则或提示词复制到项目中，再由 AI 工具通过「包含文件」等方式读取。

### 复制到哪、怎么用

- **规则类**：将 Markdown 规则放入项目内 AI 工具能读取的位置，例如：
  - Cursor：`.cursor/rules/` 或项目内任意路径，对话中用 `@Files` 引用
  - Claude Code / 其他：`CLAUDE.md`、`AGENT.md` 或 `prompts/*.md`
- **提示词类**：将单条提示词保存为 `prompts/[名称].md`，在对话中通过工具的「包含文件」或 `#文件名`、`@文件` 等方式引用。

不同工具用法略有差异：

- **GitHub Copilot**：`#prompts/auth-web.md`
- **Cursor**：`@Files` 后选择文件
- **Zed**：`/file` 后选择文件

可用的 CloudBase 提示词场景见下方「可用的 Skill 场景」；规则与技能包的完整列表见 [CloudBase AI Toolkit](https://github.com/TencentCloudBase/CloudBase-AI-ToolKit) 仓库。

**激活率**：依赖你是否在对话中主动引用这些文件。若不主动 @ 或 # 引用，AI 自发读取的概率与方式 1 未干预时类似，整体也偏低；主动引用后则按需生效。

---

## 激活率小结

| 方式 | 特点 | 激活率大致情况 |
|------|------|----------------|
| 方式 1 安装 Skills | 易用、与 MCP 搭配好；可配合首行注入、项目规则或 Hooks | 未干预时较低（约 20%）；首行注入/项目规则可提升；Hooks 最高（约 80%+） |
| 方式 2 手动复制 | 灵活、可完全自定义；依赖主动引用文件 | 主动引用时按需生效 |

可根据项目对“规范稳定性”的要求，选择方式 1 内的一种或多种手段，或搭配方式 2。

---

## 可用的 Skill 场景

<PromptScenarios />

---

## 延伸阅读

- **连接与 MCP**：[连接方式：本地模式与托管模式](/ai/cloudbase-ai-toolkit/connection-modes)、[快速开始](/ai/cloudbase-ai-toolkit/getting-started)。
- **教程与案例**：[入门视频与文章](/ai/cloudbase-ai-toolkit/tutorials)。
