企业官网建设流程全解析

skills 这个词最近在 AI 编程圈里几乎天天有人提。你刷视频能看到 superpower skills，翻 GitHub 能翻到一大堆 claude skills、codex skills 的合集，连 opencode 和各类插件生态也把 skills 当成标配。我最早也是一头雾水——这不就是一堆 markdown 吗？为什么大家当个宝？真正用上之后才明白，skills 解决的是 AI 编程助手“记不住事、干活没套路”的痛点：把一套成熟的流程固化下来，让模型碰到对应任务时自动按步骤执行。

这篇文章是我自己从零折腾 skills 的记录：从 GitHub 手动装、验证、选型，到写自己的第一个 skill，再到数学建模、前端开发这些具体场景的配置，最后把踩过的坑和排查方法一并整理出来。适合刚接触 skills 但被各种教程绕晕的朋友，也适合已经装了一堆技能但觉得不好用、想自己动手重写的人。我会尽量把每一步怎么操作、为什么这么做讲清楚，少讲虚的概念，多给能直接上手的方案。

1. 先说清楚：AI 编程工具里的 skills 到底是什么

1.1 不是提示词，也不是插件：skills 的定位

先纠正一个最常见的误解：skills 不是一段提示词，也不是一个插件。提示词是一次性的，你说完就没了，下次还得重新组织语言；而 skill 是一个结构化的文件（或一个目录），里面有指令、有示例、甚至还有配套的脚本和模板，模型每次用到它时都会读到完整的流程说明。

插件呢？插件通常运行在工具外部，负责调用 API、操作文件系统这些“动手”的事。skill 的重心不一样，它首先是给模型看的“说明书”。当然，一个完整的 skill 也可以附带脚本，让模型在执行时调用，所以它俩的边界会有一点重叠，但定位完全不同。

打个比方，提示词像是你临时交代同事“帮我把这个表格整理一下”，而 skill 是一份标准作业指导书，里面有整理步骤、格式要求、检查清单，同事（模型）下次再遇到类似活，就知道直接按这套流程走，不用你重新讲一遍。

这背后其实是一个很大的痛点：大模型的上下文是“一次性”的，每次新开对话它就把之前的事忘光了。你上次手把手教它怎么写的代码规范、怎么处理数据、怎么排版，这次全不记得。skills 就是把这些经验固定成文件，相当于给 AI 配了一个可复用的“第二大脑”。

1.2 Skills 在 Claude Code、Codex、opencode 里的存在形式

目前市面上主流的 AI 编程工具对 skills 的支持方式不太一样，我按实际使用频率说一下。

Claude Code 是做得最完整的一个。它规定每个 skill 是一个文件夹，里面必须有一个 SKILL.md 文件，YAML 头里写 name 和 description，正文写具体的操作指令。技能放在两个位置：项目级的是.claude/skills/，个人级的是~/.claude/skills/。工具启动时会自动扫描这些目录，把每个技能的 description 加载进模型，模型根据任务判断要不要调用。

Codex（OpenAI 的编程助手）走的是另一条路，它主要靠 AGENTS.md 这类项目说明文件来约束模型行为。社区里很多 codex skills 其实是把 Claude 的 skill 格式转成 markdown 指令，或者做成一个可以被引用的文档，让 Codex 在项目里读取。你可以理解为“技能内容一样，外壳不同”。

opencode 作为开源社区很活跃的工具，插件机制是它的特色，skills 一般以插件或者 preset 的形式存在，原理同样是“把一套指令持久化，模型按需读取”。

所以别被各种工具的名字吓到，核心思路就一条：把可复用的流程写进文件，让模型在合适的时候读出来执行。你在 Claude Code 里学会了怎么写 SKILL.md，到了别的工具只是改改放文件的路径而已。

1.3 为什么 2025 年大家都在聊 skills

skills 突然火起来，我觉得有三个原因。

第一是模型能力够了，但“默认行为”不可控。模型很强，什么都会一点，可实际干活时经常不按你的项目规范来。你让它写代码，它写得通，但是风格和你团队完全不一样。skills 正好能把“团队规范”“个人偏好”固化下来，让模型输出稳定在一个预期范围内。

