企业官网建设流程全解析

1. 为什么你的 Agent Skill 总是不触发

很多人第一次写 SKILL.md 时，都会遇到同一个尴尬：文件建好了，内容也写得很认真，结果在 Cursor 或 Claude Code 里问半天，AI 压根没读它。你以为是工具不支持，其实是 description 没写对。

Agent Skill 的本质，是给 AI 装一套“肌肉记忆”。它和 Rule、Prompt 最大的区别在于：Rule 是全局常驻的行为准则，Prompt 是当次对话的临时吩咐，而 Skill 是按需触发的专项技能。触发开关只有一个——SKILL.md 顶部 YAML frontmatter 里的description字段。AI 会把你当前说的话，去和所有已安装 Skill 的 description 做匹配，匹配度最高的那个才会被加载。

这意味着两件事。第一，Skill 正文写得再漂亮，description 没写好，AI 永远找不到它。第二，如果你装了多个 Skill，description 之间没有区分度，AI 就会频繁触发错，答非所问。我见过太多人把 description 写成“帮助用户处理代码相关问题”这种万能句，结果就是永远不触发，或者乱触发。

这篇内容聚焦一个具体问题：怎么设计 description，让 Cursor 和 Claude Code 精准识别并调用你的 Skill。我会给出可直接复制的 SKILL.md 模板、description 的三要素公式、中英文关键词写法，以及在两类工具里验证命中效果的完整步骤。适合已经了解 Skill 基本概念、但触发率上不去的开发者。读完你能自己写出一份“说一句话就能精准命中”的 Skill。

2. TaoToken 前置：给 Skill 配一个稳定的模型入口

在讲 description 之前，先说一个容易被忽略的前置问题：Skill 触发之后，AI 得真的能跑起来。Cursor 和 Claude Code 都支持自定义模型接入，如果你用的是按量计费的官方通道，调试 Skill 时频繁触发、反复试错，成本会悄悄涨上去。这时候配一个稳定的 API 入口就很实际。

TaoToken 提供的就是这样一个入口，官网是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api 。它的作用是让你在 Cursor、Claude Code 这类工具里，通过统一的 Base URL 和 Key 调用模型，不用每个工具单独折腾一套配置。

具体到 Skill 调试场景，你需要准备三件套：Base URL、API Key、Model ID。这三样在 Cursor 的模型设置和 Claude Code 的环境变量里都要用到。获取 Key 的入口在控制台的 API Keys 页面：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。拿到 Key 之后，模型对话可以在 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 里先试一下，确认通道正常，再去配工具。

为什么强调“先验证再配置”？因为 Skill 触发失败时，原因可能有两层：一层是 description 没匹配上，另一层是模型通道本身不通。如果你没先把通道验证好，排查时会分不清到底是 Skill 的问题还是网络的问题。我试过的顺序是：先在模型对话页发一句简单的话确认有响应，再去 Cursor 里配 Base URL 和 Key，最后才去调 description。这样每一步的变量都是可控的。

对于长期要跑编码 Agent、频繁触发 Skill 的场景，可以考虑 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。它的定位是给持续编码、Agent 调用这类高频场景用的，比单次按量更适合调试期。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有各工具的配置说明，配之前扫一眼能少踩坑。

需要说明的是，TaoToken 在这里的角色是模型调用入口，不是替代 Cursor 或 Claude Code 本身。Skill 的目录结构、YAML 格式、触发机制，仍然由 Cursor 和 Claude Code 各自决定。你要做的是把模型通道配通，然后把精力放在 description 的设计上。

3. 可复制配置：SKILL.md 模板与 description 写法

这一节是核心。先给一个完整的、可直接复制的 SKILL.md 模板，再拆解 description 的写法。

3.1 目录结构与文件位置

Cursor 的个人 Skill 放在~/.cursor/skills/skill-name/，项目 Skill 放在项目根目录的.cursor/skills/skill-name/。Claude Code 把前缀换成.claude即可：个人是~/.claude/skills/skill-name/，项目是.claude/skills/skill-name/。两者除了目录前缀不同，文件结构、YAML 格式、触发规则完全一致。

一个 Skill 目录的核心是 SKILL.md，可选配 reference.md、examples/、scripts/。先看最小可用结构：

~/.cursor/skills/java-code-review/ └── SKILL.md

