企业官网建设流程全解析

1. 先搞清楚“不执行”到底卡在哪一层

Skill 写好了，AI 却像没看见一样，该走的流程不走，该调的接口不调，该输出的格式全乱。这个问题我前前后后踩了不下十次坑，从最早的 Claude Code 自定义 skill，到后来自己搭 agent 框架做多步任务编排，几乎每一种“技能加载失败”的姿势都见过一遍。先说结论：绝大多数情况下，问题不在模型能力，而在技能本身的结构、触发条件、上下文注入方式，或者运行环境的配置上。这四件事按顺序查一遍，能解决九成以上的“AI 不按要求执行”。

这篇文章适合两类人看。一类是刚接触 skill 机制、在 Claude Code 或者类似 agent 工具里写自定义技能的开发者，另一类是已经在做 agent 项目、发现技能时灵时不灵、想系统排查的工程师。我会把每个排查点的原理讲清楚，再给可直接复现的操作步骤和参数，最后附上我自己的避坑清单。全文基于实际项目经验，不是文档翻译。

先对齐一个基础认知。所谓 skill，本质上就是一段结构化的指令包，它告诉 AI 在什么场景下、按什么顺序、用什么工具、输出什么格式。它和普通的 prompt 最大的区别在于：skill 通常带有触发条件（什么时候加载）、执行步骤（怎么做）、依赖声明（需要哪些工具或权限）和输出约束（结果长什么样）。任何一环出问题，AI 都会表现得像“没看到这个 skill”。

我习惯把排查分成四层，从外到内依次是：加载层、触发层、上下文层、执行层。下面逐个拆。

2. 第一件事：Skill 到底有没有被加载进来

这是最容易被忽略的一层。很多人写完 skill 文件，往目录里一放，就默认 AI 能读到。实际上不同工具的加载机制差别很大，Claude Code、VS Code 插件、自建 agent 框架各有各的规则。

2.1 加载路径和文件命名规则

以 Claude Code 为例，skill 通常放在项目根目录下的特定文件夹里，文件名和扩展名都有讲究。我见过最常见的错误是：文件放对了目录，但命名不符合规范，导致扫描时被直接跳过。比如有的工具要求 skill 文件必须是特定后缀，有的要求文件名全小写加连字符，有的要求每个 skill 必须有一个同名的元数据文件。

排查方法很直接：先确认你的工具到底从哪些路径加载 skill。这个信息一般在工具的配置文档或者启动日志里。Claude Code 启动时如果开了 verbose 模式，会打印它扫描了哪些目录、加载了哪些 skill。如果你在日志里看不到自己的 skill 名字，那后面所有排查都是白费。

# 以 Claude Code 为例，启动时观察加载日志 claude --verbose # 或者在项目里检查 skill 目录结构 ls -la .claude/skills/

注意：不同版本的 Claude Code 对 skill 目录的约定可能不同，升级后一定要重新确认路径。我就遇到过一次在线升级最新版本之后，skill 目录从旧路径迁移到新路径，结果所有自定义 skill 集体失效。

2.2 依赖和权限声明缺失

Skill 被扫描到了，不代表能被正常使用。如果 skill 里声明了需要调用某个工具、访问某个文件、执行某条命令，但运行环境没有对应权限，加载阶段就可能静默失败。这种失败最坑，因为工具往往不报错，只是把 skill 标记为“不可用”，然后 AI 就当作没这个技能。

我的做法是：每写完一个 skill，先做一个最小可执行验证。把 skill 简化到只剩一条最简单的指令，比如“输出 hello”，确认它能被加载和执行，再逐步加回复杂逻辑。这样能把加载问题和逻辑问题彻底分开。

2.3 一个真实的加载失败案例

我之前写过一个用于代码审查的 skill，逻辑很完整，但死活不生效。查了两个小时，最后发现是 skill 文件头部的元数据里，description字段写成了中文，而那个版本的加载器对非 ASCII 字符处理有 bug，直接导致整个文件解析失败。改成英文描述后立刻正常。这件事给我的教训是：skill 的元数据部分尽量用最保守的格式，别用特殊字符、别用花哨的写法，等确认能加载了再考虑优化可读性。

3. 第二件事：触发条件是不是根本没命中

Skill 加载进来了，但 AI 没用它，第二个要查的就是触发条件。这是“AI 不按要求执行”里占比最高的原因，没有之一。

3.1 触发描述写得太窄或太宽

每个 skill 都有一个触发描述，告诉 AI 什么情况下该用这个技能。这个描述写得好不好，直接决定命中率。写得太窄，比如“当用户要求用 Python 3.11 在 Linux 环境下处理 CSV 文件时使用”，那稍微换个场景 AI 就不认了。写得太宽，比如“处理任何文件时使用”，又会导致 AI 在不该用的时候乱用，反而干扰正常流程。

我的经验是：触发描述要覆盖“意图”而不是“具体操作”。比如你要做一个数据清洗 skill，触发描述应该围绕“用户需要清洗、整理、规范化数据”这类意图，而不是绑定到某个具体文件格式或工具。同时，在描述里列出几个典型的触发短语，能显著提高命中率。

