VS Code 创建与使用 Skill 完整实操教程（基于 TraeCode 插件 + 本地 roll-dice 项目）

本文基于本地真实项目环境编写，项目路径：D:\wwwroot\skillsdemo\skills-demo-runoops\.agents\skills\roll-dice。全程使用 TraeCode 插件 实现 Skill 加载、识别与运行，不依赖、不使用 GitHub Copilot。

文章以经典入门案例 roll-dice 掷骰子技能 为核心，手把手讲解 VS Code 下 Skill 的目录规范、创建方法、文件编写、插件加载、测试调试与运行原理，是零基础上手 AI 智能体 Skill 开发的标准实操教程。

一、本地环境与工具说明

本次实操所有环境均为本地真实环境，参数固定、可复现：

编辑器：VS Code 最新稳定版
AI 插件：TraeCode Plugin（唯一技能运行插件）
项目根目录：D:\wwwroot\skillsdemo\skills-demo-runoops
Skill 完整路径：D:\wwwroot\skillsdemo\skills-demo-runoops\.agents\skills\roll-dice
案例技能：roll-dice 掷骰子技能（终端生成真实随机点数）

TraeCode 插件安装与启用

1. 打开 VS Code 扩展市场，搜索 TRAE，安装 TraeCode Plugin；

2. 安装完成后重启 VS Code，登录账号；

3. 使用快捷键 Ctrl+U 唤起 TraeCode 对话面板，开启智能体能力。

二、Skill 官方强制目录规范（TraeCode 专用）

TraeCode 插件只会固定扫描项目内 .agents/skills 目录，不在该路径的技能无法自动识别与触发。

你的项目标准合法目录结构：

skills-demo-runoops/
└── .agents
    └── skills
        └── roll-dice          # 技能文件夹名
            └── SKILL.md        # 唯一核心文件

两条硬性规范（必须遵守）

1. 文件夹名称必须和 SKILL.md 头部 name 字段完全一致；

2. 核心文件名固定为大写 SKILL.md，不可小写、不可改名。

三、VS Code 手动创建 Skill 完整流程

步骤 1：打开本地项目工作区

VS Code → 文件 → 打开文件夹，选择本地根目录：

D:\wwwroot\skillsdemo\skills-demo-runoops

步骤 2：逐级创建标准目录

在项目根目录依次新建文件夹：

1. 新建隐藏目录 .agents

2. 在 .agents 内新建 skills

3. 在 skills 内新建技能目录 roll-dice

步骤 3：创建核心文件 SKILL.md

在 roll-dice 目录下新建文件 SKILL.md，粘贴以下可直接运行的标准代码，适配 TraeCode 插件规范：

---
name: roll-dice
description: 掷骰子技能，用户询问掷骰子、roll d6、roll d20、随机点数、2d6 场景自动触发。调用本地终端生成真实随机数，不使用模型脑补数据。
version: 1.0.0
author: runoops-demo
disable-model-invocation: true
掷骰子技能 roll-dice
任务目标
接收用户骰子指令，调用本地终端生成真实随机点数，支持单骰子、多骰子组合投掷，自动计算总和，输出标准化结果。
触发场景
用户输入包含以下内容，TraeCode 自动启用本技能：

掷骰子、生成随机点数
roll d6、roll d20
2d6、3d6、多骰子投掷

执行规则

默认规则：1d6（一颗6面骰子）
自动识别用户自定义骰子数量与面数
优先调用本地终端命令生成随机数
多骰子场景自动累加总点数

终端执行命令
Windows PowerShell：
Get-Random -Minimum 1 -Maximum <sides>
Linux / Mac Bash：
echo $((RANDOM % <sides> + 1))
输出规范

明确展示骰子规则、单颗点数、总点数
输出简洁干净，无多余解释
标准示例：掷骰子 2d6 → 点数：2、6，总和：8

四、SKILL.md 文件结构详解（TraeCode 适配版）

1. 头部 YAML 元信息（触发核心）

name：技能唯一标识，严格匹配文件夹名称，TraeCode 依靠此字段注册技能；
description：技能触发关键词，TraeCode 智能体通过该字段判断是否加载并执行当前技能；
disable-model-invocation：关闭模型自由回答，强制按技能规则执行，杜绝胡乱输出。

2. 正文规则（执行核心）

包含任务目标、触发场景、终端命令、输出规范，TraeCode 成功匹配技能后，会完整读取全文并严格按步骤执行。

五、TraeCode 插件加载与验证 Skill

1. 唤起 TraeCode 对话面板

使用快捷键 Ctrl+U 打开侧边 AI 面板，确保插件正常就绪。

2. 查看已加载技能列表

在对话框输入技能查询指令：

/skills

若列表中出现 roll-dice，代表技能目录识别成功、加载生效。

加载失败排查（本地项目高频问题）

目录错误：必须放在 .agents/skills/ 下级目录；
命名不匹配：文件夹名与 name 字段不一致；
文件错误：文件名非大写 SKILL.md；
未保存文件：修改后未 Ctrl+S，TraeCode 无法读取最新规则。

六、本地项目实战测试

在 TraeCode 对话框输入任意测试指令，验证技能自动触发：

基础测试：帮我掷一个 d20 骰子
进阶测试：掷 2d6 骰子
精准触发：@roll-dice 1d6

标准正确运行效果

TraeCode 不会直接文字回答，而是完整执行技能流程：

匹配用户指令关键词，激活 roll-dice 技能；
申请终端执行权限；
调用 PowerShell 随机数命令生成真实点数；
按规范格式输出单颗点数与总和。

七、TraeCode Skill 核心运行原理（渐进式加载）

TraeCode 插件采用渐进式披露加载机制，高效节省上下文 Token，这是 Skill 优于普通 Prompt 的核心优势：

发现阶段：会话启动，仅扫描所有技能的 name 和 description，轻量化预加载；
匹配阶段：用户提问命中关键词，精准匹配 roll-dice；
激活阶段：按需加载完整 SKILL.md 全部规则；
执行阶段：调用终端、执行命令、标准化输出结果。

八、本地项目迭代与维护

你的本地 skills-demo-runoops 项目支持长期迭代：

修改 SKILL.md 规则后保存，重新输入/skills 即可刷新生效；
可按需扩展 examples、templates、scripts 目录，升级为完整企业级技能；
支持 Git 版本管理，可存档、回滚、复用、团队共享。

九、教程总结

本次基于本地 roll-dice 真实项目，依托 TraeCode 插件，完整掌握了 VS Code 创建和使用 Skill 的标准流程：

规范建目录 → 编写标准 SKILL.md → TraeCode 识别加载 → 终端实战测试 → 迭代维护

该流程是所有 AI 智能体 Skill 开发的通用标准，掌握后可自主开发文档处理、自动化任务、数据统计等各类自定义技能。

极简运行流程图（适配本地 TraeCode 环境）

用户骰子指令 → TraeCode 扫描 .agents/skills 目录 → 匹配 roll-dice 技能 → 加载完整 SKILL.md 规则 → 执行终端随机数命令 → 输出标准化真实点数