182 lines
4.4 KiB
Markdown
182 lines
4.4 KiB
Markdown
---
|
||
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`
|