重构 Agent 技能：从上下文爆炸到快速、可靠的工作流
I’m happy to translate the article for you, but I don’t have the full text of the post beyond the source link you provided. Could you please paste the content you’d like translated (excluding any code blocks or URLs you want to keep unchanged)? Once I have the text, I’ll translate it into Simplified Chinese while preserving the original formatting and markdown.
1️⃣ 根本原因：把 Skills 当作文档
第一个陷阱非常人性化：
“If I include everything, the model will always have what it needs.”
所以你为每个工具创建一个 Skill，每个 Skill 成为文档倾倒：
- 设置步骤
- API 参考
- 详尽示例
- “不要做 X” 列表
- 自 2017 年以来的所有边缘情况
然后像 “deploy a serverless function with a small UI” 这样的任务会调用：
- 你的 Cloudflare Skill
- 你的 Docker Skill
- 你的 UI‑styling Skill
- 你的 web‑framework Skill …
……模型的工作已经半沉没了。
Claude Code 的官方文档警告说，Skills 与对话、请求以及其他 Skills 共享上下文窗口——这意味着不受控制的加载会直接导致性能开销（你会感受到慢速、漂移，以及“它为什么忽略明显的部分？”）。
结论： 你的问题不是“信息不足”。而是“信息过多且不相关”。
2️⃣ 修复方案：渐进式披露（三级）
Claude Code 文档明确推荐 渐进式披露：将关键信息放在 SKILL.md，将大量内容存放在单独的文件中，仅在任务需要时加载。
这与三级系统对应：
第1层 – 元数据（始终加载）
一个简短的 YAML 前置元数据，包含 name、description 和 routing signal。可以把它想象成书的封面和简介——你不是在教学，而是帮助模型决定是否打开这本书。
第2层 – 入口点：SKILL.md（激活时加载）
你的导航图：
- 技能的用途
- 何时使用
- 高层次的步骤
- 接下来要打开的参考文件
不是教程，也不是维基。
第3层 – 参考文件与脚本（仅在需要时加载）
小而专注的文件：
- 每个文件只涉及一个主题
- 每个文件约 200–300 行是一个不错的目标
- 脚本执行确定性的工作，避免模型消耗 token “描述”操作
示例文件夹结构
.claude/skills/devops/
├── SKILL.md
├── references/
│ ├── serverless-cloudflare.md
│ ├── containers-docker.md
│ └── ci-cd-basics.md
└── scripts/
├── validate_env.py
└── deploy_helper.sh3️⃣ “200 行规则”：残酷、略显任意、奇效显著
在社区重构的案例中，作者给出了一个硬性约束：
保持
SKILL.md在约 200 行以内。
如果做不到，就说明入口点放了太多内容。
Claude 自己的最佳实践文档建议将主体控制在几百行以内（当接近此上限时就拆分内容）。“200 行”是一把更锋利的刀：它迫使你写 目录，而不是教科书。
为什么有效
- 模型可以快速扫描入口。
- 它能够决定接下来加载哪个引用文件。
- 总的“初始加载”保持足够小，使对话仍有余地展开。
你可以直接使用的快速测试
- 开启一个全新的会话（冷启动）。
- 触发你的 Skill。
- 如果第一次激活加载的内容 超过约 500 行，说明你的设计可能在泄漏作用域。
4️⃣ 真正的思维转变：从工具导向到工作流导向
这是大多数人忽略的部分。
工具导向技能（有问题）
cloudflare-skill
tailwind-skill
postgres-skill
kubernetes-skill它们像百科全书，难以组合使用。
工作流导向技能（推荐）
devops (deploy + environments + CI/CD)
ui-styling (design rules + component patterns)
web-frameworks (routing + project structure + SSR pitfalls)
databases (schema design + migrations + query patterns)它们对应于开发过程中你实际在做的事。
工作流技能回答：
“当我处于工作中的这个阶段时，代理需要了解哪些信息才能正确行动？”
—而不是—
“这个工具能做的所有事情是什么？”
这种重新框定几乎可以自行防止上下文膨胀。
5️⃣ 一个最小的、可投入生产的 SKILL.md（示例）
下面是一个刻意保持简洁的入口文件，你可以复制并自行定制。请注意缺少的内容：冗长的示例、完整文档以及“你可能需要的所有东西”。
---
name: ui-styling
description: Apply consistent UI styling across the app (Tailwind + component conventions). Use when building or refactoring UI.
---
# UI Styling Skill何时使用
- 开始一个新的 UI 组件。
- 为了一致性重构现有组件。
- 更新设计系统。
高级工作流程
- Identify 需要进行样式化的组件或页面。
- Run
scripts/apply_tailwind.sh以生成 Tailwind 类。 - Reference
references/tailwind-utilities.md获取实用类指南。 - Validate 使用
scripts/check_style.py验证，以确保没有 lint 错误。
参考文件（按需加载）
references/tailwind-utilities.md– 已批准的实用程序和模式列表。references/component-conventions.md– 命名、文件夹结构和组合规则。
脚本（按需加载）
scripts/apply_tailwind.sh– 将 Tailwind 类注入文件。scripts/check_style.py– 运行样式检查并报告违规。
快速提示
如果组件已经遵循了设计系统，跳过第 2 步，直接进行验证。
### TL;DR 检查清单
- **仅在 YAML front‑matter 中放置元数据**。
- 保持 `SKILL.md` **≤ 200 行**。
- 将大量内容存放在 `references/` 和 `scripts/` 中。
- 将技能 **围绕工作流** 设计，而不是单个工具。
- 使用冷启动进行测试；首次加载目标 **≤ 500 行**。
遵循此手册，你会看到上下文窗口重新获得呼吸空间。 🚀
### 使用时机
- 你正在构建 UI 组件或页面。
- 需要一致的间距、排版和响应式行为。
- 需要与现有设计约定保持一致。
### 工作流
1. **确定 UI 视图**（页面/组件）及其约束（响应式、暗模式、可访问性）。
2. **从参考资料中应用样式规则**——只挑选你需要的部分。
3. **根据检查清单验证输出**。
### 参考资料（仅在需要时加载）
- `references/design-tokens.md` — 间距、字体比例、颜色使用
- `references/tailwind-patterns.md` — 布局、常用实用类组合
- `references/accessibility-checklist.md` — 键盘、焦点、对比度
### 输出约定
- UI 文本使用英式英语。
- 优先使用可复用组件，而非复制‑粘贴代码块。
- 保持 `className` 可读（当变得混乱时抽取出来）。
#### 全屏切换（示例）
```html
Enter fullscreen mode
Exit fullscreen mode就这些。
Skill 的职责是 在正确的时刻将代理路由到正确的文件——而不是成为页面内的百科全书。
6️⃣ 衡量改进（不自欺）
如果你想要可重复的结果，请跟踪真正重要的指标：
- 激活时加载的初始行数。
- 激活时间（大致：感觉有多“灵敏”）。
- 相关性比例（已加载内容中实际被使用的比例）。
- 上下文溢出频率（长任务崩溃的次数）。
你不需要完整的可观测性栈；一个简单的仓库审计脚本就足够了。
简易 Python 审计：统计每个 Skill 的行数
from pathlib import Path
skills_dir = Path(".claude/skills")
def count_lines(p: Path) -> int:
"""Return the number of lines in a file, ignoring decode errors."""
return sum(1 for _ in p.open("r", encoding="utf-8", errors="ignore"))
for skill in sorted(skills_dir.iterdir()):
skill_md = skill / "SKILL.md"
if skill_md.exists():
lines = count_lines(skill_md)
status = "OK" if lines < 200 else "TOO LONG"
print(f"{skill.name}: {lines} lines – {status}")每周运行一次，你就能在“文档膨胀”成为危机之前发现它。
7️⃣ 常见失败模式（以及如何避免）
失败模式：Claude 写 “a doc” 而不是 “a Skill”
LLMs 喜欢把 markdown 扩展成教程。
修复：
- 明确告诉模型：这不是文档。
- 删除 “beginner” 填充词。
- 保持示例简短；将细节放入参考文件。
失败模式：入口点膨胀，因为 Skill 范围太宽
修复：
- 按工作流阶段拆分 Skill。
- 或者将决策树移到参考文件中。
失败模式：参考太多，仍然难以导航
修复：
- 在
SKILL.md中添加一个简短的 “地图” 部分。 - 保持参考文件单一主题，并按意图命名，而不是按工具命名。
8️⃣ 可复制的重构清单
- 审计 – 列出 Skills + 行数；标记任何
SKILL.md> 200 行的文件。 - 按工作流分组 – 将工具特定的 Skills 合并到能力 Skills 中。
- 创建引用 – 将详细信息移出
SKILL.md。 - 强制入口约束 – 保持
SKILL.md简洁且易于导航。 - 冷启动测试 – 确保首次激活的成本低于你设定的预算。
- 保持脚本确定性 – 尽可能将“执行任务”转移到代码中。
- 每月复查 – Skills 随时间漂移；把它们当作代码来对待。
最后总结：上下文工程是“正确的信息，正确的时间”
关键的教训不是“200 行”或“三层”。
而是：
上下文是一种预算。
最好的 Skill 设计会像工程师而不是图书管理员那样使用它。
不要一次性加载所有内容。只加载重要的——在重要的时候——其余的保持在另一个文件中即可。