第二是经验无法跨会话复用。开发者每天花大量时间在对话里教模型各种细节，这些对话关掉就没了。以前只能靠维护一个巨大的 AGENTS.md 或者提示词文件，越写越乱。skills 提供了更清晰的模块化方式，一个技能管一件事，按需加载。

第三是社区生态起来了。superpower skills 这种成体系的技能框架一出来，大家发现原来技能还能这么写——不只是“做什么”，还包括了“怎么思考”“怎么规划”“怎么验证”。再加上 Anthropic 自己也开源了官方 skills 仓库，把 PDF、Word、Excel 这些文档处理能力做成了标准技能，直接给整个生态定了一个模板。后来越来越多的人开始“技能化”自己的工作流，前端开发、数学建模、内容创作，几乎每个领域都能看到对应的 skills 合集。

2. 从 GitHub 手动装 skills：绕开一切平台的硬核姿势

2.1 先搞懂 skills 的目录结构

在动手安装之前，强烈建议你先打开一个 skill 仓库，看看里面长什么样。以 Claude Code 的官方 skills 仓库为例，每个技能就是一个文件夹，比如skills/docx/SKILL.md。有的技能除了 SKILL.md 还有子目录，比如scripts/、references/，里面放着这个技能要用的辅助脚本和参考资料。

SKILL.md 是核心，它的格式非常固定。开头是一段 YAML frontmatter，里面至少要写 name 和 description 两个字段。然后是正文，正文里是详细的步骤、规则、示例。模型拿到这个文件后，会先读 frontmatter 里的 description，判断当前任务是否匹配；匹配了才会继续读正文，按里面的流程执行。所以 description 写得好不好，直接决定这个技能会不会被正确触发——这个后面写技能的部分我会展开说。

一个常见的坑是：很多人以为把 SKILL.md 随便丢进项目里就行，结果完全不生效。其实 Claude Code 扫描的是固定目录，你放在别的地方，它根本看不到。一定要放在.claude/skills/<技能名>/SKILL.md或者~/.claude/skills/<技能名>/SKILL.md这个结构下。

2.2 手动安装的完整步骤

虽然现在很多工具和平台提供了“一键安装” skills 的功能，但手动装依然是最稳的方式，尤其是遇到需要特定版本的场景。步骤其实很简单：

1. 在 GitHub 上找到目标仓库，复制仓库地址，执行git clone把整个仓库拉到本地。如果仓库很大又只想装其中某个技能，也可以不带历史记录拉取，用git clone --depth 1只拉最新内容。
2. 打开仓库目录，找到 skills 子目录（有的仓库把所有技能放在skills/下，有的直接放在仓库顶层，需要自己看一下）。
3. 把你要装的技能文件夹复制到目标位置。个人全局技能就放到~/.claude/skills/，项目内技能放到项目的.claude/skills/下。
4. 重启当前 Claude Code 会话，让工具重新扫描技能目录。
5. 输入/skills（或对应工具的技能列表命令）检查技能是否被加载出来。

这里要提醒一个细节：复制的时候，目录名就是技能名。如果仓库里的技能目录叫superpower-brainstorming，你复制到本地后不要随手改成brainstorm，否则可能出现技能名和内部指令不一致的问题。保持原名是最省心的。

2.3 装完怎么验证生效

装完不是结束，验证才是关键。我自己踩过很多次“装完发现根本没加载”的坑，所以现在每次装完都会做三步检查。

第一步，用技能列表命令确认加载。Claude Code 里输入/skills会列出当前可用的技能，看到名字就说明目录放对了、frontmatter 解析成功。

第二步，做一个最小触发测试。比如装了一个 React 组件生成技能，就新开一个会话，直接说“帮我在当前项目里建一个 button 组件，按项目规范来”。如果模型真的调用了技能，它通常会在回复里明确提到“我将使用 xxx 技能来完成”，或者行为明显符合技能里写的步骤。如果模型完全没提技能名、输出风格也和技能定义的不一样，那大概率是没生效或者没被触发。

