skills指南

GitHub Copilot Skills 开发指南

本指南介绍如何为 GitHub Copilot 创建、开发和使用 Skills。

目录

快速开始

5 分钟快速上手

  1. 初始化新项目

    1
    打开 VS Code → 打开 GitHub Copilot Chat → 输入 /init

  2. 查看可用的 Skills

    1
    在 Copilot Chat 中输入 /skills

  3. 获取 skill-creator

    1
    2
    从 https://github.com/anthropics/skills/tree/main/skills/skill-creator
    下载到 .github/skills/skill-creator/

  4. 开始使用

    1
    在 Chat 中说 "帮我创建一个新的 skill"

项目初始化

使用 /init 命令

对于一个新项目，首先需要初始化 GitHub Copilot 配置：

  1. 打开 VS Code

  2. 打开 GitHub Copilot Chat

    • 快捷键：Ctrl + Alt + I（Windows/Linux）
    • 或点击侧边栏的 Copilot 图标

  3. 初始化项目

    在 Chat 中输入：

    1
    /init

  4. 结果

    这会在项目根目录创建 .github/copilot-instructions.md 文件，包含：

    • 项目级别的 Copilot 指令
    • 代码风格指南
    • 架构说明
    • 开发规范

初始化后的项目结构

1
2
3
4
5
6
你的项目/
├── .github/
│   ├── copilot-instructions.md     # 项目级别的 Copilot 指令（自动生成）
│   └── skills/                      # Skills 目录（需要手动创建）
├── src/                             # 你的源代码
└── [其他项目文件]

注意： .github/skills/ 目录需要手动创建，用于存放 skills。

获取通用 Skills

从 GitHub 获取

GitHub 提供了一些通用的 skills，可以直接使用：

官方 Skills 仓库：

1
https://github.com/anthropics/skills/tree/main/skills

推荐的通用 Skills

1. skill-creator

功能： 帮助你创建新的 skills

获取方式：

  1. 访问：https://github.com/anthropics/skills/tree/main/skills/skill-creator

  2. 下载整个 skill-creator 目录

  3. 放到你的项目中：

    1
    你的项目/.github/skills/skill-creator/

使用：

1
在 Copilot Chat 中说："帮我创建一个新的 skill"

2. 其他通用 Skills

浏览 https://github.com/anthropics/skills/tree/main/skills 查看更多：

  • 代码审查相关
  • 文档生成相关
  • 测试辅助相关
  • 等等

安装 Skills

将下载的 skill 目录复制到：

1
.github/skills/<skill-name>/

目录结构示例：

1
2
3
4
5
6
7
8
.github/skills/
├── skill-creator/           # 从 GitHub 获取
│   └── SKILL.md
├── attachment-saver/        # 你自己创建的
│   ├── SKILL.md
│   └── scripts/
└── your-custom-skill/       # 你的自定义 skill
    └── SKILL.md

查看和管理 Skills

/skills 命令

使用 /skills 命令查看和管理当前项目中的所有 skills。

在 Copilot Chat 中输入：

1
/skills

显示内容：

  • 所有已安装的 skills 列表
  • 每个 skill 的名称和描述
  • 可用的操作：重命名（Rename）、复制（Copy）、删除（Delete）

管理 Skills

查看位置：

所有 skills 都存放在：

1
.github/skills/

添加新 Skill：

  1. 创建新目录：.github/skills/your-skill-name/
  2. 添加 SKILL.md 文件
  3. GitHub Copilot 会自动检测并加载

重命名 Skill：

通过 /skills 命令界面：

  1. 输入 /skills
  2. 找到要重命名的 skill
  3. 点击 Rename 选项

或手动重命名目录：

1
Rename-Item .github\skills\old-name .github\skills\new-name

复制 Skill：

通过 /skills 命令界面：

  1. 输入 /skills
  2. 找到要复制的 skill
  3. 点击 Copy 选项

或手动复制目录：

1
Copy-Item -Recurse .github\skills\source-skill .github\skills\new-skill

删除 Skill：

通过 /skills 命令界面：

  1. 输入 /skills
  2. 找到要删除的 skill
  3. 点击 Delete 选项

或手动删除目录：

1
Remove-Item -Recurse .github\skills\your-skill-name

临时禁用 Skill：

如果想临时禁用但不删除，可以重命名目录（添加 .disabled 后缀）：

1
Rename-Item .github\skills\my-skill .github\skills\my-skill.disabled

创建新的 Skill

方法 1: 使用 skill-creator（推荐）

如果你已经安装了 skill-creator，可以直接在 Copilot Chat 中请求帮助：

示例对话：

1
2
3
4
5
6
你: "帮我创建一个新的 skill 叫 api-helper，用于调用外部 API"

