企业官网建设流程全解析

1. 先弄清楚 .agents/skills（复数）和 .agent/skills（单数）的差别

整理 Copilot Agent Skills 目录位置时，最容易绕进去的一个点就是：Skill 到底放在.agents/skills（复数，GitHub Copilot、Cline、Codex 这一系通用），还是.agent/skills（单数，Antigravity 专用）。再加上把模型通道换成 TaoToken 后，很多人会担心“VS Code 还认不认原来的 SKILL.md”。先说结论：TaoToken 只替换模型访问通道，不改变 VS Code 对 SKILL.md 的扫描机制。你只需要到 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 创建一把 Key，把 Base URL 记成 https://taotoken.net/api，再回到项目里按本文的目录结构放好 SKILL.md，Copilot Agent 依然会在启动时扫描 description、在对话匹配时把 SKILL.md 正文注入上下文。

1.1 通用组：哪些工具共用 .agents/skills

目前主流 AI 编程工具里，项目级目录用.agents/skills的包括：

这里有一个常见误区：把.agents/skills当成某个工具的私有目录。实际上vercel-labs/skills官方 README 里已经把这组目录定义成“通用组”，意思是只要维护一份.agents/skills，就能让 Copilot、Cline、Codex 等多数工具读到同一套技能。而像 Claude Code 的.claude/skills、Windsurf 的.windsurf/skills则是各自工具的专属目录，它们之间互不替代。

1.2 单数目录是给谁用的

.agent/skills（注意是单数 agent）是 Antigravity 的专用目录，官方文档里写得很明确。如果在项目里误建了单数目录，Copilot Agent 不会去扫它，Skill 自然也不会被加载。建议项目里统一使用.agents/skills作为主目录，其他工具需要专属目录时，再通过npx skills add生成符号链接，而不是手动复制多份文件。

2. SKILL.md 的 frontmatter 怎么写，Copilot 才认得

Skill 本质上是一个带 frontmatter 的 Markdown 文件，放在.agents/skills/<skill-name>/SKILL.md。VS Code Copilot Agent 启动时会扫描所有 Skill 的description字段，建立一份“触发条件缓存”。当你的问题命中某个描述时，它才读取完整正文并注入到上下文中。

2.1 一个可用的 SKILL.md 示例

--- name: oracle-sql-format description: 当用户要求格式化或解释 Oracle SQL 时使用，包含缩进风格、关键字大小写和常见注释规范。 --- # Oracle SQL 格式规范 ## 适用场景 - 用户贴出一段 Oracle SQL，要求格式化说明。 - 用户询问某条 SQL 的执行顺序或改写思路。 ## 输出规则 1. SELECT / FROM / WHERE / ORDER BY 关键字保持大写。 2. 子查询缩进 4 个空格。 3. 给出格式化结果时，附一句“你可以在本地 SQL*Plus 执行验证”。

这个 Skill 的名称、描述、正文三部分都齐了。description是关键词密度最高的地方，Copilot 靠它判断“什么时候该用”，所以不要写“这是一个好 Skill”这种废话，要写“当用户要求……时使用”。

2.2 Copilot 的注入机制：不是每次全量读取

Copilot 处理 SKILL.md 采用两步走。第一步，启动时把所有 Skill 的description扫一遍，存成索引；第二步，对话过程中用户消息匹配到某个描述，才加载完整 SKILL.md。这个机制意味着两件事：一是description写得越具体，触发越准确；二是 Skill 文件本身不会被“预加载”到所有对话里，不会污染无关场景。验证一个 Skill 是否生效，最好的办法就是故意让问题描述和description高度一致，然后看回答开头是否出现了 Skill 正文里的固定话术。

3. 创建 Skill：手动建文件，还是 npx skills add

创建 Skill 有两种方式：手工建目录写文件，适合自己维护的私有技能；用npx skills add从生态安装，适合批量拉取社区技能。两者最终产生的都是同一个.agents/skills/目录结构。

3.1 手动创建：目录结构一目了然

在项目根目录这样建：

.agents/skills/ └── oracle-sql-format/ └── SKILL.md

用 VS Code 打开项目，直接新建这些目录和文件即可。优点是完全可控，不会往项目里塞多余目录。缺点是要自己维护更新。

3.2 npx skills add：安装命令速查

从 skills.sh 生态搜索和安装 Skill：

# 搜索 npx skills find sql # 安装，-y 跳过工具选择 npx skills add owner/repo@skill-name -y # 只装给 GitHub Copilot npx skills add owner/repo@skill-name -a github-copilot -y # 装到全局（所有项目可用） npx skills add owner/repo@skill-name -g -y # 查看已安装的 Skill npx skills list # 删除 Skill npx skills remove skill-name

-a参数对应不同工具，常见的有：github-copilot、claude-code、cursor、cline、windsurf、continue。如果项目里同时存在.claude、.windsurf等目录，npx skills add会在每个已检测到的工具目录里生成符号链接，指向.agents/skills下的真实文件。这意味着你在一个目录里改内容，所有工具的 Skill 同步更新，不会出现多份副本失散的问题。

