文章目录
本篇目标
把经验写进 SKILL.md，打开 Cursor CLI 的 /skills，却看到黄色警告：是经验没价值，还是文件写法不合要求？
先查格式和长度，不要急着重写整套方法。Cursor CLI v2026.10.08 新增的这组检查，针对的是名称、目录一致性、description 长度和正文长度，不是给经验内容打分。
本篇按这四类检查拆解修改方法，用"Excel 台账合并前检查"作为编写示例，最后给出可复制的模板。示例用于说明写法。
| 你碰到的现象 | 去看哪篇 |
|---|---|
| 想把写作里的口癖沉淀成审稿规则 | 实践经验 指导 AI 写文章时，别只改一篇稿子：把口癖和空话沉淀成 skill 再审一遍 |
| 多个表格合并前的检查经验原文 | Python实战 多个 Excel 台账合并前，先用 Python 查清字段和异常行 |
Skill 的定义与本次检查的由来
按照 Agent Skills 规范，Skill 是一个目录，至少包含 SKILL.md，也可以包含 scripts/、references/、assets/ 等资源目录。
SKILL.md 分成两部分：开头是 YAML frontmatter，必填 name 和 description；后面是 Markdown 正文，写具体步骤、判断条件和输出要求。
我把它理解为：description 负责告诉 Agent"什么任务适合找我"，正文负责说明"找到我之后怎么做"，资源文件提供需要时再读的详细材料。
Cursor CLI v2026.10.08 会在 /skills 中，对超出 Agent Skills 限制的 Skill 显示黄色警告计数；选中某条，可以查看需要修改的项目。
如果你维护了自己的 Skill，或者把已有经验整理成 Skill，这次检查就值得留意。不过，格式合规和任务有效是两件事：消除警告之后，仍要确认步骤能否支持实际任务。
四类警告逐条解读
先按表格定位问题，再改对应部分，避免把简单的目录命名问题扩大成全文重写。
| 警告类别 | 规则 | 常见原因示例 | 怎么改 |
|---|---|---|---|
| 名称长度或格式 | name 为 1--64 字符，只含小写字母、数字、连字符；首尾不能是连字符，不能有连续连字符 | 使用大写、下划线，或把整句说明写成名称 | 改为简短的小写连字符名称 |
| 名称与目录不一致 | frontmatter 的 name 必须与父目录名一致 | 只改文件里的 name，没改文件夹 | 对照检查，两处使用同一名称 |
| description 太长 | 1--1024 字符，不能为空 | 把完整操作流程放进描述 | 保留任务、触发条件和关键词，步骤移入正文 |
| 正文太长 | CLI 对超过约 5000 tokens 的正文给出警告 | 长样例、参考资料全部堆在主文件 | 主文件保留执行要点，详细内容拆到资源文件 |
前三类涉及字段和命名规则。第四类需要分清计量单位：约 5000 tokens 不是 5000 个汉字，也不是 5000 行。
规范还建议主 SKILL.md 控制在 500 行以内。这是整理主文件的另一条建议，不能反过来理解成"没到 500 行就不会触发正文长度警告"。
改名字和目录
先给 Skill 取一个描述任务的短名称，再同步修改父目录。
例如，把 Excel_Check 改成 excel-precheck。只改成小写还不够，下划线也不属于允许的字符。
规范中的 pdf-processing 是合法形式；PDF-Processing、-pdf、pdf--processing 分别存在大写、首字符为连字符、连续连字符的问题。
下面是建议采用的示例结构：
text
.cursor/
└── skills/
└── excel-precheck/
├── SKILL.md
└── references/
└── examples.md对应 frontmatter：
yaml
---
name: excel-precheck
description: 检查 Excel 台账合并前的字段差异和异常行。用于多个表格合并前的检查，不用于直接修改源文件。
---需要与 name 对齐的是紧挨着 SKILL.md 的父目录 excel-precheck，不是上层的 skills，也不是文件名本身。文件仍叫 SKILL.md。
如果暂时没有参考资料，只保留目录和 SKILL.md 即可，不必为了显得完整而创建空资源目录。
改 description：写清什么时候该用它
description 超长，不宜只从末尾截掉一段。更值得检查的是：你写的是经验故事，还是任务入口？
下面的改前示例没有刻意制造超长文本，它展示的是另一种问题：长度可能合规，但 Agent 难以判断什么时候应该使用。
改前：
yaml
---
name: excel-precheck
description: 我整理了不少处理表格的经验，涉及各种容易忽略的细节，可以帮助你把表格工作做得更好。
---改后：
yaml
---
name: excel-precheck
description: 检查 Excel 台账合并前的字段差异、必填值缺失和重复记录候选。用于用户准备合并多个 Excel 表格、需要先排查异常的任务；不用于直接合并、覆盖源文件或制作图表。
---改后明确了做什么、什么时候用，并保留 Excel、台账、合并、字段、异常等任务关键词。
"不适用条件"是本篇建议的写法，不是规范新增的必填字段。它适合用来收窄范围，例如把"检查表格"和"直接修改表格"分开。
先问自己：只读这段 description，不看正文，能否判断它适合哪类请求？如果不能，就继续改触发条件，不要追加更多"专业、高效、全面"之类的形容词。
过长正文的拆分方法
Agent Skills 采用渐进加载：启动时加载 name 和 description，约 100 tokens；激活后加载整个正文，正文建议小于 5000 tokens；资源文件按需加载。
因此，拆文件不只是为了消除警告，也是为了区分"每次都需要的操作要求"和"遇到具体情况才需要的详细材料"。
可以按下面的顺序整理：
- 主文件保留适用范围、必要输入、执行步骤、输出要求和停止条件。
- 长样例、字段对照说明、详细参考资料移到
references/。 - 在主文件对应步骤写清资源的用途和读取时机。
例如，在正文加入：
markdown
## 参考样例
需要判断字段差异或异常行的表达方式时，
阅读 [检查样例](references/examples.md)。
样例不能代替用户提供的字段规则。被引用的文件要实际存在。不能只留一个链接，就认为拆分完成。
规范要求引用使用相对路径，并保持一层引用深度。让 SKILL.md 直接指向需要的资料，不设计"先读目录说明，再跳转另一份说明"的多层查找过程。
也不建议为了压缩长度，删掉影响判断的边界。例如"只检查，不覆盖源文件"虽然短，却比重复背景更值得留在主文件。
上手第一步：改好第一条 Skill
先选一个范围明确、能判断结果是否合格的任务，不要把所有工作经验塞进同一个 Skill。
以表格检查为例，可以这样开始：
- 挑一条经验。把"擅长处理 Excel"收窄为"合并前检查字段和异常行"，写清输入和预期输出。
- 套用文末模板。保留匹配的任务要求，修改作者信息；如果换任务，同时修改目录名和 name。
- 检查文件结构。确认 frontmatter 有必填字段，引用的资源真实存在，正文没有堆入无关长材料。
- 检查规范和警告。已准备好规范中的校验工具时，可执行下面的命令；再打开 Cursor CLI 的
/skills，选中对应 Skill，按实际列出的项目修改，检查警告是否清零。 - 在新会话中给出符合 description 的请求，建议明确请 Agent 使用该 Skill。检查它是否遵守步骤、输出要求和停止条件，不把警告清零等同于任务验收。
规范给出的校验命令是：
text
skills-ref validate ./my-skill./my-skill 要替换成你的实际 Skill 目录。
目录方面，Cursor CLI 从 2026 年 3 月起也会发现 .claude/skills、.agents/skills、.codex/skills 中的 Skill；2026-05-14 的更新还支持发现嵌套的 .cursor/skills。
这说明的是 Cursor CLI 的发现范围。同一 Skill 要交给其他代理使用，目录位置和支持字段仍应按各自文档确认。
另一个容易混淆的情况是"没有出现在 / 补全里"。Cursor CLI v2026.07.06 支持在 frontmatter 写 user-invocable: false，把只供模型使用的 Skill 从补全中隐藏，模型仍能使用。它不是处理黄色警告的开关。
具体界面呈现细节，官方未写明，以你本机 Cursor CLI 的实际界面为准。
参考资料
实用总结
可以把修改顺序记成：名字合法、目录一致、描述明确、正文精简。前两项解决命名问题，后两项让 Agent 更容易判断何时使用、怎样执行。
下面是可复制的 SKILL.md 模板，保存到 excel-precheck/SKILL.md。它不依赖额外资源文件；metadata 使用字符串键值，作者信息请替换成你自己的署名。
markdown
---
name: excel-precheck
description: 检查 Excel 台账合并前的字段差异、必填值缺失和重复记录候选。用于多个 Excel 表格合并前的异常排查；不用于直接合并、覆盖源文件或制作图表。
metadata:
author: "请替换为你的署名"
---
## 任务范围
只检查并提出建议，不修改或覆盖源文件。
## 必要输入
1. 待检查的文件和工作表范围。
2. 预期字段与必填字段。
3. 判断重复记录所需的业务键。
## 执行步骤
1. 确认文件与检查范围；不能访问文件时说明原因。
2. 对照预期字段，列出缺失、额外和名称不一致的字段。
3. 按用户提供的规则检查必填值和重复记录候选。
4. 将已确认问题与待确认问题分开。
5. 给出合并前的处理建议，不直接执行合并。
## 输出要求
1. 检查范围与采用的规则。
2. 字段差异和异常记录位置。
3. 尚不能判断的事项及缺失信息。
4. 建议的下一步操作。
## 停止条件
缺少字段规则或业务键时，先询问用户。
无法读取文件时，不编造检查结果。经验写成 Skill，不是把一句"我懂这个"交给 Agent，而是把你的判断条件、处理顺序和边界表达清楚。署名能记录作者，真正支撑复用的仍是这些具体内容。
本篇收入「Cursor / AI Agent 实战」专栏。你可以沿着本篇的方法，先整理一条经验，再根据实际任务表现修订。
你最想写成 Skill 的一条经验是什么？