3.2 可直接复制的 SKILL.md 模板

下面这份模板以“Java 代码审查”为例，description 部分是我反复调过的写法，中英文关键词都覆盖了：

--- name: java-code-review description: >- 按 Java 企业级规范审查代码，检查安全漏洞（SQL 注入、权限绕过、敏感信息泄露）、 性能问题（N+1 查询、缺失索引、深分页）、代码可读性（命名、注释、复杂度）。 Use when reviewing Java code, Spring Boot controllers, service layer, DAO layer, or when user asks for code review, PR review, security audit, 代码审查, 代码质量, 安全检查, 帮我看看这段代码, 有没有问题. --- # Java 代码审查 ## 审查维度 ### 安全（必须修） - SQL 注入：字符串拼接 SQL、未使用参数化查询 - 敏感信息：日志里打印密码、token、手机号 - 权限校验：接口是否有鉴权，数据是否做了行级隔离 ### 性能（建议优化） - N+1 查询：循环里调数据库 - 大对象序列化：返回体包含不必要的大字段 - 缺少索引：where 条件字段没有索引 ### 可读性（酌情处理） - 方法超过 30 行 - 魔法数字未提取常量 - 注释缺失或过时 ## 输出格式 逐条列出问题，每条包含：位置、问题描述、修复建议。 按“高危 → 中危 → 低危”分级。

这份模板的关键在 description 那几行。它同时包含了中文能力描述、英文触发场景、中英文关键词。下面拆解为什么这么写。

3.3 description 三要素公式

一个好的 description 必须包含三部分：WHAT（做什么）+ WHEN（何时触发）+ 关键词（触发词汇）。公式模板是：

[具体能力描述]。Use when [触发场景1], [触发场景2], or when user [asks for/mentions/wants] [关键词].

对照上面的模板：前半句“按 Java 企业级规范审查代码，检查安全漏洞……”是 WHAT；中间的“Use when reviewing Java code, Spring Boot controllers……”是 WHEN；最后的“代码审查, 代码质量, 安全检查, 帮我看看这段代码”是关键词。三者缺一不可。

只写 WHAT 不写 WHEN，AI 不知道什么时候该用；只写 WHEN 不写 WHAT，AI 不知道这个 Skill 到底能干什么；没有关键词，AI 匹配不到你的口语表达。

3.4 中英文关键词都要写

中国开发者用中文提问时，如果 description 里只有英文，触发率会明显下降。反过来，如果你在英文语境里工作，只有中文也会漏触发。推荐写法是核心描述用中文，触发词中英文都写。比如单元测试这个 Skill：

description: >- 为 Java 方法生成完整的单元测试，使用 JUnit5 + Mockito 框架。 Use when user asks for unit tests, test cases, 单测, 测试用例, or when working with @Service, @Component classes that need testing.

这里“单测”“测试用例”就是中文口语里最常出现的说法，必须显式写进去。AI 不会自动把“单测”翻译成“unit test”再去匹配，它做的是字面和语义的近似匹配，你写了它才认。

3.5 多个 Skill 的 description 要有区分度

如果你装了多个 Skill，它们的 description 不能太相似。反面例子：

# Skill A description: 帮助分析和优化代码 # Skill B description: 检查代码问题并提供建议

这两个几乎一样，AI 不知道该用哪个，结果就是随机触发或者都不触发。正确做法是让每个 Skill 的职责边界清晰：

# Skill A：专门做安全审查 description: >- 检查 Java 代码安全漏洞：SQL 注入、XSS、权限绕过、敏感信息泄露。 Use when security audit, 安全审查, vulnerability check. # Skill B：专门做性能优化 description: >- 分析 Java 代码性能瓶颈：N+1 查询、内存泄漏、线程安全、缓存策略。 Use when performance optimization, 性能优化, slow response, 慢查询.

安全审查和性能优化是两个正交的维度，关键词不重叠，AI 就能准确分流。

3.6 description 长度与自检

长度建议：最短 30 字以上，太短匹配不精准；最长不超过 500 字，系统限制是 1024 字，但太长浪费上下文；最佳区间是 80 到 150 字，包含 WHAT + WHEN + 5 到 10 个关键词。

写完 description 后，问自己三个问题：是不是第三人称描述（不能出现“我”“你”）？有没有说清楚“什么时候用”（有没有 Use when）？有没有 5 个以上的触发关键词？三个都是“是”，才算合格。