第三步，看一下日志。Claude Code 的调试日志里会记录技能加载和调用的信息。遇到技能相关的问题，开着--debug跑一遍，能看到它到底有没有扫描到技能文件、description 是什么、最终是否触发。这个信息比肉眼猜要准得多。

2.4 安装路径选择：全局还是项目级

这是很多人容易纠结的问题。我的原则很简单：通用技能放全局，项目技能放项目。

像代码审查、前端组件生成、LaTeX 排版这类跟具体项目无关的技能，放~/.claude/skills/，这样所有项目都能用，不用重复装。但要注意，全局技能越多，模型每次会话要扫描的 description 就越多，误触发的概率也会变高，所以全局目录里只放高频使用的技能。

项目级的.claude/skills/则适合放跟这个项目强绑定的内容：这个项目的代码规范、这个项目的技术栈约定、这个项目的文档格式。因为项目级技能会跟着 git 仓库走，团队里每个人 clone 下来都能用，是团队协作的最佳载体。

有一个场景要特别提一下：如果你同时配了全局和项目级同名技能，不同工具的处理方式不一样，有的会报冲突，有的会用项目级覆盖全局级。我建议规则是“项目内明确存在同名技能时，优先用项目级，把全局那份删掉或改名”，避免出问题的时候不知道是哪个在起作用。

3. 值得装进工具箱的 skills 清单

3.1 Superpower Skills：一套成体系的协作框架

如果你只打算装一个合集，我大概率会推荐 superpower skills。它不是零散的几个技能，而是一套完整的“如何与 AI 协作”的方法论，包含头脑风暴、方案细化、执行规划、编码、测试、调试等多个环节。

它的核心理念是把大任务拆成小步骤，每个步骤有专门的技能负责。比如最开始它会引导你和模型做 brainstorming，把需求聊清楚；然后是计划技能，把任务拆成可执行清单；最后才是写代码和验证。这套流程对复杂任务特别有用，因为它解决了模型“拿到大需求就直接开写”的毛病。

安装方式就是标准的 GitHub 流程，clone 之后把技能目录放到~/.claude/skills/。它的一个特点是依赖较新的模型版本，因为里面的技能会要求模型执行一些高级的规划步骤，老版本模型理解不了。装完建议先用小任务跑一遍，确认流程能走通，再拿它去干真正的活。

3.2 前端开发常用 skills

前端是我自己用得最多的场景，这类技能在 GitHub 上数量也最多，我筛选下来常用的有这么几类。

第一类是组件生成。给它一个组件的需求描述，它按你预设的技术栈（React/Vue、TypeScript、Tailwind 等）生成完整组件代码，同时附带必要的 props 定义、样式方案和基础测试。这类技能的价值在于“输出风格可预期”，同一个技能生成的所有组件结构一致，代码风格统一。

第二类是代码审查和重构。技能里定义了审查清单，模型按清单逐项检查，比如类型安全、可访问性、性能隐患、命名规范，输出格式化的审查报告和修改建议。

第三类是样式和设计规范类技能。把 Tailwind 的配置规则、设计系统的色板、间距规范做成技能，模型写出来的 UI 就不会跑偏。

用这类技能需要注意一个点：不同团队的技术栈差异很大，别人写的技能不一定适合你。我在实际操作中的体会是，前端 skills 最适合的用法不是“直接用”，而是“当模板改”——下载一个组件生成技能，把它里面的技术栈、代码风格改成你们团队的，再用起来就非常顺手。

3.3 数学建模 / 华为杯场景的 skills 组合

数学建模比赛是 skills 的一个很有意思的应用场景。以华为杯这类研究生数学建模竞赛为例，整个比赛流程其实非常固定：读题、理解数据、建模、求解、结果分析、写论文。每一步都有大量重复性工作，非常适合技能化。

我见过不少人自己整理数学建模用的 skills，核心是三个方向。一个是数据分析类技能，负责数据清洗、缺失值处理、统计描述，省去每次比赛都要重复写的样板代码；一个是模型求解类技能，里面写好常见模型的代码模板，比如回归、分类、聚类、优化问题，以及对应的参数调优思路；还有一个是论文写作类技能，定义好 LaTeX 排版规范、图表格式、公式风格，让模型直接按竞赛规定输出论文片段。