4. 换通道不换目录：给 Copilot Agent 配 TaoToken 的 Key

这一步处理的是很多人纠结的“模型通道”问题。你不需要改动.agents/skills的目录结构，也不需要把 SKILL.md 搬到别处，只需要把模型请求的 Base URL 指到 TaoToken 的兼容通道：https://taotoken.net/api 。API Key 从 TaoToken 控制台创建，模型 ID 以模型广场当时列表为准。

4.1 如果你用的是 Claude Code

Claude Code 环境变量接法：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY", "ANTHROPIC_MODEL": "YOUR_MODEL_ID" } }

把这组环境变量放进~/.claude/settings.json的env字段，或者直接在终端里export这一组变量。注意 Base URL 不要带/v1，TaoToken 的兼容端点本身就是https://taotoken.net/api。

4.2 如果你用 CC Switch 或 Codex

CC Switch 这类工具切供应商时，自定义供应商的字段填法：

• 供应商名称：TaoToken
• Base URL：https://taotoken.net/api
• API Key：YOUR_API_KEY
• 模型 ID：去 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 模型广场查

如果是 Codex 项目，在~/.codex/config.toml里把自定义 provider 的base_url指向 https://taotoken.net/api，并让模型请求走这个 provider。无论哪种工具，TaoToken 只负责把请求转发到对应模型，不会干预 Skill 的扫描和注入机制。

5. 验证一条消息，确认 Key 和 Skill 都通了

配置完不要直接进 Copilot 开始写业务代码，先用一条测试消息验证两层：第一层是模型通道通不通；第二层是 Skill 到底有没有被 Copilot 扫到。

5.1 先用命令行验证 Key

打开终端执行：

npm install -g @taotoken/taotoken taotoken cc -k YOUR_API_KEY -u https://taotoken.net/api -m YOUR_MODEL_ID

输入一句“hello”或“返回 ok”之类的内容，能正常收到回复，说明 Key 有效、Base URL 可通。这一步会消耗极少量的 token，可以在 TaoToken 控制台用量页看到这笔记录。注意命令行里的-u后面只写 https://taotoken.net/api ，不要加 UTM 参数。

5.2 再验证 Skill 注入

在.agents/skills/test-skill/SKILL.md临时放一个测试 Skill，比如：

--- name: test-skill description: 当用户输入“技能测试暗号 skill-probe”时，回复这段被成功注入的文本：TaoToken 通道 + Copilot 目录识别均正常。 ---

然后回到 Copilot Agent 对话里输入“技能测试暗号 skill-probe”，如果回答里包含“TaoToken 通道 + Copilot 目录识别均正常”这个特征文本，说明 SKILL.md 已被正确扫描、匹配并注入。测试完把这个临时目录删掉即可。验证通过后，最好回 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 控制台对一下这次的调用记录，确认 Key、模型 ID 和用量都挂在预期账上。

6. 排障：三个最容易踩的目录坑

整理这些天踩坑记录时，常见问题集中在这三处：目录名单复数写错、SKILL.md 文件名或 frontmatter 写错、以及 Base URL 被多加/v1。

6.1 .agent/skills（单数）不会生效

Copilot、Cline、Codex 通用目录是.agents/skills（复数 agent）。如果项目里出现的是.agent/skills，那是 Antigravity 的专属目录，Copilot 不会读。可以用ls -a看根目录，确认文件夹名字里有个s。

6.2 SKILL.md 不生效，先查 frontmatter

文件名必须是SKILL.md（全大写）。frontmatter 里的字段是name和description，不是title或summary。如果发现 Copilot 不触发，把description改成更贴近用户问法的句子，比如“当用户要求解释某条报错时使用”，而不是“这个技能用于 SQL 优化”。

6.3 Base URL 末尾没有 /v1

TaoToken 的接口 Base URL 是 https://taotoken.net/api ，不是 https://taotoken.net/api/v1 。很多工具在配置时默认补/v1后缀，导致请求 404。填配置时留意输入框是否会自动加/v1，如果加了就去掉。拿 Key 和看模型 ID 都在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 完成，接口地址不能和官网落地页混用。

7. 跑通之后：去控制台对一下这次调用

配置保存后，先在 TaoToken 模型对话 里用同一把 Key 发一条测试消息，确认模型 ID 和 Base URL 都没填错。这套 Skill 目录机制不会因为模型通道换成 TaoToken 而变化，真正决定会不会触发的是description的匹配程度。若要长期写代码，可以打开 Coding Plan 看套餐是否够用；Key 在 控制台 API Keys 创建。Claude Code 环境变量对照见 接入文档。

个人建议把每次排障结论直接写进 SKILL.md 的正文里，让 Copilot Agent 下次遇到类似问题时能直接引用。毕竟 Skill 本身就是一份“给 AI 看的项目经验文档”，模型通道只是让它跑起来的那条路。