3.7 在 Cursor 与 Claude Code 中配置模型入口

Skill 要跑起来，模型通道得先通。Cursor 里在设置中找到模型配置，填入 Base URLhttps://taotoken.net/api、API Key 和 Model ID。Claude Code 里通过环境变量配置，典型的是设置ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY，Model ID 按你选的模型填。三件套缺一不可：Base URL、Key、Model ID。

如果你用 Claude Code 的 Anthropic 兼容接入，配置入口参考 https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claude_code&utm_campaign=rewrite 。配好之后，Skill 的触发和模型调用是两条独立的链路：description 决定“触不触发”，模型通道决定“触发后能不能跑”。两条都通，才算真正可用。

4. 验证请求：确认 Skill 真的被命中

配置写完，必须验证。很多人以为“重启工具就生效了”，其实要确认 AI 到底有没有加载你的 SKILL.md。这一节给 Cursor 和 Claude Code 各自的验证步骤。

4.1 Cursor 中的验证步骤

第一步，确认目录和文件。在终端执行：

ls -la ~/.cursor/skills/java-code-review/ cat ~/.cursor/skills/java-code-review/SKILL.md

确认 SKILL.md 存在，且 frontmatter 的---闭合正确。YAML 格式错误是触发失败的头号原因，比如冒号后没空格、缩进用了 Tab。

第二步，重启 Cursor。Skill 是在启动时扫描加载的，新建或修改后必须重启。

第三步，用自然语言触发。在对话里输入一句和 description 关键词沾边的话，比如“帮我看一下这个 UserService 有没有问题”。注意不要用@skill手动指定，先测自动触发。

第四步，看 context 引用。Cursor 的回复上方会显示本次加载的上下文，如果看到java-code-review/SKILL.md字样，说明 Skill 被成功加载。如果没看到，说明 description 没匹配上，回到第 3 节调整关键词。

第五步，测手动触发兜底。输入@java-code-review 帮我审查这个 Controller，这种方式不依赖 AI 判断，100% 触发。如果手动能触发、自动不能，问题一定在 description。

4.2 Claude Code 中的验证步骤

Claude Code 的验证逻辑类似，但观察方式不同。先确认目录：

ls -la ~/.claude/skills/java-code-review/

然后启动 Claude Code，输入触发语句。Claude Code 会在处理时读取匹配的 Skill，你可以在它的输出里观察是否引用了 Skill 内容。如果它按你 SKILL.md 里定义的“高危 → 中危 → 低危”格式输出，说明 Skill 生效了。

一个实用的验证技巧：在 SKILL.md 里放一句独特的输出要求，比如“输出开头必须写‘Java 安全审查报告’”。触发后如果 AI 真的这么写了，就证明它读到了你的 Skill，而不是凭自己的理解回答。

4.3 用模型对话先验证通道

在配工具之前，建议先在模型对话页确认通道正常：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。发一句“你好，确认一下通道”，有正常响应再去配 Cursor 和 Claude Code。这样能把“通道问题”和“Skill 问题”分开排查。

4.4 触发成功的判断标准

总结一下，触发成功有三个信号：一是 Cursor 的 context 引用里出现 SKILL.md 路径；二是 AI 的输出格式符合 SKILL.md 里的定义；三是手动@skill和自动触发结果一致。三个都满足，说明 description 和正文都写对了。

如果只有手动触发成功，自动失败，那就是 description 的关键词覆盖不够，需要补充用户可能说的各种表达方式。如果两个都失败，先检查 YAML 格式和目录位置，再检查模型通道。

5. 本篇常见错排查

调试 Skill 触发时，报错和异常基本集中在几类。这一节按真实报错对照排查。

5.1 401 未授权

现象：模型调用返回 401，Skill 触发了但 AI 没响应。原因通常是 API Key 填错、过期，或者 Base URL 和 Key 不匹配。排查步骤：先在模型对话页用同一个 Key 发一条消息，如果也 401，说明 Key 本身有问题，去控制台重新生成：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。如果模型对话页正常、只有工具里 401，检查工具里 Base URL 是否写成了https://taotoken.net/api，有没有多写斜杠或漏写。

5.2 local proxy failed

