# VuePress Plume Skills

此目录包含为 VuePress Plume 主题定制的专用技能（Skills），旨在通过 AI 代理提升您的开发体验。

## 1. 技能介绍

`skills` 目录目前提供以下技能：

### 🌟 可用技能

| 技能名称 | 描述 | 主要特性 |
| ---------- | ----------- | ------------ |
| **vuepress-plume-config** | 主题配置生成器 | • 生成 `config.ts`, `plume.config.ts`<br>• 管理 `themeConfig`, `navbar`, `sidebar`<br>• 支持 `locales` 和 `plugins` 配置 |
| **vuepress-plume-markdown** | Markdown 写作助手 | • 提供 Plume Markdown 扩展语法<br>• 支持图表 (Mermaid, ECharts 等)<br>• 支持嵌入 (YouTube, Bilibili, PDF) |

### 🔍 选择指南

- **使用 `vuepress-plume-config` 的场景：**
  - 初始化一个新的 VuePress Plume 项目。
  - 需要更新主题配置、导航栏或侧边栏。
  - 需要配置复杂设置，如多语言或插件。

- **使用 `vuepress-plume-markdown` 的场景：**
  - 编写 Markdown 内容文件。
  - 需要使用高级功能，如容器、代码组或图表。
  - 需要嵌入媒体或外部内容。

---

## 2. 安装与配置

您可以使用 `skills` CLI 工具将这些技能安装到您的项目中或全局安装。

### 前置要求

- 已安装 Node.js
- `npx` 可用

### 安装步骤

1. **从本仓库安装特定技能：**

    ```bash
    # 安装到当前项目（团队协作推荐）
    npx skills add https://github.com/pengzhanbo/vuepress-plume

    # 仅安装特定技能
    npx skills add https://github.com/pengzhanbo/vuepress-plume --skill vuepress-plume-config
    ```

2. **验证安装：**

    ```bash
    npx skills list
    ```

    您应该能看到已安装的技能列在输出中。

---

## 3. 集成指南

### 🤖 Claude Code 集成

Claude Code 会自动检测 `.claude/skills` 目录或配置的标准 `skills` 目录中的技能。

**设置：**

```bash
# 专为 Claude Code 安装
npx skills add https://github.com/pengzhanbo/vuepress-plume -a claude-code
```

**配置：**
确保您的 `~/.claude/config.json` 或项目配置允许从安装位置加载技能。

### 🌐 OpenCode 集成

OpenCode 支持开放代理技能（open agent skills）标准。

**设置：**

```bash
# 为 OpenCode 安装
npx skills add https://github.com/pengzhanbo/vuepress-plume -a opencode
```

**使用：**
安装后，OpenCode 代理将自动索引技能，并可通过自然语言提示调用。

### 🚀 Trae 集成

Trae 是一个强大的 IDE，可以利用这些技能更好地协助您。

**设置：**

1. **项目级：** 克隆或安装技能到您项目的 `skills/` 目录。Trae 可以扫描并利用项目工作区中的 `SKILL.md` 文件。
2. **使用：** 直接要求 Trae 执行与技能相关的任务。

**示例：**
> "帮我使用 plume config skill 配置 VuePress 站点的导航栏。"

**调试：**
如果 Trae 无法识别技能，请确保 `SKILL.md` 文件有效且包含正确的 frontmatter（name, description）。

---

## 4. 使用示例

### 🛠️ 使用 `vuepress-plume-config`

**场景：** 初始化一个新的配置文件。

**提示词：**
> "Generate a `config.ts` for my VuePress Plume site with a blog setup, English and Chinese locales, and the filesystem cache enabled."
> （"为我的 VuePress Plume 站点生成一个 `config.ts`，包含博客设置、中英文多语言支持，并启用文件系统缓存。"）

**结果：**
代理将使用技能创建一个包含请求配置结构的 `src/.vuepress/config.ts` 文件。

### 📝 使用 `vuepress-plume-markdown`

**场景：** 向文档页面添加复杂图表。

**提示词：**
> "I want to add a timeline of VuePress release history to my markdown file using the Plume timeline extension."
> （"我想使用 Plume 时间轴扩展在 Markdown 文件中添加 VuePress 发布历史的时间轴。"）

**结果：**
代理将引用 `vuepress-plume-markdown` 技能提供正确的语法：

```markdown
::: timeline 2024
2024-01-01: **VuePress Plume v1.0.0 Released**
The first official release.

2024-06-01: **Feature Update**
Added support for new markdown extensions.
:::
```

---

## 5. 最佳实践

### 建议

- **版本控制：** 如果使用项目级技能，请将 `skills/` 目录提交到 Git。这确保所有团队成员都能使用相同的功能。
- **更新：** 定期检查技能更新以获取最新功能和修复。

    ```bash
    npx skills update
    ```

### 性能与安全

- **审查更改：** 在部署之前，始终审查由 `vuepress-plume-config` 技能生成的配置文件。
- **安全执行：** 这些技能主要生成文本/代码。在大多数代理环境中，未经用户确认，它们不会直接执行系统命令。