尧图网页设计 
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 永远找不到它。第二如果你装了多个 Skilldescription 之间没有区分度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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。拿到 Key 之后模型对话可以在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 里先试一下确认通道正常再去配工具。为什么强调“先验证再配置”因为 Skill 触发失败时原因可能有两层一层是 description 没匹配上另一层是模型通道本身不通。如果你没先把通道验证好排查时会分不清到底是 Skill 的问题还是网络的问题。我试过的顺序是先在模型对话页发一句简单的话确认有响应再去 Cursor 里配 Base URL 和 Key最后才去调 description。这样每一步的变量都是可控的。对于长期要跑编码 Agent、频繁触发 Skill 的场景可以考虑 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它的定位是给持续编码、Agent 调用这类高频场景用的比单次按量更适合调试期。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各工具的配置说明配之前扫一眼能少踩坑。需要说明的是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.md3.2 可直接复制的 SKILL.md 模板下面这份模板以“Java 代码审查”为例description 部分是我反复调过的写法中英文关键词都覆盖了--- name: java-code-review description: - 按 Java 企业级规范审查代码检查安全漏洞SQL 注入、权限绕过、敏感信息泄露、 性能问题N1 查询、缺失索引、深分页、代码可读性命名、注释、复杂度。 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、手机号 - 权限校验接口是否有鉴权数据是否做了行级隔离 ### 性能建议优化 - N1 查询循环里调数据库 - 大对象序列化返回体包含不必要的大字段 - 缺少索引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 不写 WHENAI 不知道什么时候该用只写 WHEN 不写 WHATAI 不知道这个 Skill 到底能干什么没有关键词AI 匹配不到你的口语表达。3.4 中英文关键词都要写中国开发者用中文提问时如果 description 里只有英文触发率会明显下降。反过来如果你在英文语境里工作只有中文也会漏触发。推荐写法是核心描述用中文触发词中英文都写。比如单元测试这个 Skilldescription: - 为 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 代码性能瓶颈N1 查询、内存泄漏、线程安全、缓存策略。 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_KEYModel ID 按你选的模型填。三件套缺一不可Base URL、Key、Model ID。如果你用 Claude Code 的 Anthropic 兼容接入配置入口参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_codeutm_campaignrewrite 。配好之后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_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。发一句“你好确认一下通道”有正常响应再去配 Cursor 和 Claude Code。这样能把“通道问题”和“Skill 问题”分开排查。4.4 触发成功的判断标准总结一下触发成功有三个信号一是 Cursor 的 context 引用里出现 SKILL.md 路径二是 AI 的输出格式符合 SKILL.md 里的定义三是手动skill和自动触发结果一致。三个都满足说明 description 和正文都写对了。如果只有手动触发成功自动失败那就是 description 的关键词覆盖不够需要补充用户可能说的各种表达方式。如果两个都失败先检查 YAML 格式和目录位置再检查模型通道。5. 本篇常见错排查调试 Skill 触发时报错和异常基本集中在几类。这一节按真实报错对照排查。5.1 401 未授权现象模型调用返回 401Skill 触发了但 AI 没响应。原因通常是 API Key 填错、过期或者 Base URL 和 Key 不匹配。排查步骤先在模型对话页用同一个 Key 发一条消息如果也 401说明 Key 本身有问题去控制台重新生成https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。如果模型对话页正常、只有工具里 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/apiAPI Key 是否有效Model ID 是否填对。这三样在 Cursor 和 Claude Code 里都要完整配置。任何一样缺失或写错都会表现为“Skill 触发了但没结果”。接入细节参考文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。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.mdSKILL.md 里只留步骤和引用。比如安全审查 SkillSKILL.md 里写“按 security-checklist.md 检查”详细清单放另一个文件。这样 SKILL.md 保持简洁加载更快AI 也更容易抓住重点。6.3 长期编码场景的配置如果你要长期跑编码 Agent频繁触发 Skill按量计费的成本会累积。Coding Plan 的定位就是这类高频场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它适合持续编码、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 持续迭代 descriptiondescription 不是一次写完就固定的。用一段时间后回顾哪些触发失败了把用户当时说的原话补进关键词。比如你发现说“帮我 review 一下”没触发就把“review”加进去。description 的迭代方向永远是覆盖更多用户真实会说的表达方式同时保持和其他 Skill 的区分度。Skill 的价值在于把你说过的最好的一段话固化下来以后自动触发不用重复解释。而这一切的前提是 description 写对了。从今天这个模板开始先让第一个 Skill 精准触发再慢慢扩展成你自己的技能库。 Agent Skill 实战：用 SKILL.md 的 description 让 Cursor 与 Claude Code 精准触发
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 永远找不到它。第二如果你装了多个 Skilldescription 之间没有区分度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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。拿到 Key 之后模型对话可以在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 里先试一下确认通道正常再去配工具。为什么强调“先验证再配置”因为 Skill 触发失败时原因可能有两层一层是 description 没匹配上另一层是模型通道本身不通。如果你没先把通道验证好排查时会分不清到底是 Skill 的问题还是网络的问题。我试过的顺序是先在模型对话页发一句简单的话确认有响应再去 Cursor 里配 Base URL 和 Key最后才去调 description。这样每一步的变量都是可控的。对于长期要跑编码 Agent、频繁触发 Skill 的场景可以考虑 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它的定位是给持续编码、Agent 调用这类高频场景用的比单次按量更适合调试期。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各工具的配置说明配之前扫一眼能少踩坑。需要说明的是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.md3.2 可直接复制的 SKILL.md 模板下面这份模板以“Java 代码审查”为例description 部分是我反复调过的写法中英文关键词都覆盖了--- name: java-code-review description: - 按 Java 企业级规范审查代码检查安全漏洞SQL 注入、权限绕过、敏感信息泄露、 性能问题N1 查询、缺失索引、深分页、代码可读性命名、注释、复杂度。 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、手机号 - 权限校验接口是否有鉴权数据是否做了行级隔离 ### 性能建议优化 - N1 查询循环里调数据库 - 大对象序列化返回体包含不必要的大字段 - 缺少索引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 不写 WHENAI 不知道什么时候该用只写 WHEN 不写 WHATAI 不知道这个 Skill 到底能干什么没有关键词AI 匹配不到你的口语表达。3.4 中英文关键词都要写中国开发者用中文提问时如果 description 里只有英文触发率会明显下降。反过来如果你在英文语境里工作只有中文也会漏触发。推荐写法是核心描述用中文触发词中英文都写。比如单元测试这个 Skilldescription: - 为 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 代码性能瓶颈N1 查询、内存泄漏、线程安全、缓存策略。 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_KEYModel ID 按你选的模型填。三件套缺一不可Base URL、Key、Model ID。如果你用 Claude Code 的 Anthropic 兼容接入配置入口参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_codeutm_campaignrewrite 。配好之后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_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。发一句“你好确认一下通道”有正常响应再去配 Cursor 和 Claude Code。这样能把“通道问题”和“Skill 问题”分开排查。4.4 触发成功的判断标准总结一下触发成功有三个信号一是 Cursor 的 context 引用里出现 SKILL.md 路径二是 AI 的输出格式符合 SKILL.md 里的定义三是手动skill和自动触发结果一致。三个都满足说明 description 和正文都写对了。如果只有手动触发成功自动失败那就是 description 的关键词覆盖不够需要补充用户可能说的各种表达方式。如果两个都失败先检查 YAML 格式和目录位置再检查模型通道。5. 本篇常见错排查调试 Skill 触发时报错和异常基本集中在几类。这一节按真实报错对照排查。5.1 401 未授权现象模型调用返回 401Skill 触发了但 AI 没响应。原因通常是 API Key 填错、过期或者 Base URL 和 Key 不匹配。排查步骤先在模型对话页用同一个 Key 发一条消息如果也 401说明 Key 本身有问题去控制台重新生成https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。如果模型对话页正常、只有工具里 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/apiAPI Key 是否有效Model ID 是否填对。这三样在 Cursor 和 Claude Code 里都要完整配置。任何一样缺失或写错都会表现为“Skill 触发了但没结果”。接入细节参考文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。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.mdSKILL.md 里只留步骤和引用。比如安全审查 SkillSKILL.md 里写“按 security-checklist.md 检查”详细清单放另一个文件。这样 SKILL.md 保持简洁加载更快AI 也更容易抓住重点。6.3 长期编码场景的配置如果你要长期跑编码 Agent频繁触发 Skill按量计费的成本会累积。Coding Plan 的定位就是这类高频场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它适合持续编码、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 持续迭代 descriptiondescription 不是一次写完就固定的。用一段时间后回顾哪些触发失败了把用户当时说的原话补进关键词。比如你发现说“帮我 review 一下”没触发就把“review”加进去。description 的迭代方向永远是覆盖更多用户真实会说的表达方式同时保持和其他 Skill 的区分度。Skill 的价值在于把你说过的最好的一段话固化下来以后自动触发不用重复解释。而这一切的前提是 description 写对了。从今天这个模板开始先让第一个 Skill 精准触发再慢慢扩展成你自己的技能库。