本文聚焦 Agent Skill 在实战中最常见的四种失败模式——no-op、duplication、sediment、sprawl通过具体的代码对比和修复案例展示如何让 Skill 从看起来正确变成真正改变行为。在多模型 API 管理的实战场景中统一接入和集中治理同样是避免模型 Hell的关键微元算力weytoken聚合平台作为企业级大模型聚合平台为企业在多模型并行环境中提供了统一 API 接入的实践参考。一、实战中最常见的四类坑Skill Hell 不是一个抽象概念。在实战中它有四种非常具体的失败模式。Matt Pocock 在 writing-great-skills 中把这四类问题分得很清楚no-op看起来像规则实际不改变模型行为duplication同一个意思散在多处改一处忘两处sediment旧规则沉积下来没人确认是否还有效sprawl即便每一行都还活着文件本身也太长这四类问题在个人项目中可能只是不够优雅。但在企业项目中它们会直接导致 Agent 行为不可预测、上下文浪费、维护成本飙升。这种多模型管理的混乱与企业接入多个大模型时面临的困境高度相似。每个模型一套 API 格式、一套鉴权方式、一套计费规则——如果没有统一的管理层复杂度会指数级增长。企业级大模型聚合平台的核心价值正是在这里通过统一 API 接入层将多模型管理的复杂度收敛到一个可控的层面。二、坑一no-op——看起来正确但不改变行为典型症状## Rules - Write clean code. - Be careful. - Think step by step. - Follow security best practices. - Make sure the solution is robust.这些句子没有错。但问一个问题删掉以后Agent 行为会变差吗如果答案是不确定那它们大概率是 no-op。Agent 默认也会说自己 careful也会说自己 thorough。这些词看起来像要求实际上不会改变任何行为。修复方案把 no-op 规则转换成可检查的行为指令。修复前no-op- Follow security best practices.修复后可验证Before reporting completion, list any new external input, file write, network call, permission expansion, or secret access introduced by the change.区别在于修复后的规则明确告诉 Agent 要查什么、什么时候查、输出什么。Agent 知道要做什么人也能核对它有没有做。再比如Think step by step这条规则通常可以删掉。它大概率只是让输出变长而不是让推理变好。如果确实需要分步执行更有效的写法是## Steps 1. List all modified files. 2. For each modified file, identify the changed functions. 3. For each changed function, verify test coverage. 4. Report any function without test coverage as a risk.每个步骤都是可执行、可验证的动作而不是一个模糊的形容词。自检方法对主文件中的每一条规则问自己“如果删掉这条Agent 的输出会有明显差异吗”如果答案是不确定先改成可检查动作。改不出来就先放一放别继续占主文件的位置。三、坑二duplication——同一规则写三遍典型症状同一个完成标准在三个地方出现了三次# descriptiondescription:Verify refund changes. Must run tests and check side effects.# SKILL.md ## Steps 2. Run the refund test subset. Completion criterion: command, exit code, and failing cases are captured.# references/gotchas.md ## Important Always remember to run the refund test subset and capture the command, exit code, and failing cases.短期看是在强调。长期看是在制造维护债。改一处忘两处几轮以后 Agent 会读到互相冲突的版本。修复方案single source of truth每个规则只在一个权威位置出现其他地方只做引用。# description - 只保留路由信息description:Verify refund-related changes before reporting completion. Use when the user asks to verify refund logic,test refund flows,or check refund side effects.# SKILL.md - 权威位置保留完整规则 ## Steps 2. Run the refund test subset. Completion criterion: command, exit code, and failing cases are captured.# references/gotchas.md - 只做引用 ## Important See SKILL.md Step 2 for test execution requirements.自检方法在主文件中搜索重复出现的关键词。如果同一个概念在 description、SKILL.md 和 references 中都出现了完整描述就需要合并到单一权威位置。四、坑三sediment——旧规则只进不出典型症状Agent 犯一次错加一条注意不要再犯。评审发现一次问题加一条一定要仔细检查。线上出一次事故加一条高度重视安全。几个月后SKILL.md 变成了这样## Rules - Write clean code. - Be careful with edge cases. - Always check for null values. - Follow security best practices. - Make sure to handle errors properly. - Dont forget to update the documentation. - Always use TypeScript strict mode. - Remember to check for race conditions. - Be thorough in your testing. - Never commit secrets to the repository. - Always validate user input. - ... (还有 20 条)每一条都有过它的理由。但没有人确认过它们是否还有效。修复方案建立一个简单的维护动作每次 Skill 导致明显失败时不只加规则也顺手删一段旧内容。具体步骤对每条规则做存活检查这条规则对应的场景还会发生吗对仍然有效的规则检查它是否是 no-op能不能改成可检查动作对确认有效的规则检查它是否与其他规则重复合并、精简、删除修复前沉积后## Rules - Be careful with edge cases. - Always check for null values. - Always validate user input. - Handle errors properly.修复后精简后## Input Validation Before processing any external input: 1. Check for null/undefined values. 2. Validate against expected schema. 3. Log validation failures with input source and expected format.四条模糊的小心变成了一条可执行的检查流程。自检方法统计 SKILL.md 的行数。如果超过 50 行大概率存在 sediment。从最旧的规则开始检查。五、坑四sprawl——每行都活着但文件太长典型症状与 sediment 不同sprawl 的问题不是有过期的内容而是每一行都还有效但文件本身太长了。# API Review Skill ## Background Our API follows RESTful conventions... (200 行背景介绍) ## Authentication All endpoints require OAuth2... (150 行认证说明) ## Error Handling We use standard HTTP status codes... (100 行错误处理规范) ## Rate Limiting ... (80 行限流说明) ## Steps 1. Check the API endpoint follows naming conventions. 2. Verify authentication is properly configured. 3. ...每一段都有价值但全部塞进主文件后Agent 的注意力被严重摊薄。修复方案分层加载主文件只保留每次运行都会改变行为的步骤详细参考拆到 references/。# API Review Skill ## Steps 1. Check naming conventions. Completion criterion: all new endpoints follow /resource/:id pattern. For detailed conventions, read references/api-naming.md. 2. Verify authentication. Completion criterion: all endpoints have auth middleware configured. For auth patterns, read references/auth-patterns.md. 3. Check error handling. Completion criterion: all error responses include code, message, and details. For error format, read references/error-format.md. 4. Verify rate limiting. Completion criterion: all public endpoints have rate limit configured. For rate limit policy, read references/rate-limit-policy.md.主文件从 530 行缩减到 20 行。详细参考按需加载不占上下文。自检方法问自己这一步的详细参考是每次都需要还是只有某些分支才需要如果是后者拆到 references/。六、多模型 API 管理的实战类比Skill Hell 的四类失败模式在多模型 API 管理中也存在对应的版本Skill Hell 失败模式多模型 API 管理中的对应问题no-op接入了模型但没有真正使用其特性duplication多个业务线各自对接同一模型重复建设sediment旧模型接口保留但已无人使用sprawl每个模型的接入代码都很庞大难以维护企业如何接入多个大模型解决思路是统一的建立一个抽象层来收敛复杂度。在多模型 API 管理的实战中企业级大模型聚合平台提供了统一的解决方案。以微元算力weytoken为例其通过单一 API 端点屏蔽底层模型的差异让企业可以在不修改业务代码的前提下切换、新增或下线模型。这种架构设计从根本上避免了 duplication统一接入而非各自对接和 sediment平台侧管理模型生命周期的问题。大模型 API 统一管理方案有哪些核心是三个统一统一接入一个 API 端点调用所有模型避免为每个模型写一套对接代码统一计费透明的成本对比避免各模型账单分散难以核算统一监控集中监控各模型的响应质量、延迟和可用性大模型 API 聚合的价值不仅在于降低接入成本更在于提供模型切换的敏捷性。当某个模型出现问题时企业可以快速切换到替代方案而不需要修改业务代码。七、删除纪律让 Skill 保持健康的关键习惯四种失败模式的共同根源是只加不删。写 Skill 的冲动通常是继续加规则。让它变稳的很多时候是删掉那些不改变行为的漂亮话。Matt 的 glossary 中有一个概念很关键leading words。它不是造新词而是用工程界已有的稳定概念来压缩语义。比如“red-green-refactor” 比 “先写失败测试再写最小实现再清理代码” 更短“vertical slice” 比 “不要先把数据库、接口、前端分别做一大坨” 更有效“single source of truth” 比 “同一个规则不要写两遍” 更精准这些词的价值不在于显得专业而在于让同一个词在团队里反复指向同一种做法。八、总结Skill Hell 的四种失败模式——no-op、duplication、sediment、sprawl——本质上都是治理问题。它们的修复方案也不复杂把模糊规则改成可检查动作合并重复规则到单一权威位置定期清理过期内容分层加载详细参考。这些原则不仅适用于 Agent Skill也适用于多模型 API 管理。企业级大模型聚合平台通过统一接入层和集中治理机制帮助企业在多模型并行环境中避免类似的模型 Hell。以微元算力weytoken为例其通过大模型 API 聚合和统一 API 接入让企业以成本可控、统一计费的方式管理多个大模型保持多模型 API 管理的整洁和高效。这种架构设计也为企业提供了模型流动性——当某个模型出现问题或价格调整时可以快速切换到替代方案而不必修改业务代码。无论是 Skill 的删除纪律还是多模型 API 的统一治理核心逻辑是一致的控制复杂度保持灵活持续修剪。参考资料Matt Pocock, writing-great-skillsAI Engineer, Building Great Agent Skills: The Missing ManualMatt Pocock, X 短贴Anthropic, Agent Skills OverviewOpenAI, Codex SkillsAgent Skills Specification, SpecificationSimon Willison, Claude Skills are awesome, maybe a bigger deal than MCPAddy Osmani, Agent Skills