Copilot: 会引导你完成：
  1. 创建目录结构
  2. 生成 SKILL.md 模板
  3. 添加必要的脚本

方法 2: 手动创建

步骤 1: 规划你的 Skill

在创建之前，明确回答以下问题：

  1. Skill 的目的是什么？

    • 例如：”保存 ALM 附件到本地文件”

  2. 何时触发此 Skill？

    • 例如：”用户说’下载附件 AT123456’”

  3. 需要什么资源？

    • Scripts: 需要执行的脚本（Python、PowerShell 等）
    • References: 参考文档、API 说明等
    • Assets: 模板文件、图片等

步骤 2: 创建目录结构

1
2
3
4
5
6
7
8
# 创建 skill 目录
New-Item -ItemType Directory -Path .github\skills\my-helper

# 创建 SKILL.md
New-Item -ItemType File -Path .github\skills\my-helper\SKILL.md

# （可选）创建 scripts 目录
New-Item -ItemType Directory -Path .github\skills\my-helper\scripts

命名规范：

  • 使用 kebab-case（小写字母和连字符）
  • 例如：attachment-saver, code-reviewer, api-helper
  • 简短且描述性

步骤 3: 基础结构

1
2
3
4
5
6
7
8
.github/skills/my-helper/
├── SKILL.md                    # Skill 的主文档（必需）
├── scripts/                    # 可执行脚本（可选）
│   └── helper.py
├── references/                 # 参考文档（可选）
│   └── api-docs.md
└── assets/                     # 资源文件（可选）
    └── template.json

开发 Skill

编写 SKILL.md

SKILL.md 是最重要的文件，包含两部分：

1. YAML Frontmatter（必需）

1
2
3
4
---
name: my-helper
description: 详细描述 skill 的功能和使用场景。包括何时使用此 skill，例如："当用户需要 XXX 时使用"
---

重要提示：

  • description 是触发 skill 的关键！要详细描述使用场景
  • 必须包含”何时使用”的信息
  • 只有 name 和 description 会被 Claude 读取用于判断是否触发

2. Markdown 正文（必需）

推荐的章节结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# Skill Name

简短介绍这个 skill 的作用。

## Quick Start

最简单的使用示例，让用户快速上手。

## Workflow

详细的工作流程，分步骤说明。

## Script Reference

如果有脚本，说明如何使用。

## Common Patterns

常见的使用模式和示例。

## Error Handling

错误处理说明。

编写指南：

  • 使用祈使句/不定式（例如：”Call the tool”, “Save the file”）
  • 提供具体的代码示例
  • 保持简洁，避免冗余
  • 不要重复 Claude 已经知道的通用知识

创建脚本（可选）

如果需要可执行脚本：

  1. 在 scripts/ 目录下创建脚本
  2. 确保脚本有清晰的注释和帮助信息
  3. 添加错误处理
  4. 提供使用示例

Python 脚本示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
#!/usr/bin/env python3
"""
脚本说明

Usage:
    python script.py <arg1> <arg2>

Examples:
    python script.py "input" "output"
"""

import sys

def main():
    if len(sys.argv) < 3:
        print("Usage: script.py <arg1> <arg2>")
        sys.exit(1)
    
    arg1 = sys.argv[1]
    arg2 = sys.argv[2]
    
    # 你的逻辑
    print(f"Processing {arg1} -> {arg2}")

if __name__ == "__main__":
    main()

添加参考文档（可选）

对于复杂的 API 或详细文档，可以创建 references/ 目录：

1
2
3
4
.github/skills/my-helper/references/
├── api-reference.md
├── data-schema.md
└── troubleshooting.md

在 SKILL.md 中引用这些文档：

1
For detailed API information, see [API Reference](references/api-reference.md).

测试 Skill

1. 验证 SKILL.md 格式

确保：

  • YAML frontmatter 格式正确
  • 包含必需的 name 和 description 字段
  • Markdown 格式正确
  • 代码示例可以运行

2. 测试脚本功能

如果你的 skill 包含脚本，先独立测试：

1
2
3
4
5
# 测试 Python 脚本
python .github\skills\my-helper\scripts\my_script.py <test-args>

# 测试 PowerShell 脚本
.\.github\skills\my-helper\scripts\my_script.ps1 <test-args>

创建测试脚本：

1
2
3
4
5
6
7
8
9
10
# test_my_skill.py
import sys
sys.path.insert(0, r'.github\skills\my-helper\scripts')

from my_script import my_function

# 测试
result = my_function("test input")
assert result == "expected output"
print("✅ Test passed!")

3. 在 Copilot Chat 中测试

  1. 检查 Skill 是否被识别

    1
    2
    在 Chat 中输入 /skills
    应该能看到你的新 skill

  2. 触发 Skill

    使用 description 中描述的场景：

    1
    2
    例如：如果 description 说 "用于下载附件"
    则说："帮我下载附件 AT123456"

  3. 验证输出

    • 检查 Copilot 是否正确理解 skill
    • 验证脚本是否正确执行
    • 确认输出符合预期

