模块一：引言——SKILL.md为什么是法律条文
核心观点：如果把AI Skill比作一份给AI的岗位说明书，SKILL.md就是说明书的法律原文，AI会严格按照描述执行任务
两种结局——格式决定命运
写得好：AI准确、稳定、可预期地完成任务；修改后下次对话即时生效；同事打开文件秒懂功能
写得差：AI困惑、遗漏步骤、违反约束，甚至拒绝执行；改了10次AI还是按老方式运行；同事打开后问这个Skill是干嘛的
两个真实翻车现场
翻车0：技能名称加上了引号，好在提交前发现——YAML中字符串不需要引号，加了可能导致解析器把引号当成name的一部分，AI索引表中名字带引号，永远不会被正确匹配
翻车1：product-manager的description写成自我介绍而非功能描述——结果同事让分析竞品时AI匹配到了code-review而不是product-manager
翻车2：risk-tracker的工作流步骤用了无序列表并列关系——AI只收集了风险信息就直接结束，没有生成登记表；有序列表才是步骤顺序信号
核心结论：Markdown格式不是好看就行，而是AI理解执行意图的唯一载体，格式错了，执行的逻辑就歪了
模块二：Markdown六要素——AI的结构化母语
标题——划分逻辑区块
规范：一级标题通常只出现一次；至少包含触发条件、工作流程、约束规则；最多四级，AI对四级以上标题注意力明显下降；层级不跳跃，不要从#直接跳到###
实战验证：project-manager的6个二级标题+1个三级标题，层级清晰不超四级，AI读到红线时立刻知道这是硬约束
反例警示：yitangke-lecturer出现6个一级标题，违反一个文件只应有一个#的建议，AI对标题层级的注意力被稀释，不易区分是同一技能的四个篇章还是四个独立技能
列表——步骤化与清单化
有序列表：数字本身就是必须按这个顺序执行的信号，AI看到有序列表时严格遵守1→2→3→4的顺序
无序列表：并列关系，无顺序约束，适合红线、检查清单等场景
嵌套列表：子步骤用嵌套，AI能区分有序流程与并列检查项的执行语义
实战验证：testing的五阶段流水线用有序列表定义了不可更改的执行顺序，每个阶段内部用表格+有序列表嵌套组织，多层格式嵌套是复杂流程Skill的正确写法
代码块——命令、脚本、示例
行内代码：用于文件名、变量名、短命令，如执行`git diff`命令
块级代码：多行命令、脚本、输出示例，必须标明语言（bash、python、markdown等）
实战验证：ai-coach-director大量使用代码块，AI看到语言标注后能区分这是要执行的命令还是要生成的模板
正反对比：yitangke-lecturer的脚本调用标注了bash语言、参数名和依赖说明，AI清楚地知道这是bash命令有三个参数执行前要确保依赖已安装；如果写成纯文本，AI需要猜测是shell还是Python命令、参数叫什么
强调与语气——让AI重视关键信息
用法分级：最高强度用**加粗**（禁止做/必须做），中等强度用*斜体*（强调条件），最低强度用普通文本（一般描述）
实战验证：product-manager的红线全部用加粗强调关键动词，AI明确理解这是硬约束不是建议
关键原则：只对必须做/禁止做/极易出错的地方使用加粗，不要滥用——如果全文都是加粗，等于什么都没加粗
表格——结构化参数、对比信息
当需要描述多个选项、参数说明时，表格比列表更清晰，列对齐让AI能快速定位映射关系
实战验证：product-manager的意图识别路由表，AI逐行扫描关键词→子技能→路径的映射关系，对比段落形式需要更多自然语言解析
表格嵌套复选框：testing的提测准入标准清单展示了表格进阶用法——6项检查行数=检查项数量，每项有通过标准和不通过后果，☐是可操作的复选框，AI会逐项向用户确认
引用块——附加说明、警告
常用于标注注意事项或背景知识，引用块在AI眼中相当于高亮标注区域，和正文有视觉语义区分，AI会更仔细地阅读
实战验证：project-manager的必须追问场景用引用块呈现，AI对警告信息注意力更集中
Markdown六要素快速对照
标题：层级清晰不超四级→AI找到对应章节执行；反例多一级标题稀释注意力→AI分不清是同一技能还是多个独立技能
有序列表：数字序号=执行顺序→AI正确按序执行；无序列表并列→AI误解为并列项乱序执行
有序+嵌套：1→2→3→4→5+标题+表格+复选框嵌套→AI理解完整流程；缺少任一层次→AI理解不全
代码块：标注语言→AI理解执行意图；不标注→AI不知道这是命令还是模板
代码块规范：标注语言+参数名+依赖说明→AI清楚执行细节；不完整→AI猜参数名、忘记装依赖
加粗强调：**禁止**=硬约束信号→AI把硬约束当一般建议
表格：列对齐逐行匹配→AI快速定位；段落形式→AI需要解析大段文字匹配率下降
表格嵌套复选框：表格+☐=逐项确认流程→AI知道这是检查清单跳过确认
引用块：> ⚠️=高亮区域→AI对警告信息注意力不足
模块三：YAML Frontmatter——Skill的身份证
五个案例的Frontmatter一览
案例A product-manager：功能总览+覆盖枚举，description约180字符信息密度高
案例B project-manager：功能总览+覆盖枚举，description约220字符
案例C ai-coach-director：多句功能描述+差异化能力+自主学习引擎，description约380字符远超推荐长度但每个句子都是语义锚点
案例D testing-and-acceptance-management：箭头串联流程节点，description约80字符极短但信息密度极高
案例E yitangke-lecturer：枚举用户原话触发场景，description约250字符偏长但每句都是锚点，使用了YAML | literal block scalar语法保留换行
name字段——Skill的唯一标识
规范要求：只能包含小写字母、数字、连字符-，不能有空格；建议不超过50字符；整个技能库中应保持唯一
正确示例：pdf-analyzer、code-reviewer-v2、sql-optimizer
错误示例：PDF Analyzer（含大写字母和空格）、commit_message（下划线不建议）、代码审查（中文不推荐兼容性差）
最佳实践：使用名词短语，特定领域加前缀，统一命名风格如<业务域>-<角色>-<功能>
五个案例name分析：product-manager、project-manager、ai-coach-director、yitangke-lecturer均好评；testing-and-acceptance-management功能描述准确但带了多余引号发布前应去掉
description字段——路由的核心深度解析
长度控制：太短<20字符信息不足AI难以判断；太长>200字符浪费Token稀释关键信息；推荐80~150字符信息密度最佳
经典公式：[核心功能] + [输入类型] + [主要输出] + [可选：典型场景]
使用同义词增强匹配：在描述中加入常见同义词提高匹配率，如行动项=action items=待办事项=tasks
避免元描述：不要告诉AI你应该使用此Skill，而是直接描述功能
两种description策略对比：yitangke-lecturer枚举用户原话（入口型Skill需要广度覆盖多种表达），testing箭头串联流程节点（过程型Skill需要精度精确定义每个阶段）
核心启示：别被80-150字符的推荐范围框死，关键是信息密度不是字数——如果每个字符都在增加匹配价值超长有理，如果每个字符都在浓缩信息超短也有理
allowed-tools——授予AI的武器许可
基本语法：工具名(权限范围)，多个工具用逗号分隔
常用工具类型：Bash执行Shell命令、Python执行Python脚本、Read读取文件、Write写入文件、MCP调用MCP服务、WebFetch抓取网页
权限范围的最佳实践——最小权限原则：只授予完成任务所必需的最小权限，禁止使用Bash(*)
通配符使用：*匹配任意内容风险低，/*匹配目录下所有文件风险中，/**递归匹配风险高可能覆盖关键文件
多个Skill的权限合并：如果一个对话中先后激活了多个Skill，AI会获得所有已激活Skill的权限并集，因此不要依赖未激活Skill的安全限制来隔离风险
五个案例allowed-tools分析：product-manager和project-manager未声明正确（纯自然语言没有脚本）；ai-coach-director未声明需补充（引用了scripts/*.sh）；testing未声明正确（纯流程定义暂无脚本）；yitangke-lecturer未声明严重缺失（scripts/下有5个脚本）
