本文聚焦 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——同一规则写三遍

典型症状

同一个完成标准在三个地方出现了三次：

# description
description: 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.
- Don't 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 导致明显失败时，不只加规则，也顺手删一段旧内容。

具体步骤：

1. 对每条规则做"存活检查"：这条规则对应的场景还会发生吗？
2. 对仍然有效的规则，检查它是否是 no-op（能不能改成可检查动作）
3. 对确认有效的规则，检查它是否与其他规则重复
4. 合并、精简、删除

修复前（沉积后）：

## 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 统一管理方案有哪些？ 核心是三个统一：

1. 统一接入：一个 API 端点调用所有模型，避免为每个模型写一套对接代码
2. 统一计费：透明的成本对比，避免各模型账单分散难以核算
3. 统一监控：集中监控各模型的响应质量、延迟和可用性

大模型 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-skills
• AI Engineer, Building Great Agent Skills: The Missing Manual
• Matt Pocock, X 短贴
• Anthropic, Agent Skills Overview
• OpenAI, Codex Skills
• Agent Skills Specification, Specification
• Simon Willison, Claude Skills are awesome, maybe a bigger deal than MCP
• Addy Osmani, Agent Skills