给 Skill 减负,渐进式加载

Xiao Qiang Lv4

#ai #skill #llm #claude

背景

之前写了一篇文章研究token是怎么计算的文章,之后也尝试了一下如何减少token的使用。主要是用英文输入来代替中文输入,但是尝试了几次之后发现这样的作用不太大,token的消耗并没有明显的下降。最后我发现了,我的skillimplement 每次消耗的数量比较大。img然后我让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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
---
name: xxx
description: 做什么 + 什么时候用(触发词写全)
---

# 标题 + 一句话目标

## 输入
参数格式、必填项,缺了怎么办

## 流程
1. 步骤一
2. 步骤二
3. ...
(每步只写动作和判定标准,不写背景故事)

## 输出
产物位置、格式、模板

## Pitfalls
一条一行:现象 → 正确做法

目前我现在的implementskill的构成如下

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
implement/SKILL.md (934 行)
├── frontmatter(name + description,description 被污染,见上条)
├── # /implement 概述 (6-26)
├── ## Arguments (27-47)
├── ## Preconditions (48-59)
├── ## Steps (60-847)
│ ├── 1. 取卡 (62-83) [Claude]
│ ├── 1b. 找 Obsidian 里的 plan (84-122) [Claude]
│ ├── 2. 建 feature 分支 (123-168) [Claude]
│ ├── 3. Plan (169-268) [Claude]
│ ├── 3b. 写交接单 (269-343) [仅 --copilot]
│ ├── 3c. 调用 Copilot (344-426) [仅 --copilot]
│ ├── 4. TDD 实现 (427-484) [Claude / --copilot 时 Copilot]
│ │ └── Common pitfalls (485-624, 140 行)
│ ├── 5. lint + 单测 (625-667) [同上]
│ ├── 6. 小步提交 (668-702) [同上]
│ ├── 7. 同步 Postman (703-722) [仅改了 endpoint]
│ ├── 7b. 复核 Copilot 结果 (723-795) [仅 --copilot]
│ ├── 7c. 业务规则对照 (796-816) [两条路径都做]
│ └── 8. 汇报 (817-847) [Claude]
├── ## Rules (848-908)
└── ## Appendix D 结果模板 (909-935) [仅 --copilot]

分层出来之后,就显而意见了,当前的这个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
2
3
4
implement/
├── SKILL.md 主流程 Step 1-8 + Rules,约 500 行以内
├── COPILOT.md Pattern 3,仅 --copilot 时读
└── PITFALLS.md Pattern 1,Step 4 前读

但是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
2
3
4
5
6
implement/
├── SKILL.md Pitfalls 缩成约 30 行(B 类 + 指向下面两个文件的触发条件)
├── COPILOT.md
└── reference/
├── permissions.md 新增或更换 permission 时读
└── persistence-migrations.md 新增 model、加唯一约束、写迁移、加 feature flag 时读
  • 保证不漏读的方式
    • 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.
Comments