在 Codex 这类工具里用数学建模 skills 时，我建议按“流程分段”来组织，而不是一个技能管到底。读题阶段用一个分析技能，建模阶段用一个建模技能，写论文阶段用另一个写作技能。每个技能只管一段，指令清晰，模型不容易被长流程带偏。

3.4 AI 漫剧制作的 skills 思路

AI 漫剧（用 AI 生成漫画、动画剧情内容）这两年也是一大热门，这里面的 skills 思路很有意思，因为它主要不是写代码，而是做内容生产。

漫剧制作最大的痛点是角色一致性。同一个角色在不同画面里要保持样貌统一，这光靠提示词很难稳定实现。技能可以做的事情是：把一个角色的外貌描述、LoRA 触发词、画风参数固化成一个标准模块，生成每个分镜时都调用它，保证角色描述一致。分镜脚本生成技能可以按剧情自动切分镜头、写动作描述、决定景别；提示词生成技能则把分镜描述转成文生图模型的完整提示词，带上画风、光照、质量后缀这些固定参数。

虽然这类技能不是传统意义上的编程技能，但它们完美体现了 skills 的本质——把可复用的流程固化下来。我自己写过一个给漫画生成用的“角色描述卡”技能，里面存了每个角色的详细特征描述和负面提示词，后面每次生成相关画面时都让模型先读这张卡，效果比手写提示词稳定很多。

3.5 找 skills 的常用源头

最后说说去哪找。我自己常用的几个方向：第一是 Anthropic 官方仓库，里面的 docx、pdf、pptx、xlsx 这几个文档处理技能质量非常高，属于“官方出品、经过大量测试”的类型；第二是各类聚合列表，比如 Awesome Claude Code，里面有人整理的技能清单；第三是直接在 GitHub 上搜claude skills、codex skills、opencode skills这些关键词，按 star 数和最近更新时间排序。不少技能库还提供网页版浏览界面，可以先把技能的说明和示例看一遍，决定要不要装，再回到命令行装对应的目录。

社区里还会冒出各种名字的合集仓库，比如 codex nature、cola skills、typesafe ai skills 这一类。这些合集质量参差不齐，我一般用三个标准判断：description 写得是否具体，有没有配套的示例和使用文档，最近一个月有没有更新。三条都不满足的直接跳过，省得装完一堆没用的技能污染你的环境。

4. 自己写一个 AI skill：从零到可用的完整流程

4.1 SKILL.md 的基本格式和 frontmatter

会装 skills 之后，下一步就是写自己的 skill。千万不要觉得这是很高级的事情，一个最小可用的 skill 就是一个带 frontmatter 的 markdown 文件。我先给一个最常见的模板：

--- name: react-component description: 在需要生成 React 组件时使用。根据描述创建组件文件、类型定义、样式和测试。 --- # React 组件生成 ## 流程 1. 分析需求，确定组件名称和 props 接口。 2. 创建组件文件，使用 TypeScript 定义 props。 3. 添加 Tailwind 样式，禁止使用内联 style。 4. 生成对应的测试文件，覆盖主要交互逻辑。 ## 输出要求 - 所有文件放到 `src/components/<组件名>/` 目录下。 - 组件使用函数式写法，导出默认组件。

frontmatter 里name是必须要的，格式一般为小写加连字符；description也是必须要的，它是模型判断触发时机的唯一依据。其他的字段像version、allowed-tools属于可选，刚开始不用管。

正文就是普通的 markdown，但写法和写给人看的文档很不一样。你要假设读者是一个记忆力很差但执行能力很强的实习生，它不会脑补你没写的任何规范，但只要你写清楚了，它就会严格照做。所以指令必须具体、可验证。

4.2 写指令时的关键细节

第一个关键细节是 description 的写法。很多人不理解它有多重要：模型在会话开始时就扫了一遍所有技能的 description，但它不会把正文全部读进去——只有当 description 命中当前任务时，它才去读正文。所以 description 至少要包含两层信息：什么时候用（触发条件）、它能干什么（能力边界）。

