wskill 1.1.0
Windsurf Skill Manager - 搜索和管理Windsurf技能的命令行工具
License: MIT
Requires Python: >=3.10
Keywords: windsurf, skill, cli, search, cascade

<div align="center">

# 🚀 wskill

**Windsurf Skill Manager**

[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg)]()

一个用于搜索和管理 **Windsurf 技能** 的命令行工具  
安装后通过 `wskill` 命令快速搜索相关技能供 Windsurf/Cascade 使用

[功能特性](#功能特性) •
[安装方法](#安装方法) •
[使用方法](#使用方法) •
[命令参考](#命令参考)

</div>

## 功能特性

| 功能 | 描述 | 命令 |
|------|------|------|
| 📋 **列出技能** | 查看所有可用的 Windsurf 技能 | `wskill list` |
| 📁 **分类浏览** | 按类别（云服务、前端、AI等）分组查看 | `wskill list -c` |
| 🔍 **关键词搜索** | 支持中英文关键词搜索技能 | `wskill search <关键词>` |
| 📖 **详情查看** | 查看技能完整信息和使用说明 | `wskill show <技能名>` |
| 🔥 **热门发现** | 查看 skills.sh 热门在线技能 | `wskill trending` |
| ⬇️ **一键安装** | 安装热门在线技能 | `wskill install <技能>` |
| 🌐 **打开网站** | 打开 skills.sh 发现更多技能 | `wskill web` |

## 安装方法

### 方式一：从 GitHub 安装（推荐）

```bash
# 克隆仓库
git clone https://github.com/1837620622/wskill.git

# 进入目录并安装
cd wskill
pip install -e .

# 安装 MCP 服务器（可选，用于 Windsurf 集成）
pip install -e ".[mcp]"
```

### 方式二：手动安装

<details>
<summary>macOS / Linux</summary>

```bash
# 进入项目目录
cd /path/to/wskill

# 使用 pip 安装
pip install -e .

# 或使用 pip3
pip3 install -e .
```

</details>

<details>
<summary>Windows</summary>

```powershell
# 进入项目目录
cd C:\path\to\wskill

# 使用 pip 安装
pip install -e .
```

</details>

### 验证安装

```bash
wskill --version
# 输出: wskill 1.0.0
```

## 使用方法

### 列出所有技能

```bash
wskill list
```

<details>
<summary>📸 输出示例</summary>

```
Windsurf Skills (25 个技能)
==================================================

1. analytics-metrics v1.0.0
   构建数据可视化和分析仪表盘。适用于创建图表、KPI展示...
   关键词: analytics, dashboard, charts, metrics, KPI

2. kaggle-competition v2.0.0
   制作Kaggle机器学习比赛的完整解决方案...
   关键词: Kaggle, competition, 比赛, notebook, ipynb

3. ui-ux-pro-max v1.0.0
   专业的 UI/UX 设计智能技能...
   关键词: UI design, UX, frontend design, color scheme
...
```

</details>

### 按类别浏览

```bash
wskill list -c
```

<details>
<summary>📸 输出示例</summary>

```
Windsurf Skills 分类列表
==================================================

📁 云服务与部署 (6)
   • aws-account-management
   • aws-agentcore
   • aws-strands
   • cloudflare
   • railway
   • vercel

📁 数据与可视化 (2)
   • analytics-metrics
   • mermaid-diagrams

📁 AI与机器学习 (5)
   • kaggle-competition
   • langchain
   • fal-ai
   • copilot-docs
   • nano-banana-pro

📁 前端与UI/UX (4)
   • figma
   • mobile-responsiveness
   • ui-ux-pro-max
   • web-accessibility

📁 数据库 (1)
   • mongodb

📁 文档处理 (2)
   • docx
   • xlsx

📁 开发工具 (2)
   • bun
   • github-trending
```

</details>

### 搜索技能

```bash
# 搜索英文关键词
wskill search kaggle

# 搜索中文关键词
wskill search 仪表盘

# 搜索技术栈
wskill search dashboard
```

<details>
<summary>📸 输出示例</summary>

```bash
$ wskill search kaggle

搜索 'kaggle' 找到 1 个技能:
==================================================

1. kaggle-competition v2.0.0
   制作Kaggle机器学习比赛的完整解决方案。适用于创建比赛notebook、
   数据分析、特征工程、模型训练和提交文件生成...
   关键词: Kaggle, competition, 比赛, notebook, ipynb (+3)
```

</details>

### 查看技能详情

```bash
wskill show ui-ux-pro-max
```

### 发现热门在线技能

```bash
# 查看 skills.sh 热门技能排行
wskill trending

# 安装热门技能（需要 Node.js）
wskill install react

# 打开 skills.sh 网站
wskill web
```

<details>
<summary>📸 热门技能输出示例</summary>

```
🔥 热门 Agent Skills (来自 skills.sh)
=======================================================

1. vercel-react-best-practices ⬇ 23.5K by Vercel
   40+ 条 React/Next.js 优化规则
   仓库: vercel-labs/agent-skills

2. web-design-guidelines ⬇ 17.9K by Vercel
   100+ 条 UI/UX 审查规则
   仓库: vercel-labs/agent-skills

3. remotion-best-practices ⬇ 1.1K by Remotion
   Remotion 视频制作最佳实践
   仓库: remotion-dev/remotion
...
```

</details>

<details>
<summary>📸 输出示例</summary>

```
============================================================
  ui-ux-pro-max
============================================================

版本: 1.0.0
作者: UI/UX Pro Max
路径: /Users/xxx/.codeium/windsurf/skills/ui-ux-pro-max

描述:
  专业的 UI/UX 设计智能技能。适用于前端界面设计、配色方案选择、
  字体搭配、图表选型、Landing Page 和 Dashboard 设计...

关键词:
  UI design, UX, frontend design, color scheme, typography,
  dashboard, landing page, glassmorphism, dark mode, responsive

内容预览:
  ---
  name: ui-ux-pro-max
  description: "专业的 UI/UX 设计智能技能..."
  ...
```

</details>

## 命令参考

### 本地技能管理

| 命令 | 别名 | 描述 | 示例 |
|------|------|------|------|
| `list` | `ls`, `l` | 列出所有技能 | `wskill list` |
| `list -c` | `list --category` | 按类别分组显示 | `wskill list -c` |
| `search` | `s`, `find` | 搜索技能 | `wskill search kaggle` |
| `show` | `info`, `i` | 显示技能详情 | `wskill show ui-ux-pro-max` |
| `path` | - | 显示技能目录路径 | `wskill path` |

### 在线技能发现 (skills.sh)

| 命令 | 别名 | 描述 | 示例 |
|------|------|------|------|
| `trending` | `hot`, `t` | 查看热门在线技能 | `wskill trending` |
| `install` | `add`, `get` | 安装在线技能 | `wskill install react` |
| `web` | `open` | 打开 skills.sh 网站 | `wskill web` |

### 通用选项

| 命令 | 别名 | 描述 | 示例 |
|------|------|------|------|
| `--help` | `-h` | 显示帮助信息 | `wskill --help` |
| `--version` | `-v` | 显示版本号 | `wskill --version` |

## 📂 技能目录结构

技能存储在 `~/.codeium/windsurf/skills/` 目录下：

```
~/.codeium/windsurf/skills/
├── analytics-metrics/
│   └── SKILL.md
├── kaggle-competition/
│   └── SKILL.md
├── ui-ux-pro-max/
│   ├── SKILL.md
│   ├── data/
│   │   ├── colors.csv
│   │   ├── typography.csv
│   │   └── ...
│   └── scripts/
│       ├── core.py
│       └── search.py
└── ...
```

## 🔗 在 Windsurf 中使用

搜索到合适的技能后，在 Windsurf 对话中提及技能关键词，Cascade 会自动调用相应技能：

```
👤 用户: 帮我创建一个Kaggle比赛的Notebook
🤖 Cascade: [自动调用 kaggle-competition 技能]

👤 用户: 设计一个现代化的Dashboard界面
🤖 Cascade: [自动调用 ui-ux-pro-max 技能]

👤 用户: 帮我画一个流程图
🤖 Cascade: [自动调用 mermaid-diagrams 技能]
```

## ➕ 添加自定义技能

1. 在技能目录创建新文件夹：
   ```bash
   mkdir ~/.codeium/windsurf/skills/my-skill
   ```

2. 创建 `SKILL.md` 文件：
   ```markdown
   ---
   name: my-skill
   description: "技能描述。触发关键词：keyword1, keyword2, 中文关键词。"
   author: YourName
   version: 1.0.0
   ---

   # 技能标题

   ## 概述
   技能内容...

   ## 使用方法
   ...
   ```

3. 验证技能是否加载：
   ```bash
   wskill search my-skill
   ```

## 📋 依赖

| 包名 | 版本 | 用途 |
|------|------|------|
| Python | ≥ 3.10 | 运行环境（MCP需要） |
| PyYAML | ≥ 6.0 | 解析 SKILL.md frontmatter |
| mcp | ≥ 1.0.0 | MCP服务器框架 |

## 🔌 MCP 服务器集成

wskill 提供 MCP（Model Context Protocol）服务器，可直接在 Windsurf 中调用技能搜索功能。

### 配置 Windsurf MCP

#### 方式一：自动配置（推荐）

```bash
# 安装 wskill
pip install -e .

# wskill-mcp 命令会自动注册到系统
```

#### 方式二：手动配置

1. 找到 Windsurf MCP 配置文件：
   - **macOS/Linux**: `~/.codeium/windsurf/mcp_config.json`
   - **Windows**: `%APPDATA%\Codeium\windsurf\mcp_config.json`

2. 添加 wskill 服务器配置：

```json
{
  "mcpServers": {
    "wskill": {
      "command": "wskill-mcp",
      "args": [],
      "disabled": false
    }
  }
}
```

3. 重启 Windsurf 使配置生效

#### 完整配置示例

```json
{
  "mcpServers": {
    "wskill": {
      "command": "wskill-mcp",
      "args": [],
      "disabled": false
    },
    "其他服务器": {
      "...": "..."
    }
  }
}
```

### MCP 工具列表

| 工具 | 描述 | 参数 |
|------|------|------|
| `list_local_skills` | 列出本地已安装的技能 | `category`: 可选，按类别筛选 |
| `search_local_skills` | 搜索本地技能 | `query`: 搜索关键词 |
| `get_skill_detail` | 获取技能详细信息 | `name`: 技能名称 |
| `get_skill_categories` | 获取技能分类 | 无 |
| `get_trending_online_skills` | 获取 skills.sh 热门排行 | 无 |
| `search_online_skills_tool` | 搜索在线技能 | `query`: 搜索关键词 |
| `install_online_skill` | 安装在线技能 | `skill_name`: 技能名称 |
| `get_skills_path` | 获取技能目录路径 | 无 |

### 在 Windsurf 中使用

配置完成后，可以直接在 Cascade 对话中请求：

```
👤 用户: 帮我搜索 React 相关的技能
🤖 Cascade: [调用 search_local_skills("react") 和 search_online_skills_tool("react")]
   返回本地和在线匹配的技能列表

👤 用户: 安装 frontend-design 技能
🤖 Cascade: [调用 install_online_skill("frontend-design")]
   技能将安装到 ~/.codeium/windsurf/skills/ 目录

👤 用户: 显示热门技能排行榜
🤖 Cascade: [调用 get_trending_online_skills()]
   显示 skills.sh 热门技能排行

👤 用户: 查看 kaggle-competition 技能详情
🤖 Cascade: [调用 get_skill_detail("kaggle-competition")]
   返回技能的完整信息和使用说明
```

### 验证 MCP 配置

重启 Windsurf 后，在 Cascade 中输入：

```
请调用 wskill MCP 的 get_skills_path 工具
```

如果返回技能目录路径信息，说明 MCP 配置成功。

## 🔗 关联项目

| 项目 | 描述 |
|------|------|
| [Super-Agent-Skills](https://github.com/1837620622/Super-Agent-Skills) | 🎯 Windsurf 技能合集仓库，包含丰富的预置技能 |
| [skills.sh](https://skills.sh) | 🔥 Vercel 官方 Agent Skills 排行榜 |

## 🖥️ 平台支持

| 平台 | 技能目录路径 | 状态 |
|------|-------------|------|
| **macOS** | `~/.codeium/windsurf/skills/` | ✅ 官方确认 |
| **Linux** | `~/.codeium/windsurf/skills/` | ✅ 官方确认 |
| **Windows** | `%APPDATA%\Codeium\windsurf\skills\` | ✅ 支持 |

> 📖 参考: [Windsurf Skills 官方文档](https://docs.windsurf.com/windsurf/cascade/skills)

## �‍💻 作者信息

| 信息 | 内容 |
|------|------|
| **作者** | ChuanKang |
| **GitHub** | [@1837620622](https://github.com/1837620622) |
| **项目地址** | [https://github.com/1837620622/wskill](https://github.com/1837620622/wskill) |
| **许可证** | MIT License |

## �📄 许可证

本项目采用 [MIT License](LICENSE) 开源许可证。

<div align="center">

Made with ❤️ by [ChuanKang](https://github.com/1837620622) for Windsurf Users

**[wskill](https://github.com/1837620622/wskill)** | **[Super-Agent-Skills](https://github.com/1837620622/Super-Agent-Skills)**

</div>