文章目录本篇目标Skill 的定义与本次检查的由来四类警告逐条解读改名字和目录改 description写清什么时候该用它过长正文的拆分方法上手第一步改好第一条 Skill参考资料实用总结本篇目标把经验写进 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分别存在大写、首字符为连字符、连续连字符的问题。下面是建议采用的示例结构.cursor/ └── skills/ └── excel-precheck/ ├── SKILL.md └── references/ └── examples.md对应 frontmatter---name:excel-precheckdescription:检查 Excel 台账合并前的字段差异和异常行。用于多个表格合并前的检查不用于直接修改源文件。---需要与name对齐的是紧挨着 SKILL.md 的父目录excel-precheck不是上层的skills也不是文件名本身。文件仍叫SKILL.md。如果暂时没有参考资料只保留目录和 SKILL.md 即可不必为了显得完整而创建空资源目录。改 description写清什么时候该用它description 超长不宜只从末尾截掉一段。更值得检查的是你写的是经验故事还是任务入口下面的改前示例没有刻意制造超长文本它展示的是另一种问题长度可能合规但 Agent 难以判断什么时候应该使用。改前---name:excel-precheckdescription:我整理了不少处理表格的经验涉及各种容易忽略的细节可以帮助你把表格工作做得更好。---改后---name:excel-precheckdescription:检查 Excel 台账合并前的字段差异、必填值缺失和重复记录候选。用于用户准备合并多个 Excel 表格、需要先排查异常的任务不用于直接合并、覆盖源文件或制作图表。---改后明确了做什么、什么时候用并保留 Excel、台账、合并、字段、异常等任务关键词。“不适用条件”是本篇建议的写法不是规范新增的必填字段。它适合用来收窄范围例如把“检查表格”和“直接修改表格”分开。先问自己只读这段 description不看正文能否判断它适合哪类请求如果不能就继续改触发条件不要追加更多“专业、高效、全面”之类的形容词。过长正文的拆分方法Agent Skills 采用渐进加载启动时加载 name 和 description约 100 tokens激活后加载整个正文正文建议小于 5000 tokens资源文件按需加载。因此拆文件不只是为了消除警告也是为了区分“每次都需要的操作要求”和“遇到具体情况才需要的详细材料”。可以按下面的顺序整理主文件保留适用范围、必要输入、执行步骤、输出要求和停止条件。长样例、字段对照说明、详细参考资料移到references/。在主文件对应步骤写清资源的用途和读取时机。例如在正文加入## 参考样例 需要判断字段差异或异常行的表达方式时 阅读 [检查样例](references/examples.md)。 样例不能代替用户提供的字段规则。被引用的文件要实际存在。不能只留一个链接就认为拆分完成。规范要求引用使用相对路径并保持一层引用深度。让 SKILL.md 直接指向需要的资料不设计“先读目录说明再跳转另一份说明”的多层查找过程。也不建议为了压缩长度删掉影响判断的边界。例如“只检查不覆盖源文件”虽然短却比重复背景更值得留在主文件。上手第一步改好第一条 Skill先选一个范围明确、能判断结果是否合格的任务不要把所有工作经验塞进同一个 Skill。以表格检查为例可以这样开始挑一条经验。把“擅长处理 Excel”收窄为“合并前检查字段和异常行”写清输入和预期输出。套用文末模板。保留匹配的任务要求修改作者信息如果换任务同时修改目录名和 name。检查文件结构。确认 frontmatter 有必填字段引用的资源真实存在正文没有堆入无关长材料。检查规范和警告。已准备好规范中的校验工具时可执行下面的命令再打开 Cursor CLI 的/skills选中对应 Skill按实际列出的项目修改检查警告是否清零。在新会话中给出符合 description 的请求建议明确请 Agent 使用该 Skill。检查它是否遵守步骤、输出要求和停止条件不把警告清零等同于任务验收。规范给出的校验命令是skills-ref validate ./my-skill./my-skill要替换成你的实际 Skill 目录。目录方面Cursor CLI 从 2026 年 3 月起也会发现.claude/skills、.agents/skills、.codex/skills中的 Skill2026-05-14 的更新还支持发现嵌套的.cursor/skills。这说明的是 Cursor CLI 的发现范围。同一 Skill 要交给其他代理使用目录位置和支持字段仍应按各自文档确认。另一个容易混淆的情况是“没有出现在/补全里”。Cursor CLI v2026.07.06 支持在 frontmatter 写user-invocable: false把只供模型使用的 Skill 从补全中隐藏模型仍能使用。它不是处理黄色警告的开关。具体界面呈现细节官方未写明以你本机 Cursor CLI 的实际界面为准。参考资料Cursor CLI changelog2026-10-08、2026-07-06、2026-05-14 及 2026 年 3 月更新Agent Skills 规范来源未注明发布日期实用总结可以把修改顺序记成名字合法、目录一致、描述明确、正文精简。前两项解决命名问题后两项让 Agent 更容易判断何时使用、怎样执行。下面是可复制的 SKILL.md 模板保存到excel-precheck/SKILL.md。它不依赖额外资源文件metadata使用字符串键值作者信息请替换成你自己的署名。--- 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 的一条经验是什么