写这篇东西的起因是我在某次大项目里把Claude Code用到了极限。代码库接近二十万行涉及五个子项目Agent频繁出现三类问题上下文窗口被无关信息塞满、指令理解时好时坏、同一个功能在A模块能用换到B模块就失效。折腾了大半个月最后解决我这个问题的不是更多system prompt不是更长的规则文档而是把整个编码Agent拆成了一个个独立的、按需加载的模块化组件——也就是标题里提到的Agent Skills架构。这篇文章就围绕这套架构的设计逻辑、核心组件实现和实际踩坑过程展开给正在跟Agent编码工具较劲的人一个可以复用的参考。1. 为什么需要Agent Skills从单体Agent到模块化组件1.1 单体Agent的痛点先复现一下大家最常见的Agent使用姿势把一堆规则、工具说明、项目背景全塞进system prompt希望模型变成一个全知全能的“项目内行”。这种方法在小项目上看着还行但项目一旦膨胀问题很快就暴露。第一个问题是上下文稀释。Claude的上下文窗口是有限的你塞了三千行规则和描述它在具体处理某个文件时就很容易“忘掉”当前真正相关的约束。典型表现是你问一个数据库迁移逻辑它忽然从某个偏门的API文档里找出一段不太相关的内容来“丰富回答”。这不是模型笨是人类把上下文信息密度的优先级排错了。第二个问题是耦合过重。所有知识都集中在同一个prompt里意味着改任何一处小规则都要把整个提示词重新测一遍。我遇到过最头疼的情况是新增一个错误码规范说明后Agent对原先某个执行命令的偏好突然变了——没有任何逻辑上的解释纯粹是文本长度和位置变化导致的注意力偏移。单体架构就是这样牵一发而动全身。第三个问题是复用性差。同一个团队在另一个仓库可能要处理几乎一样的需求但因为规则全部写在某个项目的system prompt里新项目根本没法快速继承。只能复制粘贴然后手动删改差异部分。一次两次能忍次数多了就完全是时间黑洞。1.2 Skills与Tools、Prompts的边界Agent Skills这套思路本质上就是解决上面三个问题而生的。很多人容易把Skills、MCP Tools和普通的Prompts搞混我一开始也在这上面绕了弯路先理清三者的边界。Tools或MCP Tools是Agent执行动作的抓手。它是显式的API接口Agent决定调用、传入参数、拿到返回值典型例子是文件读写、代码查询、执行shell命令。Skills则更像一组“条件触发的能力包”包含了触发条件、执行思路、相关脚本和约束说明Agent在回应某个任务时会根据自身判断动态决定是否加载这个包。两者最关键的区别是Tools是确定性接口Skills是启发式指令集。Prompts则是大家都熟悉的那套文本指令。但传统的Prompts是被动且全局的它常驻上下文无论当前任务是否相关都在消耗tokenSkills是主动且按需加载的只有当Agent判断当前任务匹配某个技能时才把它读入上下文。这个差别非常关键直接决定了上下文窗口的利用效率。我个人的比喻是传统Prompts就是岗位说明书永远摆在桌上Skills是工具箱里的专用工具用得到的时候才拿出来用完就放回去。单独看每份说明书都很有用但当你有二十份说明书全部摊开时桌面上就没有干活的地方了。2. 架构设计SKILL.md入口与按需加载2.1 目录结构与核心规范Agent Skills架构里最核心的约定是每个技能都包含一个名为SKILL.md的入口文件。在Claude Code的环境里通常会把这些技能放在skills目录下每一个子目录代表一个独立技能。我常见的目录布局如下skills/ ├── database-migration/ │ ├── SKILL.md │ ├── scripts/ │ │ ├── generate_migration.py │ │ └── verify_schema.py │ └── templates/ │ ├── migration_template.sql │ └── rollback_template.sql ├── log-analysis/ │ ├── SKILL.md │ └── scripts/ │ └── analyze_log.py └── code-review/ ├── SKILL.md └── rules/ ├── security_checks.md └── style_checks.mdSKILL.md就是技能说明书也是整个模块的入口。Claude Code会先扫描这个文件根据其中的描述判断“当前任务是否应该加载这个技能”。这个扫描和判断的过程消耗的是轻量级的元数据而不是完整的技能内容。这里有一个很多初学者容易忽略的点SKILL.md的标题和首段描述一定要写清楚这个技能的边界和触发条件。因为Agent会把这个文件的关键信息提前用于技能匹配匹配不上就不会往下读取细节。用大白话说这份文件既是你写给Agent的使用说明也是Agent用来做“检索召回”的索引条目写得太笼统召回就极其不稳定。2.2 元数据与依赖声明SKILL.md开头通常会有一段YAML格式的frontmatter用于声明该技能的元信息。这不是强制标准但实际用下来收益非常大尤其在技能数量多、需要依赖管理的时候。我常用的是以下几项--- name: database-migration-toolkit description: 生成和验证数据库迁移脚本检测破坏性变更适用于表结构修改、索引调整和数据回填任务。 version: 1.2.0 depends_on: - schema-inspector - sql-linter tags: - database - migration - sql ---其中description是Agent判断是否触发该技能的关键。它不能写成“数据库迁移相关的操作”而要写成有明确边界的行为描述例如“适用于表结构修改、索引调整、数据回填任务”。我在初版就吃过亏description写得太文艺“帮助你理解数据库变更的方方面面。”结果Agent每次遇到SELECT查询都想去加载这个技能既浪费token又引入噪声。depends_on字段可以声明当前技能依赖的其他技能或工具。在设计成体系的架构时这个字段特别有用。比如一个数据库迁移技能它可能要依赖一个schema-inspector来读取当前表结构依赖一个sql-linter来做语法检查。声明依赖后Agent在执行时就能提前规划加载顺序而不是临时东翻西找。2.3 上下文窗口的优化逻辑按需加载带来的最显著收益就是上下文窗口腾出了空间。我不止一次实测过同一个任务采用Skills架构后执行同样规模的需求Agent有效上下文的利用率明显提高因为常驻prompt里只保留了核心的、跨任务通用的少量指令和约束。上下文优化有一个非常实用的小技巧把技能的“读取顺序”和“读取深度”分开设计。SKILL.md的主体部分只包含摘要和入口指令具体细节放在scripts/或者references/目录里。Agent优先读取SKILL.md如果判断确实需要执行这个技能再按需读取其中的辅助文档。这个做法有点像是给Agent一个“图书目录”先看章节标题和简介再决定要不要翻开正文。如果一开始就把整本书的内容塞给Agent上下文很快就会被无关细节填满。我见过有些团队把整个部署手册写进某个SKILL.md里导致Agent在执行任何代码审查时都带着一套完整的Docker部署文档——这后果不堪设想。3. 核心组件实现与原理3.1 技能注册表与路由分发一套完整的Agent Skills架构不仅仅是SKILL.md文件的堆砌。当技能数量达到几十个时就需要一个显式的注册表来管理它们以及一个路由分发机制来把任务匹配到正确的技能上。在我的实现中注册表就是一个简单的JSON或YAML索引文件记录了每个技能的路径、名称、触发说明、依赖关系。Claude Code在会话开始时加载这个索引维护一张“技能清单”。路由分发的核心是匹配策略先基于技能描述做语义匹配再做约束检查是否满足依赖、是否适配当前仓库语言。举一个具体场景。一个Python项目和一个Go项目共享模型训练技能集但它们的构建工具链完全不同。路由分发时就需要把“当前项目的语言类型和构建工具”作为约束条件来判断某个技能是否应该被启用。如果技能描述里不写清楚适用语言两个项目就都会错误加载然后产生完全不可控的行为。我这里为了方便管理做了一个简单的注册表示例skills: - name: python-packaging path: skills/python-packaging match_rules: project_language: python description: 打包与发布Python库处理pyproject.toml配置与版本号管理。 - name: go-module-health path: skills/go-module-health match_rules: project_language: go description: 检查Go模块依赖健康状态分析go.mod与vendor目录。路由分发逻辑本身不复杂难的是规则的精确度。规则写得过细Agent会漏判该用的技能规则写得过粗Agent会不分场景地乱用。3.2 参数解析与验证技能设计的另一个关键模块是参数解析。与传统Tools不同的是Skills往往不是被显式调用的而是由Agent根据语义自行决定如何使用所以参数解析通常用的是自然语言到结构化数据的转换。这听起来自由度很高但隐患也在这里Agent可能生成不一致的参数格式。举个例子一个日志分析技能需要接收“时间范围”Agent上一轮生成的是start_time2024-01-01 00:00:00下一轮可能变成start: 2024-01-01。虽然模型本身有很强的格式推断能力但依赖这种隐式的一致性终究不如显式校验来得稳妥。因此我的每个技能脚本里都会有一段参数验证逻辑。无论是Python脚本还是Shell脚本入口处都定义好参数的合法类型、允许范围、默认值对缺失参数和类型不匹配的情况给出清晰错误提示。这一步是“伪装成工具的Skills”和“真正可靠的能力模块”之间的分水岭。3.3 执行沙箱与安全检查Agent Skills里经常要执行脚本比如生成代码、修改数据库、批量重命名文件。这些操作如果直接放权一个描述写得有歧义的技能就可能酿成事故。我自己最难忘的教训是一个用于“清理过期临时文件”的技能由于正则表达式写得不严谨差点把项目里的资源文件当成临时文件给删了。从那之后我在所有涉及破坏性操作的技能脚本里都加了三道防线dry-run模式脚本默认只输出将要执行的操作不真正执行只有显式传入--apply参数才真正生效。路径白名单脚本内部校验所有操作路径必须位于项目根目录或指定子目录不满足直接终止。操作日志在运行目录保留一份完整的操作记录方便事后追踪和回滚。这三道防线不依赖Claude Code提供任何额外机制纯粹是靠技能Shell脚本自身实现的。架构上它们是技能的外壳但实际作用相当于给Agent手上拿了把带保险栓的工具既不妨碍执行又能防止误伤。这里再补充一个与执行安全强相关的心得依赖链不要无限拉长。技能之间尽量不要形成复杂的级联调用避免一个技能在执行中调用另一个技能再调用另一个技能。这样的调用链一旦在某个中间环节出问题你很难定位是哪一个技能的规则或者脚本导致了失败。我尽量控制每个技能最多依赖一至两个其他技能或工具保持依赖树浅平。4. 从零构建一个Agent Skill完整实操理论知识聊了不少下面用一个具体的例子完整演示怎么从零构建一个“SQL迁移生成”技能。这个例子的真实性是我从自己项目中抽出来的只不过名称和细节稍微泛化。4.1 定义技能目标与原子化拆分第一步不是写代码而是写目标。任何技能设计的第一道工序都是界定它的能力边界。我当时给自己定的目标是这个技能只负责“基于数据库当前结构生成差分迁移脚本”。它与schema检查有关但不负责数据备份它与SQL优化有关但不负责查询改写。这种边界感非常重要。很多失败的技能都是因为想“什么都做一点”结果描述写得模棱两可触发时机不稳定执行质量也很差。原子化拆分的标准很简单如果一个技能描述里需要三个连续的“并且”那大概率它还可以继续拆分。用这个标准拆分后我的SQL迁移技能和“schema-inspector”读取表结构、“sql-linter”SQL语法与风格检查天然形成了依赖关系但彼此不交叉。迁移技能负责生成迁移文件它调用schema-inspector获取当前结构生成完毕后交给sql-linter检查。这种职责分离让我可以单独更新任何一个模块而不影响其他模块。4.2 编写SKILL.md与辅助脚本接下来是最核心的SKILL.md编写。我当时的初版长这样--- name: sql-migration-generator description: 在schema-inspector提供当前表结构后生成跨版本的SQL迁移脚本。适用于添加字段、修改字段类型、新增索引、数据回填等场景。 version: 1.0.0 depends_on: - schema-inspector - sql-linter --- # SQL迁移生成器 ## 使用场景 这个技能用于生成数据库表结构变更的迁移脚本包含正向迁移和回滚脚本。 ## 执行流程 1. 先调用schema-inspector技能获取当前数据库表结构快照。 2. 对比目标表结构与当前表结构的差异。 3. 生成迁移SQL保存到migrations/目录下命名采用{version}_{description}.sql。 4. 调用sql-linter对生成的脚本做语法检查。 ## 输出规范 - 正面迁移输出到 migrations/{version}_{description}.sql - 回滚脚本输出到 migrations/{version}_{description}.rollback.sql - 所有表结构变更均需包含IF NOT EXISTS或IF EXISTS条件保证可重入。这段描述看似简单但里面包含了好几个精心设计过的关键短语。比如“在schema-inspector提供当前表结构后”是在暗示Agent必须先加载依赖“采用{version}_{description}.sql”是在给Agent强约束命名规范避免它自创一套行为。技能描述中最重要的不是文采而是约束密度。辅助脚本方面我当时写了一个generate_migration.py用来解析新旧两份schema定义并输出差异SQL。实际执行时Agent会调用这个脚本获取中间结果再基于结果调整最终迁移内容。这个脚本不需要做得完美只需要能稳定输出结构化数据给Agent提供决策依据。4.3 导入与调试技能文件写好之后把它放进Claude Code的skills目录重启会话。第一次执行时我直接就调用了技能结果不出所料出了状况——Agent虽然识别了技能但在生成迁移脚本时没有先读取schema-inspector的结果而是自己“猜测”了一份表结构。这就是缺少调试经验时最容易踩的坑。我以为技能描述写得够清楚了但Agent的路径规划优先级跟我想象的不完全一致。解决方案也很直接在SKILL.md的执行流程里把“调用schema-inspector”从第一步改成了“必须先读取schema-inspector输出的schema快照文件路径为.cache/schema_snapshot.json若该文件不存在则强制中止”。把隐式依赖改成显式路径引用后问题立刻消失。这条经验我后来反复用了很多次。Agent Skills里的指令越“具体”就越可靠越“自然语言化”就越容易出现歧义。这里的“具体”不是指限制Agent的发挥空间而是指把数据来源、输出路径、判断节点这些确定性信息写清楚减少模型做不必要推测的空间。5. 调试与问题排查实录5.1 技能不被识别的排查技能文件放在目录下但Agent就是不调用它。这个现象很常见原因通常有三类。第一类是SKILL.md的描述与任务语义匹配度不够。我之前提到过的把description写得太宽泛或太文学化都会造成召回失灵。处理方式是检查description是否用了任务导向的动词和明确的对象比如“生成迁移脚本”“检查模块依赖”“分析登录日志”而不是“处理数据库事宜”“帮助理解项目结构”。第二类是路由规则冲突。多个技能的description描述范围有重叠Agent在匹配时就可能犹豫不决最终选了另一个技能。这个在技能数量超过十几个之后会频繁出现。排查方法是输出Agent的决策路径看它在选择技能时究竟读到了哪些候选内容再针对性调整描述边界。第三类是依赖缺失或声明不完整。如果depends_on里引用了尚未安装的工具或未定义的技能Agent可能在隐式校验环节悄悄跳过了这个技能。排查时先检查依赖链再去看技能脚本是否在沙箱环境中能独立运行。5.2 上下文污染与知识漂移技能加载后有时Agent的表现反而变差一个很典型的原因是上下文污染。一个技能里包含了大量历史案例、示例代码和不必要的背景介绍这些内容被整体读入上下文后会干扰Agent对当前任务的判断。我的一款技能初版为了“帮助模型理解”塞了五六个详细的例子结果每次加载它之后Agent都倾向于复述或模仿示例结构而不是按实际需求生成方案。这个现象非常狡猾因为它不表现为报错而是表现成“输出结果风格异常统一”。解决方法是严格控制SKILL.md的示例数量最多保留一个最小示例其余细节全部移到references/目录。Skill骨架文件只负责告诉Agent“这是什么、怎么执行、输出是什么”不充当“教材”。教材内容按需读取否则教学本身就是一种污染。5.3 并发与执行顺序问题在多个Agent并行执行的场景里技能脚本之间的数据一致性和执行顺序容易出问题。比如两个Agent同时调用同一个schema-inspector技能生成同一份快照文件就可能出现互相覆盖导致其中一个Agent读到的是旧数据。这类问题的排查与解决思路给每个技能执行过程分配独立的工作目录内部保存的中间文件使用任务ID隔离。如果技能里要用到共享资源写操作必须加锁或者使用原子写入。我在这里想强调的是不要觉得Agent编程工具的并发场景少实际项目里多个Agent实例协同工作时这类竞态问题几乎是必然的。以下是我整理的一份排查速查表方便大家遇到问题时对照症状可能原因排查重点常见解法技能完全不被调用description与任务不匹配查看技能匹配日志重写description明确用行为动词技能偶尔被调用与其他技能描述边界重叠检查候选技能排序缩小description范围增加负向边界调用后输出质量差上下文被示例污染查看加载内容的token分布精简SKILL.md示例细节下移到references生成路径或命名不规范输出规范约束不足查看SKILL.md中输出规范段补充具体的命名模板和目标路径脚本执行失败但无报错信息参数验证缺失检查脚本入口参数处理补全参数类型校验和默认值多个Agent并行输出不一致共享状态竞争检查中间文件路径隔离工作目录用任务ID做文件后缀6. 组件维护与演进方向6.1 版本管理与兼容性技能也是代码也需要版本管理。我对技能的变更做了明确的阶段控制SHALL必须满足的约束、SHOULD强烈建议遵循的规则、MAY可选的建议。这三档在SKILL.md里用明确的标记区分对Agent来说相当于给了它一个决策优先级的锚点它知道哪些执行约束是没有妥协空间的哪些只是理想偏好。在版本兼容上要格外注意依赖声明。当某个技能修改输出格式后依赖它的下游技能可能悄悄失效。比如我把schema-inspector输出的JSON结构从数组改成了对象加元数据结果所有直接解析这个输出的技能全都崩了。后来我习惯在SKILL.md里明确声明“输出格式稳定承诺”的版本号只有大版本变更时才允许破坏性更新这样下游技能可以感知变更并做适配。6.2 技能复用与共享技能架构最大的红利是跨项目复用。一个团队或一个技术社区可以沉淀一套公共技能集在新项目初始化时一键引入。这比复制整个system prompt要优雅得多因为它让能力边界清晰化也让维护成本分摊到了每个技能模块上。我的建议是在团队内部建立一套“技能仓库”概念公共技能放在统一仓库项目级技能放在各项目内部。公共技能遵循严格的准入标准描述无歧义、脚本无单点执行风险、输出格式稳定、依赖清晰。项目级技能则可以做快速迭代实验成熟后再提升为公共技能。这种做法最大的价值不在于节省重复劳动而在于让Agent能力变成组织资产而不是绑定在某段提示词里的隐性知识。它能被审查、被版本化、被评估这是传统Prompts完全无法提供的可管理性。最后再分享一点个人体会这套Skills架构我用了很长一段时间从最初的十几个技能逐渐收敛到五个核心技能中间经历了大量试错。给我留下最深印象的不是技术本身而是设计思路上的转变以前我会想“如何把更多知识塞进Agent”现在我想的是“如何让Agent在正确的时间找到刚好够用的知识”。这两者看起来差别很小但实际效果天差地远。如果你刚开始接触Agent Skills我建议不要贪多先尝试把最频繁使用的三个能力模块化。等跑通一次“定义边界、写SKILL.md、补脚本、迭代调试”的完整流程你自然会理解每个细节背后的必要性。最后再分享一个小技巧定期翻看Agent的实际调用记录每次加载技能时的进入原因和退出时机都会写在日志里。你会发现很多自己没有意识到的行为规律这些发现往往比你再去优化提示词文案更有效。