开发AI Agent技能时要注意150行限制的实用技巧

📄 代理工具框架中的技能

很多人都不知道这一点（我也是最近才知道）：大多数代理工具框架在启动时会加载你技能的描述。Claude Code就是这么工作的。

而人们通常不知道的是，即使你在框架内显式调用某个技能，或是AI判断出要使用某个技能，它通常也只读取技能的前150行（用来了解如何使用它，或是判断它是否适用于当前要完成的工作）。

因此，你必须把调用技能时需要运行的必填部分整理成表格，放在前150行里，这点非常重要。如果你把某种必填指令放在150行之后，它可能会被完全漏掉。如果你在提示里描述想要使用提供的Python脚本或模板，它也可能超出这150行的范围，永远无法被正确调用。

如果你在前150行写一个技能操作目录，并标记出哪些是必填项（或者说明如果用户调用了该技能，就必须阅读整个技能上下文和所有引用），你的技能就会更可靠。我们现在用markdown清单来做这件事。

我很喜欢这个发现，但我不认为每行带点markdown语法的10行内容，会在直接调用时消耗太多上下文配额。经我们测试，把它做成markdown格式的清单效果好得多，这样AI就能意识到这些是需要完成的任务，而不只是从别的地方拉来的清单什么的。

我们这种格式是模仿代理工具框架处理长复杂问题时实际生成思维链的方式，它们本身就会用markdown清单来执行任务。Manus和Maestro教会了我这个技巧。

示例：

描述通常是2-5句话加一些参数，启动时会全部读取。说实话这通常没问题。你可以用--safe-mode来让Claude不加载这些内容。这个模式会在启动时排除所有技能、记忆、插件、钩子和Claude.md上下文。

我们用的另一个技巧是创建额外的技能文件夹：/skills /skillsa /skillsb。Claude启动时只会加载/skills，但技能本质上就是提示……所以如果我们告诉Claude「使用/skillsa里的X技能」，它完全可以正常工作。

这是一篇很棒的软件工程论文，里面有很多很棒的发现。如果你问我，我们写超过150行的技能的时候是怎么做的，我能给你讲一整篇论文，而且大部分内容都会和这篇论文的结论一致。唯一的区别是，我们的技能是为网络安全工作流和方法论构建的，大多时候它比起软件工程更偏向运营工作。这篇论文其实没有覆盖这个领域的特殊性和范围差异，所以我不认为它能完全适用。

我认为只读150行通常是为了节省上下文，我完全支持这种做法。但在运营工作流和方法论中，我需要AI完全理解整段文本。

我不认为代理技能和它们的架构设计有什么问题。我觉得很多人都不明白，它们的架构完全是自定义的，并不死板。你真的可以随便创建一个文本文件，把指令写成你想要的任何格式。它不必须是YAML格式，你可以直接告诉Claude Code子代理把它当作技能用。有时候Claude Code的技能创建工具会出错，不遵循YAML格式，结果就是这样。它本质上就是给子代理的一个文本文件里的提示，可能还附带一些文件夹里额外的工具和引用。