4. 调试

启用详细输出：

1
在 Copilot Chat 中说："用详细模式执行"

查看执行日志：

  • 检查终端输出
  • 查看脚本的错误信息
  • 验证文件是否正确创建

分享 Skill

方法 1: 通过 Git 仓库

推荐将 skills 提交到 Git 仓库：

1
2
3
4
# 添加到版本控制
git add .github/skills/my-helper
git commit -m "Add my-helper skill"
git push

其他用户使用：

1
2
3
4
# 克隆仓库后，skill 自动可用
git clone <your-repo>
cd <your-repo>
# 打开 VS Code，skills 会自动加载

方法 2: 直接分享目录

将整个 skill 目录打包分享：

1
2
# 创建压缩包
Compress-Archive -Path .github\skills\my-helper -DestinationPath my-helper-skill.zip

其他用户使用：

1
2
# 解压到 .github/skills/ 目录
Expand-Archive -Path my-helper-skill.zip -DestinationPath .github\skills\

方法 3: 发布到 GitHub

  1. 创建专门的 skills 仓库
  2. 按照 Anthropic 的格式组织
  3. 其他用户可以从你的仓库获取

示例仓库结构：

1
2
3
4
5
6
7
your-skills-repo/
├── README.md
└── skills/
    ├── skill-1/
    │   └── SKILL.md
    └── skill-2/
        └── SKILL.md

最佳实践

1. Skill 设计原则

保持简洁：

  • 只包含 Claude 不知道的信息
  • 避免重复通用知识
  • 使用简洁的语言

明确触发条件：

  • 在 description 中清晰描述使用场景
  • 包含关键词和示例
  • 说明”何时使用”

提供具体示例：

  • 包含实际的代码示例
  • 展示常见使用模式
  • 提供错误处理示例

2. 文件组织

SKILL.md（必需）：

  • Skill 的主文档
  • 包含 YAML frontmatter
  • 包含使用说明和示例

Scripts（可选）：

  • 用于需要确定性执行的操作
  • 避免重复编写相同代码
  • 示例：PDF 处理、文件转换、数据解析

References（可选）：

  • 用于详细文档和参考
  • API 文档、数据库 schema
  • 只在需要时加载

Assets（可选）：

  • 用于输出的模板文件
  • 图片、字体等静态资源
  • 不会加载到上下文中

3. 避免的错误

❌ 不要：

  • 在 SKILL.md 中重复基础知识
  • 创建额外的 README.md 等文档
  • 在 skill 正文中说明”何时使用”（应该在 description 中）
  • 深度嵌套的 reference 文件
  • 创建 .skill 打包文件（直接使用目录即可）

✅ 应该：

  • 保持 SKILL.md 精简（< 500 行）
  • 将详细内容分离到 references
  • 提供可执行的代码示例
  • 使用渐进式披露（progressive disclosure）
  • 将 skills 直接放在 .github/skills/ 目录

4. 版本管理

推荐做法：

1
2
3
4
.github/skills/my-helper/  ← 使用 Git 管理
├── SKILL.md
└── scripts/
    └── helper.py

提交到 Git：

1
2
3
git add .github/skills/my-helper
git commit -m "Add my-helper skill"
git push

建议：

  • 在 Git 中管理源代码
  • 使用分支开发新功能
  • 添加 commit message 说明变更

5. 团队协作

共享 Skills：

  • 将 .github/skills/ 提交到团队仓库
  • 团队成员克隆后自动获得所有 skills
  • 使用 /skills 查看可用 skills

命名约定：

  • 使用描述性的名称
  • 团队内保持一致的命名风格
  • 避免名称冲突

完整示例：attachment-saver

查看实际例子：.github/skills/attachment-saver/

结构：

1
2
3
4
attachment-saver/
├── SKILL.md                          # 主文档
└── scripts/
    └── save_from_mcp_response.py     # 保存附件的脚本

SKILL.md 示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
---
name: attachment-saver
description: Save attachments from ALM by calling get_attachment_tool and converting base64 response to files. Use when users want to download, save, or retrieve attachments from ALM using attachment IDs (e.g., "download attachment AT867010", "save this attachment", "get the file for AT123456").
---

# Attachment Saver Skill

Save ALM attachments to local files.

## Quick Start

User: "Download attachment AT867010"

1. Call `get_attachment_tool` with the attachment ID
2. Run the save script to convert and save the file
3. Confirm the file was saved

## Workflow

1. Extract attachment ID from user request
2. Call the MCP tool to get base64 data
3. Use the script to decode and save
4. Report the saved file path to user

