企业官网建设流程全解析

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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
• API 地址：https://taotoken.net/api
• 模型对话页：https://taotoken.net/api/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat&utm_campaign=rewrite
• API Keys 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite
• 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite

操作路径很简单：进 API Keys 页面创建一个 Key，复制保存。然后在需要的地方填三件套——Base URL 填https://taotoken.net/api，Key 填你刚创建的，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 时：

1. 提示“缺少 context，存在 goroutine 泄漏风险”
2. 提供自动补全 context 和超时的建议
3. 提醒更新所有调用方

注意代码块嵌套的问题：SKILL.md 本身是 Markdown，里面再放代码块时，外层用四个反引号包裹，内层用三个反引号，这样解析不会乱。上面模板里为了展示清晰做了简化，你实际写的时候按这个嵌套规则来。 ### 3.4 VS Code 侧启用步骤 文件放好后，在 VS Code 里确认几件事： 第一，确保 GitHub Copilot 和 Copilot Chat 扩展已安装并登录。在扩展面板搜 `GitHub Copilot`，两个都装上。 第二，打开你的项目文件夹（不是单个文件），Copilot 的技能扫描是基于工作区根目录的。如果你只打开了一个文件，`.github/skills/` 不会被识别。 第三，在 Copilot Chat 面板里，用 `@workspace` 开头提问，比如 `@workspace 这个项目的用户鉴权在哪个文件`。`@workspace` 会触发工作区上下文加载，技能文件才会被纳入。 第四，如果技能没生效，按 `Ctrl+Shift+P` 打开命令面板，运行 `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，漏了/api
• Key 复制时带了空格，或者用了已删除的 Key
• Model 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_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite

需要管理多个项目的 Key 时，API Keys 页面支持创建多个：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite

技能文件写完后，建议提交到 Git。这样每次拉取代码，Copilot 的行为规范也跟着同步，不会因为换台机器就失效。我自己的习惯是，每修完一个线上问题，就把根因和修复模板补进对应的 SKILL.md，下次同类问题 AI 直接拦下来。