如何在Visual Studio Code中开发一个skill并使用

前言

Skill 是 AI 助手（如 GitHub Copilot、Claude Code）的核心扩展机制。它通过标准化的文件结构，将复杂的任务流程、领域知识和执行规范封装成可复用的模块。本教程将指导你如何在 VS Code 中创建包含脚本执行能力的进阶 Skill。

一、核心概念与结构

1.1 什么是 Skill？

Skill 是一个包含 SKILL.md 文件的目录。当用户触发特定意图时，AI 会读取该文件中的指令，并可能调用目录下的脚本或参考文档来完成任务。

1.2 标准目录结构

text
.github/skills/
└── my-advanced-skill/
    ├── SKILL.md          # 核心指令文件
    ├── scripts/          # 存放可执行脚本
    │   └── analyze.py
    └── references/       # 存放参考知识
        └── api-spec.md

二、实战：创建带脚本执行的 Skill

我们将创建一个名为 data-analyzer 的 Skill，用于分析 CSV 数据。当用户请求分析数据时，AI 不仅提供建议，还会调用 Python 脚本生成统计报告。

第一步：创建目录

在项目根目录下创建 .github/skills/data-analyzer/ 和 .github/skills/data-analyzer/scripts/。

第二步：编写 Python 脚本

在 scripts/ 目录下创建 analyze.py。这个脚本负责实际的数据处理逻辑。

import sys
import json
import csv
from collections import Counter

def analyze_csv(file_path):
    """
    简单分析CSV文件，返回列名和基本统计信息
    """
    try:
        with open(file_path, 'r', encoding='utf-8') as f:
            reader = csv.DictReader(f)
            headers = reader.fieldnames
            if not headers:
                return {"error": "Empty CSV or no headers"}
        
            # 简单统计：每列非空值的数量
            stats = {header: 0 for header in headers}
            row_count = 0
            for row in reader:
                row_count += 1
                for header in headers:
                    if row[header] and row[header].strip():
                        stats[header] += 1
        
            return {
                "file": file_path,
                "rows": row_count,
                "columns": headers,
                "non_null_counts": stats
            }
    except Exception as e:
        return {"error": str(e)}

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print(json.dumps({"error": "No file path provided"}))
        sys.exit(1)
  
    file_path = sys.argv[1]
    result = analyze_csv(file_path)
    print(json.dumps(result, indent=2))

第三步：编写 SKILL.md

在 data-analyzer/ 目录下创建 SKILL.md。关键在于 instructing AI 如何调用上述脚本。

markdown
---
name: data-analyzer
description: 分析 CSV 数据文件。当用户上传 CSV 文件或请求分析数据时触发。
---

# 数据分析 Skill

此 Skill 用于对 CSV 格式的数据进行快速统计分析。

## 执行流程

1. ‌**确认文件路径**‌
   - 如果用户提供了文件内容，先将其保存为临时 `.csv` 文件。
   - 记录该文件的绝对路径。

2. ‌**调用分析脚本**‌
   - 使用终端命令执行 `scripts/analyze.py`。
   - 命令格式：`python .github/skills/data-analyzer/scripts/analyze.py <文件路径>`
   - 确保当前工作目录正确，以便找到脚本。

3. ‌**解读结果**‌
   - 读取脚本输出的 JSON 结果。
   - 用自然语言向用户总结数据概况：
     - 总行数
     - 包含的列
     - 各列的数据完整性（非空值比例）

4. ‌**提供建议**‌
   - 根据统计结果，建议下一步的分析方向（如：哪些列缺失值较多，哪些列适合做分类分析）。

## 注意事项
- 如果脚本执行失败，请检查 Python 环境是否安装，并告知用户错误信息。
- 不要直接尝试在对话中解析大型 CSV 文件，务必使用脚本处理以保证效率。

三、如何使用与测试

‌准备测试数据‌：在项目根目录创建一个简单的 test.csv。
‌触发 Skill‌：在 VS Code 的 AI 聊天窗口中输入：“请分析 test.csv 文件”。
‌观察行为‌：
- AI 应识别到 data-analyzer Skill。
- AI 会生成并执行终端命令 python .github/skills/data-analyzer/scripts/analyze.py test.csv。
- AI 读取输出并为你生成分析报告。

四、进阶优化技巧

4.1 错误处理与鲁棒性

在 SKILL.md 中明确指示 AI 如何处理脚本执行失败的情况。例如：“如果返回 JSON 中包含 error 字段，请直接向用户展示错误原因，并建议检查文件路径或格式。”

4.2 动态参数传递

如果脚本需要更多参数（如指定分析列），可以在 SKILL.md 中定义参数提取规则：“从用户指令中提取 --columns 参数，并追加到 python 命令后。”

4.3 多语言支持

如果你的团队主要使用 Node.js，可以将 analyze.py 替换为 analyze.js，并在 SKILL.md 中修改执行命令为 node scripts/analyze.js。Skill 的核心在于指令，而非特定语言。

五、常见问题

‌**Q: 脚本执行权限问题怎么办？**‌ A: 确保脚本文件有执行权限（Linux/Mac 下使用 chmod +x），或在 SKILL.md 中指示 AI 使用解释器显式调用（如 python script.py 而非 ./script.py）。

‌**Q: 如何调试 Skill？**‌ A: 先在终端手动运行脚本，确保其独立工作正常。然后在 VS Code 中打开 AI 聊天窗口的“开发者模式”或查看日志，确认 AI 是否正确构建了命令。

‌**Q: Skill 会被自动发现吗？**‌ A: 是的，只要文件夹位于标准的 .github/skills/ 路径下，且包含合法的 SKILL.md，大多数支持该功能的 AI 插件会在启动时自动索引。