拿我前面那个 react-component 例子来说，“在需要生成 React 组件时使用”是触发条件，“根据描述创建组件文件、类型定义、样式和测试”是能力边界。这样模型遇到“帮我写一个表单组件”时就会触发，遇到“帮我修一下登录页的 bug”时就不会误触发。

第二个关键细节是指令的具体程度。像“注意代码质量”“保证代码风格”这种话等于没说，模型本来就会这么做。真正有效的指令是让模型执行可检查的动作：“组件文件放到 src/components/ 下”“props 必须用 TypeScript interface 定义”“每个组件至少有一个测试文件”。这些要求模型能逐条执行，你也能逐条验证。

第三个关键细节是给示例。模型擅长模仿格式，你给它一个“输入-输出”的示例，它就能稳定复现。示例不用长，一段代码加一段注释说明就够，但一定要覆盖典型的边界情况。

4.3 给 skill 配套脚本和模板

当 skill 的指令变得复杂时，纯 markdown 就不够用了。这时可以给 skill 加辅助文件。常见的做法有两个。

第一个是scripts/目录，放一些模型在执行过程中可以调用的脚本。比如你写了一个项目结构生成 skill，可以放一个generate-structure.sh脚本，指令里写明“执行 scripts/generate-structure.sh --name xxx 来生成目录结构”。这样模型就不仅是照着文档写代码，还能真正执行操作。

第二个是references/目录，放参考资料。比如写代码规范技能时，把团队的 ESLint 配置、代码范例、架构说明放进去，指令里写明“在审查代码前，先阅读 references/code-style.md 了解团队规范”。模型会按需读取这些材料，比全部塞进 SKILL.md 正文干净得多。

这里要注意一个容易踩的坑：辅助文件的引用路径。SKILL.md 里的相对路径是相对于技能目录的，引用的时候不要写成绝对路径，也不要开头加多余的目录层级。比如技能目录是.claude/skills/react-component/，里面有个references/example.tsx，那在 SKILL.md 里就写references/example.tsx，而不是写/Users/xxx/.claude/skills/react-component/references/example.tsx。

4.4 一个前端组件生成 skill 的完整示例

理论讲太多没意思，我直接放一个我实际在用的精简版技能。这个技能的目标是：模型在生成任何新的前端组件时，自动遵循我们团队的项目规范。

--- name: frontend-component description: 在项目里新建或重构 React 组件时使用。按团队规范生成组件、类型、样式与测试。 --- # 前端组件规范 ## 适用场景 - 新建页面组件或通用组件 - 重构已有组件 ## 执行步骤 1. 确认组件用途和 props，先用中文写一段组件职责说明给用户确认。 2. 在 `src/components/<组件名>/` 下创建目录。 3. 生成 `index.tsx`：函数式组件，使用 TypeScript，props 接口定义在组件同文件顶部。 4. 生成 `index.module.css`：使用 CSS Modules，类名语义化，禁止内联 style。 5. 生成 `index.test.tsx`：用 Vitest + Testing Library，覆盖渲染和主要交互。 6. 在 `src/components/index.ts` 中导出该组件。 ## 注意 - 组件文件名统一为 index.tsx，目录名即组件名。 - 涉及异步数据时，在组件内部使用自定义 hook，不要在组件中直接写请求逻辑。 - 所有组件必须处理加载和错误状态。

写好之后放到.claude/skills/frontend-component/SKILL.md里重启会话，然后随便让它建一个“用户列表组件”试试。你会发现它生成的目录结构、文件命名、样式方案全都符合规范，不需要你反复提醒。一次写清楚，后面无限次复用，这就是 skills 的杠杆效应。

4.5 写好后的测试与迭代

第一次写出来的 skill 大概率不会完美，这是正常的。我的迭代流程是这样的：新开一个干净会话，用最典型的场景测试；观察模型有没有正确触发、有没有严格按步骤执行；然后针对失败点修改——如果模型老是漏掉某个要求，就把那个要求放到步骤列表的前面，或者加上一个“最后必须检查”的清单项；再测，直到稳定。