# 触发描述示例：覆盖意图，列举典型场景 name:># 粗略估算上下文 token 占用的思路 def estimate_tokens(text): # 英文约 4 字符 1 token，中文约 1.5 字符 1 token # 这里给一个保守估算 return len(text) / 3 skill_content = open("skill.md").read() history = get_conversation_history() tool_output = get_last_tool_result() total = estimate_tokens(skill_content + history + tool_output) print(f"预估占用 token: {total}") # 如果接近模型上限的 80%，就要考虑精简

4.2 指令的优先级和位置

AI 对上下文中不同位置的信息敏感度不一样。放在最前面的指令、放在最后的指令、以及被明确标记为“必须遵守”的指令，权重更高。如果你的 skill 关键约束藏在中间一大段文字里，AI 很可能忽略。

我的做法是：把最关键的输出格式约束和禁止事项，放在 skill 的开头和结尾各强调一次。开头告诉 AI“这个 skill 的核心目标是什么”，结尾再重申“输出必须满足哪些硬性要求”。中间放具体的执行步骤。这样即使中间部分被部分忽略，头尾的约束还在。

4.3 工具返回结果的污染

如果 skill 执行过程中调用了工具，工具返回的内容也会进入上下文。有些工具返回一大堆无关信息，把 skill 的后续指令“淹没”了。比如你让 AI 查一个文件，工具返回了整个目录的列表，AI 的注意力就被带偏了。

解决办法是在 skill 里明确要求工具调用的输出处理方式。比如“调用搜索工具后，只提取前 5 条最相关结果，忽略其他内容”。这样能主动控制进入上下文的噪声量。

5. 第四件事：执行阶段的工具调用和输出约束

前三层都过了，AI 确实在按 skill 执行，但结果还是不对。最后一层要查的是执行本身——工具调用是否正确、输出格式是否被遵守。

5.1 工具调用的参数错误

Skill 里写了“调用 X 工具完成 Y”，但 AI 实际调用时参数传错了。这种情况在工具接口复杂、参数多的时候特别常见。AI 可能把参数名记混，或者把可选参数当必填，导致调用失败，然后它就自己编了一个结果。

排查方法是打开工具的调用日志，看 AI 实际传了什么参数。Claude Code 和一些 agent 框架都支持打印工具调用详情。对比 skill 里的预期和实际调用，差异一目了然。

# 查看工具调用日志的通用思路 # Claude Code 中可以通过调试模式观察 claude --debug # 自建 agent 框架一般在日志里记录 tool_call 和 tool_result grep "tool_call" agent.log | tail -20

5.2 输出格式约束不够硬

“请用 JSON 格式输出”这种软约束，AI 经常不遵守，尤其是任务复杂的时候。它可能输出 JSON 外面包一层解释文字，或者字段名对不上。要让输出格式真正被遵守，得用硬约束：给出完整的 schema、给出正例和反例、明确说明“只输出 JSON，不要任何其他文字”。

# 输出约束的写法对比 # 软约束（容易失败） output: 请用 JSON 格式返回结果 # 硬约束（成功率高） output: | 只输出一个 JSON 对象，不要包含任何解释文字、markdown 代码块标记或前后缀。 格式必须严格如下： { "status": "success" | "failed", "items": [{"name": string, "value": number}], "summary": string } 错误示例：在 JSON 前后添加 "好的，结果如下：" 这类文字。

5.3 多步任务的中间状态丢失

如果 skill 包含多个步骤，AI 执行到第三步时可能忘了第一步的约束。这在长任务里很常见。解决办法是在每一步开始时，重申当前步骤的目标和约束，而不是只在开头说一次。我管这叫“步骤级上下文锚定”，实测能显著降低长任务的跑偏率。

6. 常见问题速查表与避坑清单

把上面四层排查浓缩成一张速查表，遇到问题按顺序过一遍。

几个我踩过的坑，单独拎出来说。第一，别在 skill 里写太长的背景介绍，AI 不需要你解释这个技能为什么重要，它需要的是清晰的执行指令。背景介绍占的每一个 token，都是从执行指令那里抢来的。第二，skill 的版本管理很重要，我建议用 git 管理 skill 文件，每次改动都提交，出问题能快速回滚对比。第三，测试 skill 要用真实任务，别只用构造的简单用例，真实任务的复杂度和噪声才是检验 skill 的唯一标准。

还有一个容易被忽略的点：不同模型对同一个 skill 的执行效果可能差很多。同一个 skill，在 Claude 上跑得好，换到别的模型可能就崩。如果你的 agent 支持多模型切换，skill 要针对主力模型做优化，同时给其他模型留降级方案。

7. 我个人的排查顺序和工具习惯

最后分享我自己的排查流程，基本是固定动作。第一步，看加载日志，确认 skill 在不在。第二步，跑触发测试集，确认命中率。第三步，开调试模式跑一个真实任务，看上下文占用和工具调用。第四步，检查输出格式约束。这四步走完，九成问题都能定位。

工具上，我习惯在项目里放一个skill-debug.md，记录每个 skill 的加载状态、触发测试结果、已知问题和修复记录。这个文件不参与运行，纯粹是排查时的参考。时间长了你会发现，很多问题是重复出现的，有个记录能省大量时间。

Skill 机制本身还在快速演进，不同工具的实现差异很大，今天能用的写法明天可能就变了。所以比起记住某个具体写法，更重要的是理解这四层排查的逻辑：加载、触发、上下文、执行。不管工具怎么变，问题永远出在这四层里的某一层。把这套排查思路内化，比背任何文档都管用。