1. 为什么你的 Copilot 总是“不懂这个项目”用 VS Code 写代码的人大概率都经历过这种场面你问 Copilot“这个项目的用户鉴权逻辑在哪”它给你编一段看起来合理、实际项目里根本不存在的代码你让它按团队规范改一个函数它把命名风格、错误处理方式全带偏。问题不在模型本身而在于 Copilot 每次对话都是“失忆”的——它不知道你的目录约定、不知道你们用哪套日志库、不知道数据库调用必须带超时。Agent Skills 就是来解决这件事的。它是 VS Code 里 GitHub Copilot 原生支持的一套技能机制核心载体是一个叫SKILL.md的 Markdown 文件。你可以把它理解成给 AI 装上的“项目大脑”把项目里那些口口相传的规矩、踩过的坑、固定的代码模板写成 AI 能读懂的技能说明放在项目目录里。之后 Copilot 在补全、问答、改代码时会自动加载这些技能按你定义的规则来干活。它适合谁三类人最该用一是团队里负责定规范的人写一次 SKILL.md全组 Copilot 行为统一二是接手老项目的新人把项目结构、关键模块写成技能问 AI 等于问项目三是自己维护多个仓库的独立开发者每个项目一套技能切换项目时 AI 不会串味。这篇不聊虚的直接给你能复制的目录结构、字段模板、VS Code 侧启用步骤最后用 Copilot 跑一次项目问答验证。全程只需要 VS Code GitHub Copilot不用装额外插件。2. TaoToken 前置给 Copilot 备一条稳定的模型通道在动手写 SKILL.md 之前有个现实问题得先解决Copilot 的模型调用偶尔会抽风尤其是你想在技能里指定用某个模型做复杂推理时。这时候可以准备一个兼容 OpenAI 接口的模型服务作为补充通道TaoToken 就是干这个的。它的作用很直接提供一个统一的 API 入口你拿到 Key 之后可以在需要的地方比如自定义脚本、本地验证工具、或者某些支持自定义 Base URL 的 AI 工具调用模型。对于 Agent Skills 场景它的价值在于——当你想验证 SKILL.md 里定义的规则是否被正确理解时可以用它跑一个独立的模型请求做对照确认是技能文件的问题还是 Copilot 侧的问题。接入信息如下建议先存好官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 地址https://taotoken.net/api模型对话页https://taotoken.net/api/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewriteAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite操作路径很简单进 API Keys 页面创建一个 Key复制保存。然后在需要的地方填三件套——Base URL 填https://taotoken.net/apiKey 填你刚创建的Model ID 按文档里列出的可用模型填。这三样缺一不可后面排障章节会专门讲填错会报什么错。注意TaoToken 是模型调用通道不是编辑器替代品。你的代码编辑、Copilot 补全仍然在 VS Code 里完成它只负责在你需要独立验证模型行为时提供请求能力。如果你只是想让 Copilot 读 SKILL.md其实不接任何外部通道也能跑。但实测下来准备一条备用通道有个好处当 Copilot 对某个技能规则理解偏差时你可以用同样的 prompt 走 TaoToken 请求一次对比两边输出快速定位是技能描述写得不够明确还是 Copilot 侧的加载问题。这个对照方法后面验证章节会用到。3. 可复制配置SKILL.md 目录结构与字段模板Agent Skills 的加载逻辑是VS Code 里的 Copilot 会扫描项目中的特定目录找到SKILL.md文件后解析其中的规则在后续对话中作为上下文注入。目录位置和文件结构都有讲究填错一个字符就可能不生效。3.1 目录结构放在哪才会被识别推荐的项目根目录结构如下your-project/ ├── .github/ │ └── skills/ │ ├── project-context/ │ │ └── SKILL.md │ ├── api-conventions/ │ │ └── SKILL.md │ └── db-timeout-guard/ │ └── SKILL.md ├── src/ └── README.md关键点.github/skills/是 Copilot 默认扫描的技能根目录每个技能一个子文件夹文件夹名就是技能标识里面必须有一个SKILL.md。你可以放多个技能Copilot 会按需加载。文件夹名建议用英文小写加连字符别用中文或空格避免解析异常。3.2 SKILL.md 字段模板一个能被正确解析的 SKILL.md推荐用下面这个结构。我把它拆成 frontmatter 和正文两部分frontmatter 用 YAML 格式正文用 Markdown。--- name: project-context description: 项目整体结构与技术栈说明当用户询问项目架构、模块位置、依赖关系时使用 version: 1.0.0 --- # 项目上下文技能 ## 项目概览 这是一个基于 Go 的微服务项目包含三个核心服务 - user-service用户鉴权与资料管理 - order-service订单创建与状态流转 - gateway统一入口负责路由与限流 ## 目录约定 - internal/ 下放业务逻辑禁止跨服务直接引用 - pkg/ 下放可复用工具必须写单元测试 - cmd/ 下放各服务启动入口 ## 技术栈 - Web 框架Gin - 数据库PostgreSQL统一用 pgx 驱动 - 日志zap禁止使用 fmt.Println - 配置viper配置文件放 configs/ 目录 ## 回答规则 当用户询问某个功能在哪实现时 1. 先说明属于哪个服务 2. 给出具体文件路径 3. 如果涉及跨服务调用说明调用链路frontmatter 里name和description是必填的。description尤其重要它决定了 Copilot 在什么场景下会激活这个技能。写得太泛比如“项目说明”会导致技能被频繁误加载写得太窄又可能该用的时候不触发。建议用“当用户……时使用”的句式。3.3 一个带自动修复规则的技能示例下面这个技能专门管数据库调用超时是 excerpt 里那个思路的完整可复制版--- name: db-timeout-guard description: 检查数据库与 HTTP 调用是否带 context 超时当用户编写或修改 I/O 函数时使用 version: 1.0.0 --- # 数据库超时守卫 ## 问题 数据库和 HTTP 调用如果不设超时会导致 goroutine 泄漏、连接池耗尽。 ## 规则 任何执行 I/O 的函数必须 - 第一个参数接收 context.Context - 使用 context.WithTimeout 或从调用方继承 - 把 context 传递给下游调用 ## 修复模板 修改前 go func (s *Store) GetUser(id string) (*User, error) { return s.db.QueryRow(SELECT ..., id).Scan(user) }修改后func (s *Store) GetUser(ctx context.Context, id string) (*User, error) { if _, ok : ctx.Deadline(); !ok { var cancel context.CancelFunc ctx, cancel context.WithTimeout(ctx, 2*time.Second) defer cancel() } return s.db.QueryRowContext(ctx, SELECT ..., id).Scan(user) }动作当用户写数据库或 HTTP 函数但没带 context 时提示“缺少 context存在 goroutine 泄漏风险”提供自动补全 context 和超时的建议提醒更新所有调用方注意代码块嵌套的问题SKILL.md 本身是 Markdown里面再放代码块时外层用四个反引号包裹内层用三个反引号这样解析不会乱。上面模板里为了展示清晰做了简化你实际写的时候按这个嵌套规则来。 ### 3.4 VS Code 侧启用步骤 文件放好后在 VS Code 里确认几件事 第一确保 GitHub Copilot 和 Copilot Chat 扩展已安装并登录。在扩展面板搜 GitHub Copilot两个都装上。 第二打开你的项目文件夹不是单个文件Copilot 的技能扫描是基于工作区根目录的。如果你只打开了一个文件.github/skills/ 不会被识别。 第三在 Copilot Chat 面板里用 workspace 开头提问比如 workspace 这个项目的用户鉴权在哪个文件。workspace 会触发工作区上下文加载技能文件才会被纳入。 第四如果技能没生效按 CtrlShiftP 打开命令面板运行 Developer: Reload Window 重载窗口。技能文件是启动时扫描的新增后需要重载。 ## 4. 验证请求让 Copilot 调用技能完成一次项目问答 配置写完得验证它真的被加载了。下面是一套可复现的验证流程。 ### 4.1 准备一个可提问的项目 假设你的项目里有 internal/user/service.go内容如下 go package user type Service struct { db *Store } func (s *Service) GetUser(id string) (*User, error) { return s.db.GetUser(id) }这个函数故意没带 context正好用来测试db-timeout-guard技能。4.2 在 Copilot Chat 里提问打开 Copilot Chat输入workspace 检查 internal/user/service.go 里的 GetUser 函数有没有潜在问题如果技能加载成功Copilot 的回答应该包含类似内容GetUser函数调用了s.db.GetUser但没有接收context.Context参数也没有设置超时。根据项目的 db-timeout-guard 技能规则这存在 goroutine 泄漏风险。建议改为接收 ctx 并使用context.WithTimeout。如果它只是泛泛地说“建议加错误处理”完全没提 context 和超时说明技能没被加载。4.3 用 TaoToken 做对照验证当你不确定是技能文件写错了还是 Copilot 没加载时可以用 TaoToken 跑一次对照。把技能内容作为 system prompt把同样的问题作为 user message发一次请求curl https://taotoken.net/api/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的Key \ -d { model: 按文档填Model ID, messages: [ {role: system, content: 你是代码审查助手。规则任何数据库调用必须带 context.Context 和超时。}, {role: user, content: 检查这个函数func (s *Service) GetUser(id string) (*User, error) { return s.db.GetUser(id) }} ] }如果这个请求能正确指出 context 缺失而 Copilot 不能那问题就在 Copilot 侧的技能加载而不是你的规则描述。反过来如果两边都指不出来说明 SKILL.md 里的规则写得太模糊需要加强description和正文的明确性。4.4 成功结果长什么样技能生效后你会观察到三个变化一是 Copilot 回答里开始出现你项目里的真实路径和模块名二是它改代码时会主动套用你定义的模板三是当你写出违反规则的代码时它会在补全建议里带出警告。实测下来一个描述清晰的技能从提问到命中规则响应里通常能直接引用技能名或规则原文。5. 本篇常见错排查401、技能不加载、OAuth 报错配置过程中最容易卡在几个固定报错上逐个说清楚。5.1 401 Unauthorized这个报错出现在你用 TaoToken 做对照验证时。原因通常是三件套没填全或填错Base URL 写成了https://taotoken.net漏了/apiKey 复制时带了空格或者用了已删除的 KeyModel ID 填了一个文档里不存在的名字排查顺序先确认 Base URL 是https://taotoken.net/api再进 API Keys 页面确认 Key 状态是启用最后对照接入文档里的模型列表核对 Model ID。三个都对还报 401就重新创建一个 Key 试。5.2 local proxy failed这个报错一般出现在 VS Code 侧Copilot 尝试走本地代理但连不上。先检查 VS Code 的代理设置http.proxy如果你没配代理把它清空。然后确认网络能正常访问 GitHub。这个报错和 SKILL.md 无关是环境层面的。5.3 reading choices 相关报错当你在自定义脚本里解析模型返回时如果报cannot read property choices of undefined说明返回体不是预期的 OpenAI 格式。常见原因是请求发到了错误的 endpoint或者 Key 没有该模型的权限。先打印完整返回体看结构再对照文档确认 endpoint 和模型权限。5.4 OAuth 报错Copilot 登录态失效时会报 OAuth 相关错误。在 VS Code 里点左下角账户图标退出后重新登录 GitHub。如果公司网络对 GitHub 登录有限制换一个网络环境重试。这个和技能配置无关但会直接导致 Copilot 完全不工作所以放在排查清单里。5.5 技能写了但不生效这是最高频的问题按顺序查第一目录是不是.github/skills/技能名/SKILL.md少一层都不行。第二frontmatter 的---是不是在文件第一行前面不能有空行。第三name和description有没有拼写错误。第四有没有重载 VS Code 窗口。第五提问时有没有用workspace。这五步走完九成的不生效问题都能解决。6. 把项目经验固化成技能才是 Agent Skills 的真正价值SKILL.md 最实用的地方不是让 Copilot 变聪明而是让它的行为可预测。你写一次规则团队里每个人、每次对话AI 都按同一套标准来。新同事入职不用再口头讲“我们数据库调用必须带超时”技能文件就是活的规范文档。如果你想让 Copilot 在长期编码任务里更稳定可以考虑用 Coding Plan 把常用技能和模型调用组合起来https://taotoken.net/api/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite需要管理多个项目的 Key 时API Keys 页面支持创建多个https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite技能文件写完后建议提交到 Git。这样每次拉取代码Copilot 的行为规范也跟着同步不会因为换台机器就失效。我自己的习惯是每修完一个线上问题就把根因和修复模板补进对应的 SKILL.md下次同类问题 AI 直接拦下来。