type
Post
status
Published
date
Nov 6, 2025
slug
ai-agent-skills-boost-2026-tsdci3
summary
📌 来自：faafospecialist.substack.com (Substack) | 💡 Agent Skills 的本质是上下文工程，而非文档堆砌。
作者分享了他在开发 Claude Agent Skills 过程中的重大误区：起初他将数千行的技术文档直接塞进 Skill 文件，导致上下文窗口迅速过载。通过引入“渐进式披露”架构，他将 Skill 重构为三层结构（元数据、入口点、参考文件），实现了 85% 的初始化加载减量。最核心的转变在于，意识到 Agent Skills 应该是针对“工作流”的活跃能力，而不是针对“工具”的被动文档。 | 🔑 关键词：Substack、faafospecialist.substack.com、FA&FO | 🤖 由Gemini 3 Flash (Google API)分析生成
tags
Substack
faafospecialist.substack.com
FA&FO
category
Substack文章
icon
📰
password
本文是对 faafospecialist.substack.com (Substack) 的学习笔记。所有观点归原作者所有，建议阅读原文获取完整内容。
💡 Agent Skills 的本质是上下文工程，而非文档堆砌。
作者分享了他在开发 Claude Agent Skills 过程中的重大误区：起初他将数千行的技术文档直接塞进 Skill 文件，导致上下文窗口迅速过载。通过引入“渐进式披露”架构，他将 Skill 重构为三层结构（元数据、入口点、参考文件），实现了 85% 的初始化加载减量。最核心的转变在于，意识到 Agent Skills 应该是针对“工作流”的活跃能力，而不是针对“工具”的被动文档。
发生了什么
Agent Skills（智能体技能）功能在 10 月 16 日发布后，我立即开始构建。在两周内，我写了一个 1,131 行的 `cloudflare` 技能，一个 850 行的 `shadcn-ui` 技能，一个 900 行的 `nextjs` 技能，以及超过 1,200 行的 `chrome-devtools` 技能。
每当 Claude Code（Claude 代码助手）激活多个相关的技能时，我都能看到 Context Window（上下文窗口）急剧膨胀。加载 5-7 个技能意味着 5,000 到 7,000 行内容瞬间涌入上下文。
我原本以为事情就该这样：把所有信息都放进一个巨大的 `SKILL.md` 文件里，这样 Agent 就能预先掌握所有信息。信息越多，结果越好，对吧？我错了。
残酷的真相
这很令人尴尬，因为解决方案一直就在我眼前。我把 Agent Skills 当成了 Documentation Dumps（文档堆填区），而没有意识到它们真正的本质是：Context Engineering（上下文工程）问题。
最让人沮丧的是，我甚至在 `skill-creator`（技能创建器）这个技能本身里记录了 Progressive Disclosure（渐进式披露）原则。我把它写了下来，但我当时并不理解它在实践中到底意味着什么。
真正让我生气的是：我花了整整两周时间调试“上下文增长”问题和缓慢的激活时间，而这些问题完全是我自找的。那些臃肿的 `SKILL.md` 文件中，90% 的时间加载的都是无关信息。
技术细节
重构前：灾难现场
`.claude/skills/cloudflare/`: 1,131 行
`cloudflare-workers/`: 约 800 行
`nextjs/`: 约 900 行
`shadcn-ui/`: 约 850 行
`chrome-devtools/`: 约 1,200 行
以及另外 30 个同样臃肿的文件。
总计： 36 个技能共约 15,000 行（约 12 万到 30 万个 Token）。
问题： 激活 `devops` 上下文（持续使用 Cloudflare、Docker 或 GCloud）意味着立即加载 2,500 多行内容。其中大部分从未被使用。
重构后：渐进式披露架构
我使用“三层加载系统”进行了重构：
第一层：Metadata（元数据，始终加载）
仅 YAML Frontmatter（YAML 前置数据）
约 100 个单词
刚好够 Claude 判断该技能是否相关。
第二层：`SKILL.md` 入口点（技能激活时加载）
最多 200 行
包含概览、快速启动、导航地图
指向参考资料，但不包含具体内容。
第三层：Reference Files（参考文件与脚本，按需加载）
每个文件 200-300 行
详细文档
只有在 Claude 需要时才会读取。 模块化并专注于单一主题。
数据表现
Claude Code 技能重构结果：
**重构前： ** 单个文件 870 行
**重构后： ** 181 行入口点 + 13 个参考文件
**降幅： ** 79%（Token 效率提升 4.8 倍）
第一阶段和第二阶段的完整重构：
**重构前： ** 36 个独立技能，共 15,000 行
**重构后： ** 整合为 20 个专注的技能组（2,200 行初始加载 + 45 个参考文件）
**核心组： ** `devops`、`web-frameworks`、`ui-styling`、`databases`、`ai-multimodal` 等。
**降幅： ** 初始激活量减少 85%
实际影响：
**激活时间： ** 从 约 500ms 降至 小于 100ms
**上下文溢出： ** 从 很快 变为 很慢
**相关信息占比： ** 从 约 10% 提升至 约 90%
根因分析
根本错误在于：我混淆了“可用信息”与“已加载信息”。
但更深层的误解是：Agent Skills 不是文档。它们是针对开发工作流的特定能力和知识。
每一个 Skill 代表一种 Capability（能力）：
`devops` 不是“Cloudflare 文档”——它是部署 Serverless（无服务器）函数的能力。
`ui-styling` 不是“Tailwind 文档”——它是设计一致界面的能力。
`sequential-thinking`（顺序思考）不是指南——它是一种解决问题的方法论。
我之前有 36 个独立技能，是因为我把每个工具都当成了需要文档堆填的对象。错了。技能应该按照 Workflow Capabilities（工作流能力）来组织，而不是按工具。
这就是为什么整合有效：
**旧模式： ** 36 个工具导向的技能 -> “这是关于 Cloudflare 的一切。”（文档思维）
**新模式： ** 20 个工作流能力组 -> “这是如何使用 Cloudflare、GCloud、Docker 处理 DevOps 部署。”（开发工作流思维）
200 行的限制并不是随意的。它是基于 LLM（大语言模型）能高效扫描多少上下文来决定下一步加载什么的经验值。保持入口点在 200 行以下，Claude 就能快速：
理解技能提供的功能。
决定读取哪个参考文件。
仅加载该文件（又是 200-300 行）。
总计： 400-700 行高度相关的上下文，而不是 1,131 行相关性混杂的内容。这是 Context Engineering 101（上下文工程入门），而我居然漏掉了。
经验教训
200 行规则至关重要 —— 这不是建议，而是快速导航与“上下文淤泥”之间的分界线。
**渐进式披露是必选项** —— 任何超过 200 行的技能都应该重构。 没有例外。如果你无法把核心指令压缩在 200 行内，说明你在入口点塞了太多东西。
**References（参考资料）是一等公民** —— 我以前把 `references/` 当作“可选的额外文档”。 错了。参考资料才是真正干活的地方，`SKILL.md` 只是地图。
**测试冷启动** —— 清空上下文，激活技能，然后测量。 如果第一次激活就加载了超过 500 行，那你就做错了。
**指标不会撒谎** —— 4.8 倍的 Token 效率提升不是边际改进。 它是“偶尔有用”和“稳定可靠”之间的本质区别。
总结
技能 vs. 文档
技能是在特定工作流时刻激活的能力：
编写测试时激活 `code-review`。
调试生产环境时激活 `sequential-thinking`。
部署基础设施时激活 `devops`。
每个技能都在教 Claude 如何执行特定的开发任务，而不是解释一个工具是什么。这就是为什么把它们当文档处理会失败。文档是被动的参考资料，而技能是主动的工作流知识。
渐进式披露之所以有效，是因为它匹配了开发的实际过程：
**扫描元数据： ** 这个能力对当前任务相关吗？
**阅读入口点： ** 这能开启哪些工作流模式？
**加载特定参考： ** 获取当前步骤的实现细节。
每一步都是微小、专注且有目的的。这就是你构建真正能提供帮助、而非让人不堪重负的技能的方法。
📌 关键收获
对 Grace 的启示
**SOP（标准作业程序）的 AI 化重构**： 在为独立站运营（如写 SEO 博客、处理退款）编写 AI 指令时，不要给 AI 一个超长的 PDF 指南。应采用“三层结构”：一个简短的指令判断场景，再引导 AI 去读取具体的子任务操作手册。
**从“工具导向”转向“任务导向”**： 不要建立“Shopify 技能”或“Facebook Ads 技能”，而要建立“产品上架技能”或“广告投放优化技能”。让 AI 学习如何完成一个闭环任务，而不是学习如何使用一个工具。
**极致的上下文效率**： 时刻关注 AI 处理任务时的“废话比”。如果 AI 每次干活都要先读几千字背景，不仅浪费钱（Token），还会让 AI 变笨（注意力分散）。保持核心指令在 200 行（或约 500 字）以内。
上下文工程的核心不在于加载更多信息，而在于在正确的时间加载正确的信息。
想了解更多细节？ 查看原文 →
上一篇
Claude Code 进阶技巧：如何使用多个 MCP 服务而不撑爆上下文？ (2026最新)
下一篇
深度解析 Claude Agent Skills：告别 Token 焦虑，开启高效 AI 编程新范式
- Author:EcomGrace
- URL:http://ecomgrace.com/article/ai-agent-skills-boost-2026-tsdci3
- Copyright:All articles in this blog, except for special statements, adopt BY-NC-SA agreement. Please indicate the source!