现象：工具报本地代理失败。这类报错通常和网络配置有关。排查时确认工具的代理设置是否为空或指向了不可用的地址。如果你在 Cursor 里配了自定义 Base URL，确保没有同时开启会冲突的代理选项。把 Base URL 直接设为https://taotoken.net/api，不要经过额外的本地转发。

5.3 reading choices 报错

现象：返回结构解析失败，报类似 reading 'choices' 的错误。这通常是模型返回格式和工具预期不一致导致的。排查：确认 Model ID 填的是工具支持的模型标识，不要填成别的厂商的模型名。Model ID 写错时，返回结构可能对不上，工具解析就报错。在模型对话页确认你用的 Model ID 能正常返回，再填进工具。

5.4 OAuth 相关报错

现象：Claude Code 里出现 OAuth 登录相关提示。如果你用的是 API Key 接入，不需要走 OAuth 流程。检查是否误触发了登录命令，或者环境变量没生效导致工具回退到默认的登录方式。确认ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL都设置正确，重启终端让环境变量生效。

5.5 Skill 不触发（无报错）

现象：模型通道正常，但 AI 就是不读 Skill。这是最常见的问题，原因几乎都在 description。排查清单：YAML frontmatter 的---是否闭合；name和description字段拼写是否正确；description 是否包含用户实际会说的关键词；多个 Skill 的 description 是否太相似导致互相干扰。逐个排除，通常补几个中文关键词就能解决。

5.6 触发错 Skill

现象：问代码审查，结果触发了性能优化 Skill。原因是两个 Skill 的 description 关键词重叠。解决方法是给每个 Skill 划定清晰的关键词边界，安全审查只写安全相关词，性能优化只写性能相关词，不要都写“代码优化”这种模糊词。

5.7 三件套检查清单

无论哪类报错，先过一遍三件套：Base URL 是否为https://taotoken.net/api；API Key 是否有效；Model ID 是否填对。这三样在 Cursor 和 Claude Code 里都要完整配置。任何一样缺失或写错，都会表现为“Skill 触发了但没结果”。接入细节参考文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。

6. 把 Skill 用起来：从触发到长期编码

description 调通之后，Skill 才算真正可用。接下来是把它用进日常工作流。

6.1 从单个 Skill 到 Skill 组合

一开始不用贪多，先写一个最常用的 Skill，比如代码审查或 commit message 生成，把 description 调到稳定触发。稳定之后，再按同样的方法加第二个、第三个。每加一个，都要检查它和已有 Skill 的 description 有没有关键词冲突。我建议一个项目里先控制在 3 到 5 个 Skill，覆盖最高频的场景，比如代码审查、单测生成、接口文档、commit 规范。

6.2 用辅助文件减轻 SKILL.md 体积

当 Skill 内容变多，不要把全部规范塞进 SKILL.md。把详细清单放进 reference.md，SKILL.md 里只留步骤和引用。比如安全审查 Skill，SKILL.md 里写“按 security-checklist.md 检查”，详细清单放另一个文件。这样 SKILL.md 保持简洁，加载更快，AI 也更容易抓住重点。

6.3 长期编码场景的配置

如果你要长期跑编码 Agent，频繁触发 Skill，按量计费的成本会累积。Coding Plan 的定位就是这类高频场景：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。它适合持续编码、Agent 反复调用的工作流，比单次按量更省心。配置方式还是三件套：Base URL、Key、Model ID，在对应工具里填好即可。

6.4 团队共享与版本管理

项目级 Skill 放在.cursor/skills/或.claude/skills/下，提交到 Git 就能团队共享。每次修改 SKILL.md，在 commit message 里写清楚改了什么，比如“docs(skill): java-code-review 新增反序列化检查项”。这样团队能追踪“为什么这条规范被加进来”，也方便回滚不合适的改动。

6.5 持续迭代 description

description 不是一次写完就固定的。用一段时间后，回顾哪些触发失败了，把用户当时说的原话补进关键词。比如你发现说“帮我 review 一下”没触发，就把“review”加进去。description 的迭代方向永远是：覆盖更多用户真实会说的表达方式，同时保持和其他 Skill 的区分度。

Skill 的价值在于把你说过的最好的一段话固化下来，以后自动触发，不用重复解释。而这一切的前提，是 description 写对了。从今天这个模板开始，先让第一个 Skill 精准触发，再慢慢扩展成你自己的技能库。