## Script Reference

```bash
python .github/skills/attachment-saver/scripts/save_from_mcp_response.py <json-response> <output-dir>
1
2

**使用场景：**

用户: “下载附件 AT867050”

Copilot 执行:

  1. 识别 attachment-saver skill
  2. 调用 get_attachment_tool
  3. 运行 save_from_mcp_response.py
  4. 保存文件到 attachments/
  5. 告知用户文件位置
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31

    ---

    ## 故障排除

    ### Skill 未被识别

    **问题：** 输入 `/skills` 看不到你的 skill

    **解决：**
    1. 检查目录位置是否正确：`.github/skills/<skill-name>/`
    2. 确认 `SKILL.md` 文件存在
    3. 检查 YAML frontmatter 格式
    4. 重启 VS Code

    ### Skill 未触发

    **问题：** Copilot 没有使用你的 skill

    **检查：**
    1. `description` 是否清晰描述使用场景
    2. 用户请求是否与 description 匹配
    3. Description 中包含关键触发词

    **改进 description：**
    ```yaml
    # ❌ 不够具体
    description: Helper for API calls

    # ✅ 清晰的触发条件
    description: Use when users want to call external APIs, make HTTP requests, or fetch data from web services. Triggered by phrases like "call the API", "fetch from URL", "make HTTP request".

脚本执行错误

调试步骤：

  1. 单独运行脚本测试

    1
    python .github\skills\my-helper\scripts\script.py <args>

  2. 检查参数传递是否正确

  3. 查看错误日志

  4. 验证文件路径（使用绝对路径）

YAML 格式错误

常见问题：

1
2
3
4
5
6
7
8
9
10
# ❌ 缺少必需字段
---
name: my-skill
---

# ✅ 包含所有必需字段
---
name: my-skill
description: Detailed description of when to use this skill
---

验证 YAML：

  • 确保有开始和结束的 ---
  • name 和 description 是必需的
  • 注意缩进和语法

快速参考

常用命令

初始化项目：

1
在 Copilot Chat 中输入: /init

查看已安装的 Skills：

1
在 Copilot Chat 中输入: /skills

创建新 Skill 目录：

1
2
New-Item -ItemType Directory -Path .github\skills\my-skill
New-Item -ItemType File -Path .github\skills\my-skill\SKILL.md

删除 Skill：

1
Remove-Item -Recurse .github\skills\my-skill

目录结构速查

1
2
3
4
5
6
7
8
9
10
项目根目录/
├── .github/
│   ├── copilot-instructions.md  # 使用 /init 创建
│   └── skills/                   # Skills 目录
│       ├── skill-creator/        # 从 GitHub 获取
│       └── my-skill/             # 你创建的
│           ├── SKILL.md          # 必需
│           └── scripts/          # 可选
├── src/                          # 你的源代码
└── [其他项目文件]

必需的 YAML Frontmatter

1
2
3
4
---
name: skill-name
description: 详细描述功能和使用场景，包括何时触发此 skill。例如："Use when users want to XXX. Triggered by phrases like 'YYY', 'ZZZ'."
---

获取通用 Skills

官方仓库：

1
https://github.com/anthropics/skills/tree/main/skills

推荐 Skills：

  • skill-creator - 帮助创建新 skills
  • 浏览官方仓库查看更多

工作流程

  1. 初始化项目

    1
    /init 命令创建 copilot-instructions.md

  2. 获取 skill-creator

    1
    从 GitHub 下载到 .github/skills/skill-creator/

  3. 创建新 Skill

    1
    在 Chat 中说："帮我创建一个新的 skill"

  4. 开发和测试

    1
    编辑 SKILL.md，添加脚本，使用 /skills 验证

  5. 分享

    1
    提交到 Git 或打包整个目录

相关资源

总结

创建 Skill 的正确流程：

  1. 初始化项目 → 使用 /init 创建 copilot-instructions.md
  2. 获取 skill-creator → 从 GitHub 下载到 .github/skills/
  3. 查看现有 skills → 使用 /skills 命令
  4. 创建新 skill → 在 .github/skills/ 下创建目录和 SKILL.md
  5. 开发和测试 → 编写文档和脚本，在 Chat 中测试
  6. 分享 → 通过 Git 或直接分享目录

记住：

  • 使用 /init 初始化项目
  • 使用 /skills 查看和管理 skills
  • Skills 直接放在 .github/skills/ 目录
  • 从 https://github.com/anthropics/skills 获取通用 skills
  • 保持 SKILL.md 简洁，提供清晰的使用示例

祝你开发出优秀的 Skills！🎉

工作
#AI
skills指南
https://liu-cj25.github.io/2026/03/04/skills使用guide/
Author
cj
Posted on
March 4, 2026
Licensed under