qwen-skills/skills-helper/SKILL.md

name, description

name	description
skills-helper	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 格式

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

# Skill Name

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

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

字段要求：

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

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

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

---

二、添加新 Skill

规则

1. 级别询问：当用户请求添加 Skill 但未明确指定级别时，必须先询问用户：

   • "这是项目级 Skill（仅在当前项目可用，可提交 git）还是全局 Skill（所有项目可用）？"

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

执行流程

项目级 Skill

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

全局 Skill

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

全局 Skill 的 Git 同步

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

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

如果是已成熟的skills

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

---

三、查看 Skills

查看所有可用 Skills

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

查看 Skill 内容

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

---

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

指令说明

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

执行流程

cd ~/.qwen/skills
git pull

---

五、更新和删除 Skills

更新 Skill

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

删除 Skill

# 全局
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