一个很重要的经验：测试的时候不要用复杂任务，用最小场景。比如测试组件生成 skill，就让它生成一个最简单的 Button 组件。小场景最容易暴露执行链路的问题，等链路通了再上复杂案例。

5. 数学建模场景实战：把 codex skills 用起来

5.1 数学建模需要哪些能力

落到比赛场景，我先分析一下数学建模到底需要什么能力，这样才能理解技能该怎么配。

数学建模比赛是一个典型的“时间紧、任务重”的场景，通常只有几天时间，要完成从读题到成稿的全流程。拆开来看，核心能力就四块：数据能力（清洗、探索、可视化）、建模能力（把实际问题转化成数学模型）、求解能力（写代码跑数值实验）、写作能力（把结果按论文格式组织起来）。

这四个能力对应到 AI 编程助手，正好是四类 skills 的用武之地。难点在于这四类技能要能在一个项目中协同工作——数据清洗技能处理完的数据，建模技能要能直接用；建模技能跑出来的结果，写作技能要能引用。所以配置技能的时候不能只看单个技能，要看它们之间的接口。

5.2 推荐的 skills 组合与分工

基于上面的分析，我推荐的组合是“一个流程一个技能”，每个技能只干一件事，输出格式固定，方便衔接。

数据分析技能负责最前面的脏活累活。技能里定义数据探索的标准步骤：先看数据形状、缺失值比例、字段类型，再决定清洗策略；所有统计结果统一输出成表格，方便后续引用。这个技能的好处是逼着模型每一步都汇报结果，不会自己埋头跑半天然后丢给你一个结果。

建模与求解技能是核心。技能里存了常用模型的模板和选择标准，比如回归、决策树、聚类、整数规划分别适用于什么场景，每个模型的代码模板长什么样，调参的基本思路是什么。比赛时你不用临时教模型什么是 0-1 规划，它直接按技能里存的模板来。

论文写作技能负责格式化输出。技能里定义了竞赛论文的章节结构、LaTeX 模板的位置、图表编号和引用的写法、公式的排版要求，让模型直接生成可直接编译的论文片段。

5.3 用 skill 加速“读题-建模-求解-写作”全流程

把这套组合用起来之后，实际流程会变成这样：拿到赛题，先调用数据分析技能做数据探索，模型会自动输出数据质量报告，你花十分钟看完就知道数据有哪些坑；接着调用建模技能，把你对问题的理解告诉它，它会按技能里的模型模板搭出求解框架，你只需要修正模型假设；求解结果出来后，调用写作技能，模型按论文模板生成对应章节，图表引用和公式排版都是现成的。

我实际测试下来，最花时间的反而是“读题和建模”的部分，因为需要人的判断；而最花力气的“数据处理和格式化写作”部分，技能能省掉大量时间。这也是我个人的一个体会：skills 不能替代思考，但能把你从重复劳动里解放出来，让你把时间砸在真正需要人的地方。

6. Skills 的维护与清理：装多了怎么办

6.1 为什么 skills 会“装废”

skills 装多了之后，第二个隐藏问题就会出现：不生效了，或者乱触发。很多人以为是工具坏了，其实往往是技能库太乱导致的。

原因很简单。第一，模型在每个会话开始时都会扫描所有技能的 description，技能多了，description 之间的边界就容易模糊。两个技能都写着“生成 React 组件”，模型就不知道该用哪个，或者干脆都不触发。第二，技能目录里堆了一大堆过时的、废弃的技能，这些技能里的指令可能和当前项目规范冲突，模型调到哪个算哪个，行为自然不稳定。第三，技能描述写得含糊，触发条件太宽，模型遇到什么任务都想套一下，结果干活风格完全错乱。

6.2 社区分享的清理思路

关于清理 skills，我留意到 tibo 之前在分享里讲过一套思路，核心就四个字：定期淘汰。大意是：不要把所有技能都当宝贝留着，每隔一段时间就回头看一遍自己的技能库，哪些技能是最近两周真正用过的、哪些装完就再也没碰过；长期不用的要么删，要么归档到一个单独的目录里，别让它继续参与扫描。这个思路我很认同，和我自己清理电脑上软件的习惯一模一样——装的时候觉得“以后可能用得上”，实际上三个月都不会打开一次，留着只是增加噪音。

