---
name: skills-helper
description: Skills 管理助手 — 创建、查看、更新项目级或全局 Skills，自动处理 git 提交与同步。
---

# Skills 管理助手

## 功能概述

本 Skill 提供 Skills 的完整管理能力，帮助用户高效创建和管理个人级（全局）或项目级 Skills，并自动处理相关的 git 版本控制操作。

---

## 一、Skills 基础概念

### 两种级别

| 级别 | 路径 | 可见范围 | 适用场景 |
|------|------|----------|----------|
| **全局 (Global)** | `~/.qwen/skills/` | 所有项目均可用 | 个人工作流、效率工具、在开发的 Skill |
| **项目级 (Project)** | `.qwen/skills/` | 仅当前项目 | 团队工作流规范、共享实用工具 |

### Skill 目录结构

```
my-skill/
├── SKILL.md          # 必须：Skill 定义文件
├── reference.md      # 可选：参考文档
├── examples.md       # 可选：使用示例
├── scripts/          # 可选：辅助脚本
│   └── helper.py
└── templates/        # 可选：模板文件
    └── template.txt
```

### SKILL.md 格式

```yaml
---
name: skill-name
description: 简短描述：说明这个 Skill 做什么、何时使用
---

# Skill Name

## Instructions
提供清晰的操作指导步骤。

## Examples
展示具体使用示例。
```

**字段要求**：
- `name`：非空字符串，支持 Unicode 字母、数字及 `_` `:` `.` `-`，禁止空格、斜杠、括号
- `description`：非空，需具体明确，避免模糊描述

### 可选：按路径限制 Skill（paths）

```yaml
---
name: tsx-helper
description: React TSX 组件辅助工具
paths:
  - 'src/**/*.tsx'
  - 'packages/*/src/**/*.tsx'
---
```

---

## 二、添加新 Skill

### 规则

1. **级别询问**：当用户请求添加 Skill 但未明确指定级别时，**必须先询问用户**：
   - "这是项目级 Skill（仅在当前项目可用，可提交 git）还是全局 Skill（所有项目可用）？"

2. **按需创建目录结构**：根据 Skill 需求创建可选的辅助目录。

### 执行流程

#### 项目级 Skill

```bash
mkdir -p .qwen/skills/<skill-name>
# 创建 SKILL.md 及相关文件
git add .qwen/skills/<skill-name>
```

#### 全局 Skill

```bash
mkdir -p ~/.qwen/skills/<skill-name>
# 创建 SKILL.md 及相关文件
```

### 全局 Skill 的 Git 同步

全局 Skills 存放在 `~/.qwen/skills/` 目录，通常已初始化为独立的 git 仓库。添加完成后，**必须**执行：

```bash
cd ~/.qwen/skills
git add <skill-name>/
git commit -m "feat(skills): 添加 <skill-name> Skill"
git push
```

### 如果是已成熟的skills
如果用户指定安装的目录下有 <skill-name>/SKILL.md 文件说明是一个成熟的skills
那么直接进行拷贝文件夹到 `~/.qwen/skills/` 然后参考 【四、更新全局】进行同步

---

## 三、查看 Skills

### 查看所有可用 Skills

```bash
ls ~/.qwen/skills/              # 全局 Skills
ls .qwen/skills/               # 项目 Skills（如果存在）
```

### 查看 Skill 内容

```bash
cat ~/.qwen/skills/<skill-name>/SKILL.md
cat .qwen/skills/<skill-name>/SKILL.md
```

---

## 四、更新全局 Skills（同步远程）

### 指令说明

提供指令 `/update-global-skills` 用于更新全局 Skills 目录，会在 `~/.qwen/skills/` 目录下执行 git pull。

### 执行流程

```bash
cd ~/.qwen/skills
git pull
```

---

## 五、更新和删除 Skills

### 更新 Skill

直接编辑 `~/.qwen/skills/<skill-name>/SKILL.md` 或 `.qwen/skills/<skill-name>/SKILL.md`，修改后重启 Qwen Code 生效。

### 删除 Skill

```bash
# 全局
rm -rf ~/.qwen/skills/<skill-name>

# 项目级
rm -rf .qwen/skills/<skill-name>
git commit -m "chore: 移除未使用的 <skill-name> Skill"
```

---

## 六、最佳实践

1. **保持 Skill 专注**：一个 Skill 只解决一项能力，如"PDF 表单填写"而非笼统的"文档处理"
2. **编写清晰的 description**：包含触发词和具体使用场景
3. **描述要具体明确**：
   - ❌ 模糊：`description: Helps with documents`
   - ✅ 明确：`description: 从 PDF 提取文本和表格、填写表单、合并文档`
4. **与团队测试**：验证激活时机、指令清晰度、示例完整性

---

## 七、调试提示

1. 检查路径是否正确：`~/.qwen/skills/` vs `.qwen/skills/`
2. 确认 YAML 语法正确：首行 `---`，结束行 `---`，不使用制表符
3. 全局 Skill 同步失败时，检查 git 状态：`cd ~/.qwen/skills && git status`