给 Skill 减负,渐进式加载
#ai #skill #llm #claude
背景
之前写了一篇文章研究token是怎么计算的文章,之后也尝试了一下如何减少token的使用。主要是用英文输入来代替中文输入,但是尝试了几次之后发现这样的作用不太大,token的消耗并没有明显的下降。最后我发现了,我的skillimplement 每次消耗的数量比较大。
然后我让cc分析了一下自定义skill的行数,implementskill的数量也是比较大的。在cc的best practice中提到,每个skill的大小不要超过500行,因为每次在使用skill的时候会将整个skill都加载进去,这样不仅会让ai抓不到任务的关键,也会有一些额外的噪音来干扰。claude code官网上推荐了Progressive disclosure patterns【渐进式的skill partner】。
| skill | SKILL.md 行数 | 带附属文件 | 是否超 500 行建议 |
|---|---|---|---|
| implement | 934 | 否 | 是 |
| juno-ui-test | 383 | 否 | 否 |
| analyze-requirement | 269 | 否 | 否 |
| implement-by-claudia | 219 | 否 | 否 |
| refine-ticket-plan | 185 | 否 | 否 |
| resolve-pr-comments | 159 | 是(3 个scripts/*.sh) |
否 |
| postman-request | 153 | 否 | 否 |
| create-mr | 127 | 否 | 否 |
| bug-analyze | 126 | 否 | 否 |
| code-review | 124 | 否 | 否 |
| commit | 51 | 否 | 否 |
渐进式skill patterns
单个SKILL文件
在说什么是渐进式的skill之前,我想先给大家说一下什么是一个比较好的skill格式,按照以下的格式claude code就能够按照你定义的流程来工作。
1 | --- |
目前我现在的implementskill的构成如下
1 | implement/SKILL.md (934 行) |
分层出来之后,就显而意见了,当前的这个skill中冗余了太多的不需要第一次就加载进来的东西,这就可以引入我们下一个话题了,skill可以分层了。
SKILL分层
也是claude推荐的方式,官网在这里建议了一个好的skill的pattern样本。Skill 是放在 Claude 虚拟机文件系统里的目录,内容分三层,按需加载。
| 层级 | 加载时机 | token 成本 | 内容 |
|---|---|---|---|
| Level 1:元数据 | 始终加载(启动时) | 每个 skill 约 100 token | frontmatter 里的name 和 description |
| Level 2:指令 | skill 被触发时 | 5k token 以内 | SKILL.md 正文 |
| Level 3+:资源和代码 | 按需 | 读取之前为 0 | 附属文件。参考文档读了才进上下文,脚本通过 bash 运行,只有输出进上下文 |
要点
- description 决定是否触发。 Claude 用它来匹配你的请求,所以必须同时写清这个 skill 做什么、什么时候用。没触发之前,只有 name 和 description
占上下文,所以装很多 skill 也没有负担。 - Claude 通过 bash 读文件。 触发后它 cat SKILL.md,正文里引用了别的文件才会继续读。文档的例子里,用户只要提取文字,Claude 判断不需要表单填写,就不会去读
FORMS.md。 - 三种内容各有用途。 指令用来给灵活的指导,代码用来保证确定性,资源用来查事实。
- 脚本比让 Claude 现写代码更省 token。 运行 validate_form.py 时,脚本代码不进上下文,只有 “Validation passed” 这类输出才占 token。
- 附属内容没有实际上限。 没被读到的文件不占上下文,所以可以放完整的 API 文档、大数据集、大量示例。
分层后的
分层后的skill相当于是一个路由表引导你往哪个具体要事走
| 模式 | 做法 | 官方示例 | 什么时候读附属文件 |
|---|---|---|---|
| Pattern 1:高层指南 + 引用文件(High-level guide with references) | SKILL.md 放快速开始,高级内容链接到独立文件 | pdf-processing:FORMS.md、REFERENCE.md、EXAMPLES.md | 需要对应功能时 |
| Pattern 2:按领域组织(Domain-specific organization) | 多领域内容按领域拆到 reference/ 下,SKILL.md 只做概览和导航 | bigquery-skill:reference/finance.md、sales.md、product.md、marketing.md | 问到哪个领域就读哪个文件 |
| Pattern 3:条件式详情(Conditional details) | 基础内容写在 SKILL.md,高级内容链接出去 | DOCX Processing:修订追踪看 REDLINING.md,OOXML 细节看 OOXML.md | 用户需要高级功能时 |
改进后的skill
最后我现在想把我的skill改成如下的结构,将pitfalls和copilot拆出去,skill只保留主流程
1 | implement/ |
但是PITFALL.md我没有直接拆出去因为,这样有可能导致claude code在执行过程漏读
pitfall的改进
- 类别: A. 与已常驻文档重复
内容: 路由前缀对应基类表、业务逻辑别放 view、transaction.atomic、N+1、禁止手改 migration、裸 except / except: pass
行数: 约 25
处理: 删除。这些在 .ai/conventions.md、.ai/code-quality.md、.ai/context.md 里已经有,而这三个文件通过 CLAUDE.md 每次都加载 - 类别: B. 每次都该遵守的硬规则
内容: 路由基类选错是安全 bug(一行)、新 viewset 要在 app/urls.py 注册(一行)、业务异常必须用 APPExceptionEx 带 details,以及不要把 pydantic 400 转成 biz
code
行数: 约 15
处理: 留在 SKILL.md。COPILOT.md 还引用了”SKILL.md Step 4 Errors / logging”,所以这条不能搬 - 类别: C. 只在特定场景才用
内容: Permissions(54 行):新增 permission、seed SQL 风格、本地 DDL、测试、迁移单独 PR。Persistence 和 Migrations:check-then-create 竞态、MySQL
UNIQUE 里 NULL 不相等、软删、迁移放哪个 app、db_table 前缀、feature flag
行数: 约 54 + 约 35
处理: 拆出去,按场景写触发条件 - 类别: D. 可做成自动检查
内容: db_table 前缀(已有 check_model_conventions.py)、”新增 permission 必须有 permissions_checker_args 断言测试”、新 viewset 没注册 URL
行数: 约 10
处理: 文字只留一句”由 sensor 拦截”,规则本身交给检查 - 拆分后的结构
1 | implement/ |
- 保证不漏读的方式
- Pitfalls 开头写成触发表,每个场景一行,并要求在回复里写”已读 xxx”:
- 改了或新增 endpoint 的权限 → 先读 reference/permissions.md
- 新增 model/字段/唯一约束/迁移/feature flag → 先读 reference/persistence-migrations.md
改进后的效果
结构
拆分后各文件行数(原来是单个 SKILL.md 934 行):
| 文件 | 行数 | 什么时候读 |
|---|---|---|
| SKILL.md | 593 | 每次触发 /implement |
| COPILOT.md | 270 | 仅 –copilot |
| reference/permissions.md | 58 | 新增或更换 permission |
| reference/persistence-migrations.md | 39 | 新增 model、唯一约束、迁移、feature flag |
SKILL.md 还没有降到 500 行以内(593),剩下的大块是 Step 3 Plan 和 Rules,后面再拆。
每次调用的费用
用本机会话记录统计每次手动 /implement 的费用:从输入 /implement 开始,到最后一次 git commit 为止,窗口内所有助手回复(含子代理)的 token 乘单价。没有提交的窗口不计入。
| 时段 | 有提交的次数 | 平均 | 中位数 |
|---|---|---|---|
| 10-19 到 10-28(拆分前) | 8 | 约 $30.9 | 约 $14.5 |
| 11-05 到 11-09(拆分前) | 7 | 约 $4.2 | 约 $2.4 |
| 11-17、11-18(拆分后) | 4 | 约 $1.5 | 约 $1.5 |
拆分后 4 次分别是 $1.3、$1.3、$1.7、$1.7,很稳定,和 Claude 后台 Top skills 里 implement 每次 $1.68 的量级一致。
- Title: 给 Skill 减负,渐进式加载
- Author: Xiao Qiang
- Created at : 2026-11-18 13:58:16
- Updated at : 2026-11-18 14:25:11
- Link: http://fdslk.github.io/LLM/agent/vibe-coding/skill/2026/11/18/skill-optimize-1/
- License: This work is licensed under CC BY-NC-SA 4.0.