基于这个思路，我自己的清理动作更具体一些。每个月会做一次技能盘点：列出所有已安装技能，按“高频使用”“偶尔使用”“从不使用”分类；从不使用的一律删掉，偶尔使用的看是否被高频技能覆盖，覆盖了也删；然后审视每个高频技能的 description，看有没有和别的技能重叠，有重叠就精简。

6.3 我的个人维护习惯

除了定期清理，我还有几个从实践中养成的维护习惯。

命名尽量语义化且唯一。技能名就是触发时的标识，不要用skill1、new-skill这种名字，也不要用含义太宽泛的词。我习惯用“领域-用途”的格式，比如frontend-component、math-data-analysis，一眼就知道它是干什么的，也方便在列表里辨认。

新技能先试用再转正。新下载的技能我先放到全局目录用一两个星期，确定好用且没有副作用，才保留；如果发现它和现有的技能冲突，或者产出质量不稳定，直接删掉，别指望它以后会变好用。

最后，项目级技能要跟着代码一起 review。项目级技能是团队资产，改的时候要像改代码一样慎重，最好在 PR 里一起提。技能里的指令变了，所有成员的行为都会变，这件事要有流程约束。

7. 常见问题与排查技巧实录

7.1 Skills 不生效怎么办

这是被问得最多的问题。我的排查顺序是：先确认目录位置对不对，再看文件结构对不对，再看 description 是否触发。

具体操作：第一，用/skills列表命令看技能有没有被扫描到；如果列表里根本没有这个名字，说明目录位置错了或者 frontmatter 解析失败了，返回去检查路径和 YAML 格式（比如 name 拼写、缩进问题）。第二，如果技能在列表里但任务不触发，问题几乎一定出在 description 上——它写得太模糊，或者触发条件和你的真实任务对不上。改 description 比改正文更有效。第三，开--debug看日志，确认模型是否真的读取了技能文件；如果读到了但没执行，说明正文指令不够具体，模型执行时无法判断该怎么做。

7.2 多个 skill 冲突怎么处理

技能多了之后，最典型的冲突是“两个技能都能处理同一个任务”。处理方法我在清理那节说过，重新梳理每个技能的边界，让它们的 description 尽量不重叠。比如一个技能管“生成新组件”，另一个技能管“审查现有组件”，边界就很清晰；如果两个都写着“处理组件”，那必然冲突。

另一个冲突场景是项目级和全局级同名技能。这种我建议保留项目级的，把全局的重命名或删除，避免工具加载时不确定用哪个。处理好之后，在日常使用中要留意模型的表现，一旦出现行为和以前不一致，优先怀疑技能冲突。

7.3 模型不按 skill 走怎么办

有时候技能明明加载了，模型也提了技能名，但执行到一半自己“自由发挥”，不按技能里的步骤来。这种情况在复杂技能上特别容易出现。

我的经验是：把指令写得更“可验证”一些。每一步都给一个明确的输出物或检查点，比如“每一步执行完后，输出一行说明当前进度的注释”。这种要求让模型的执行过程变得更透明，偏离流程时你能及时看出来。另外，在技能开头加一行强约束，比如“必须严格按照本技能定义的步骤执行，不得跳过或自行调整顺序”，对多数模型是有效果的。如果还是不行，就是模型版本太旧，对长指令的遵循能力不够，升级模型或者简化技能文本。

7.4 其他高频问题速查表

我把其他几个常见问题整理成一张表，方便对照：

最后再分享一个小技巧：如果你对某个技能的行为不满意，先别急着删，试试改它的 description 而不是正文。很多时候模型不按你的预期走，不是因为执行能力不行，而是因为它根本没意识到“这个任务该用这个技能”。description 就是那个“意识的开关”，把开关调准了，很多问题迎刃而解。

我自己折腾 skills 这段时间，最大的体会是：别一次装几十个技能，先精挑细选两三个，真正用顺了再扩展。技能库和衣柜一样，在精不在多。你真正高频使用的技能，可能就那么五六个，把它们维护好，比装 50 个吃灰的技能有用得多。