企业官网建设流程全解析

配置 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 frontmatter（name 和 description），正文描述执行步骤；同一目录下还可以放脚本、模板、示例代码等辅助文件。工具启动时会扫描约定的 skills 目录，解析每个 Skill 的元信息，把技能列表交给模型。模型根据用户请求判断该调用哪个技能，再读取完整的 SKILL.md 内容再执行。

和普通提示词最核心的区别在于加载时机。提示词一旦写入系统提示或全局说明文件，就会一直占据上下文；Skill 则是按需加载的。模型先看到每个 Skill 的短描述，只有认为当前任务匹配时才会去读正文。这种设计能节省上下文，代价是“描述写不好 = 永远不会被调用”。

1.2 Skill 从扫描到被调用的完整链路

一个 Skill 要真正起作用，通常要经过五步：

1. 目录扫描：工具启动时读取约定位置下的所有技能目录。例如 Claude Code 会读取~/.claude/skills/，Codex CLI 会读取~/.codex/skills/。
2. 元信息解析：解析每个 Skill 的 frontmatter，拿到 name 和 description，形成技能索引。
3. 描述匹配：用户发出请求后，模型阅读技能索引，判断哪些技能与当前任务相关。description 写得越具体，匹配概率越高。
4. 按需加载：模型认为匹配后，读取 SKILL.md 正文，把其中的步骤和约束加入当前上下文。
5. 执行与反馈：模型按正文步骤操作，可能运行目录里的脚本，也可能读取模板文件，最后把结果组织成回答。

理解了这条链路，你就会明白：把文件夹放对位置只是第一步。后面四步中任何一步出问题，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: 代码审查技能 ---

这段代码有两个问题：字段名不是 description，name 用了中文。不同工具对 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找不到，工具执行脚本自然失败。

3.2 安装并验证 Node.js 与 Git

Node.js 的安装方式很多，