配置 AI Skill 时最让人困惑的现象是目录里明明有 Skill 文件模型却完全不按 Skill 里的规则执行。你把它当成普通提示词放进某个文件夹以为它马上就能生效结果在对话里怎么引导模型都像没看见一样。这不是工具坏了而是 Skill 的生效链路比普通提示词长得多它要经过目录扫描、元信息解析、描述匹配、按需加载、运行时执行这几个环节任何一个环节没对齐最终表现都是“装了但没生效”。这篇文章围绕 AI Skill 的配置与生效问题展开先讲清楚生效机制再带你把 Node.js、Git、CLI 工具、Skill 目录这一整套环境配齐用一个最小 Skill 跑通全流程最后给出从现象倒推原因的自查顺序和上线前检查清单。1. 先理解 AI Skill 的生效机制再谈“没生效”1.1 Skill 是什么它和普通提示词有什么区别通俗讲Skill 是给 AI 编程工具安装的“岗位说明书 工具包”。它不只是让模型记住一段话而是一个目录里面放着 SKILL.md 入口文件以及可供模型查阅的模板、脚本和说明文档。模型执行任务时会按照 Skill 里写的流程来组织回答。技术定义上Skill 是一组结构化文件的集合入口文件 SKILL.md 携带 YAML frontmattername 和 description正文描述执行步骤同一目录下还可以放脚本、模板、示例代码等辅助文件。工具启动时会扫描约定的 skills 目录解析每个 Skill 的元信息把技能列表交给模型。模型根据用户请求判断该调用哪个技能再读取完整的 SKILL.md 内容再执行。和普通提示词最核心的区别在于加载时机。提示词一旦写入系统提示或全局说明文件就会一直占据上下文Skill 则是按需加载的。模型先看到每个 Skill 的短描述只有认为当前任务匹配时才会去读正文。这种设计能节省上下文代价是“描述写不好 永远不会被调用”。1.2 Skill 从扫描到被调用的完整链路一个 Skill 要真正起作用通常要经过五步目录扫描工具启动时读取约定位置下的所有技能目录。例如 Claude Code 会读取~/.claude/skills/Codex CLI 会读取~/.codex/skills/。元信息解析解析每个 Skill 的 frontmatter拿到 name 和 description形成技能索引。描述匹配用户发出请求后模型阅读技能索引判断哪些技能与当前任务相关。description 写得越具体匹配概率越高。按需加载模型认为匹配后读取 SKILL.md 正文把其中的步骤和约束加入当前上下文。执行与反馈模型按正文步骤操作可能运行目录里的脚本也可能读取模板文件最后把结果组织成回答。理解了这条链路你就会明白把文件夹放对位置只是第一步。后面四步中任何一步出问题Skill 都会“沉默”。排查时不要只盯着目录要沿着链路逐项检查。1.3 为什么“装上”和“生效”是两回事“装上”指的是文件存在于磁盘“生效”指的是模型在合适时机读到它并且按它执行。这两者之间隔着几个常见断层工具没有把该目录当作 Skill 来源目录扫描路径写错了。frontmatter 格式错误解析失败技能没有进入索引。description 太宽泛模型无法把用户请求与该技能关联起来。工具版本过旧根本不支持 SKILL.md 格式把文件当成了普通文本。Skill 引用的脚本缺少运行环境执行时报错模型无法继续按流程走。后面第二节会给出顺序化的自查方法。这里先记住一个原则Skill 没有生效时优先怀疑“链路”而不是怀疑“玄学”。2. Skill 装完没生效按这条链路逐项自查2.1 目录和命名是否符合工具约定不同工具对 Skill 目录的约定不同但基本逻辑一致一个 Skill 一个文件夹文件夹下必须有入口文件 SKILL.md。以常见配置为例Claude Code全局技能放在~/.claude/skills/项目级技能放在项目目录下的.claude/skills/。Codex CLI技能放在~/.codex/skills/。Cursor 等编辑器更常见的是.cursor/rules/规则文件调用机制与 Skill 并不完全相同。自查时先确认两件事第一你是否放进了工具真正读取的目录第二文件名是否严格写成 SKILL.md。在 Linux 和 macOS 上文件系统默认区分大小写skill.md、Skill.md和SKILL.md是三个不同的文件。很多坑就出在这里。检查命令可以这样写ls -la ~/.claude/skills/ ls -la ~/.claude/skills/code-review/如果目录不存在说明工具还没创建默认技能目录或者你放错了位置。不要自己随便造一个不存在的路径先对照工具文档确认当前版本的实际目录约定。2.2 SKILL.md 的 frontmatter 是否完整有效SKILL.md 的开头是 YAML frontmatter至少包含 name 和 description。这两项是模型判断“何时调用”的依据。如果 frontmatter 缺失、YAML 语法错误或者字段名与工具要求不一致工具很可能把整个文件当作普通文档处理。典型错误写法--- name: 代码审查 desc: 代码审查技能 ---这段代码有两个问题字段名不是 descriptionname 用了中文。不同工具对 name 的字符集要求不同稳妥做法是全部使用小写字母和连字符例如code-review。正确写法--- name: code-review description: 当用户要求审查代码、检查合并请求或给代码提修改意见时使用。 ---还要注意 YAML 的缩进和冒号。description 里如果出现中文冒号问题不大但如果值里有英文冒号建议把整个值用引号包起来避免解析歧义。2.3 工具是否重新加载了 Skill 列表很多工具只在启动时扫描一次 Skill 目录。你在工具运行过程中新建、修改或删除了 Skill会话里仍然保留着旧索引自然看不到变化。遇到这种情况不要反复编辑文件直接重启会话或使用工具提供的重载命令。如果工具支持非交互模式可以像下面这样跑一次测试确认加载情况claude -p 列出你当前可用的 skills如果工具的回复中没有体现任何技能信息大概率是索引没更新或者目录没被识别。重启后仍然如此再回到目录和 frontmatter 检查。2.4 运行时和权限是否满足Skill 常常不只是文本还包含脚本。常见情况是 SKILL.md 里写了一段步骤要求模型运行scripts/check_todos.py之类的脚本。这时候 Skill 的生效就依赖外部运行时脚本是 Python 写的需要机器上有可用的 Python 3。脚本是 Node.js 写的需要机器上有可用的 Node.js。脚本需要执行权限在 Linux/macOS 上要执行chmod x。很多用户走到“模型开始运行脚本”这一步才发现环境缺失。更隐蔽的问题是系统终端里python可用但工具运行时的 PATH 不一样模型执行python命令却提示找不到。后面第三节讲环境时会专门处理这个问题。2.5 版本兼容性最后一个常见原因是版本。Skill 的目录格式和 frontmatter 字段仍在持续演进早期版本可能只支持插件或 slash command不支持完整 SKILL.md。判断方法很简单claude --version codex --version把版本号和官方文档对照确认当前版本是否支持 Skills。如果工具还不支持再折腾目录和文件都没有意义。反过来如果用的是最新版本但 frontmatter 里写了旧版不认识的字段也可能导致解析异常。建议先用最精简的 name description 跑通再逐步加字段。3. 搭建“完全体”Skill 运行环境3.1 先对照环境清单缺什么补什么所谓“完全体环境”不是指装得越多越好而是指 Skill 从加载到执行所需的每一层运行时都可用。建议对照下表逐项确认组件作用是否必需验证命令Node.js LTSAI 编程 CLI 本身依赖部分 Skill 脚本也要用必需node -vnpm安装 CLI 工具和 Skill 依赖必需npm -vGit拉取和共享 Skill 仓库强烈建议git --versionPython 3Skill 包含 Python 脚本时需要按需python --versionAI 编程 CLI加载并执行 Skill 的主体必需claude --version或codex --version账号与认证CLI 调用模型接口的前提必需登录成功提示注意区分“装过”和“命令行里可用”。很多环境问题的根因是图形界面和终端里用的不是同一套环境变量终端里node找不到工具执行脚本自然失败。3.2 安装并验证 Node.js 与 GitNode.js 的安装方式很多