本讲摘要第 10 讲讲了 Skills 的 3 层渐进式披露骨架frontmatter / SKILL.md 正文 / references/)、本讲深入到为什么是 3 层而不是 1 层或 5 层——这是 Skills 的token 经济性核心命题。本讲用一个真实项目财务分析 Skill贯穿目录页 章节 附录 3 层架构、如何把 token 利用率从 12% 提升到 95%节省 98% 的无效 token。核心命题是怎么分层、怎么索引、怎么按需、让 Skill 加载成本从全量 30K 降到按需 0.5K。本讲的三条主线第一、为什么是 3 层?——1 层全量是上下文爆炸(30K 一次性加载、99% 是无效信息;5 层细分是索引成本反而高维护成本 token 收益;3 层是 LLM 推理 人类工程 的甜区。第二、3 层各自的职责边界——目录页frontmatter,5-10 行、启动时全量加载/ 章节SKILL.md 正文、200 行内、触发时整体加载/ 附录references/、按需加载。第三、Token 经济性的 3 个度量指标——加载率 / 命中率 / 维护成本3 个指标综合评估分层质量。学完本讲、你应该能用 3 层架构设计任意规模的 Skill财务分析 / 代码审查 / 文档生成都能套用、能给每层定清晰的职责边界、能用 3 个度量指标评估现有 Skill 的分层质量、能避免伪 3 层实 1 层的常见陷阱。 详细内容为什么是 3 层?不是 1 层也不是 5 层新人最常问“Skills 的 3 层渐进式披露是约定俗成、还是有工程依据?”——有、3 层是LLM 推理成本 人类维护成本的甜区。少一层不够用、多一层反而累。反面 1:1 层全量不分层把所有内容塞一个文件、30K tokens,Claude 启动时一次性加载。结果每次对话都背着30K 的内容、99% 是不需要的。后果——上下文迅速占满、Claude 注意力分散、关键内容反而被淹没。财务分析的 1 层全量把资产负债表 利润表 现金流 财务比率 行业基准 案例分析 API 文档全塞进 SKILL.md,30K tokens。每次 Claude 启动、不管用户问什么、都先加载这 30K。结果——用户问分析 Q3 现金流,Claude 实际只需要现金流的 0.5K、但被迫看 30K 找 0.5K、效率极低。反面 2:5 层细分过度分层把 SKILL.md 拆成 5 个小文件每个 100 行以内、再分 frontmatter / summary / main / detail / appendix。结果——加载文件数 5 倍增、Claude 推理时不知道该读哪几层、反而要去读所有文件来推断、token 成本更高。维护成本也暴增——改一个东西要同步改 5 个文件。财务分析的 5 层细分frontmatter目录/ summary(1 段总结/ main主题列表/ detail详细步骤/ appendix(API 参考/ examples例子/ troubleshooting排错。结果——7 个文件、每个 50-200 行、Claude 要扫读7 个才知道完整能力。维护成本高token 收益不大、不可行。甜区3 层3 层是 LLM 推理 人类工程 的最优——LLM 只需要看到目录 → 决定读哪章节 → 章节内可能引用附录3 步推理人类维护也只需要维护 frontmatter / SKILL.md / references/ 3 个层面。少一层不够、多一层累。这就像书的结构目录薄、一翻就能看到全书结构 章节中等、核心内容 附录厚、详细参考。读者LLM先看目录决定读哪章、读章节内可能跳到附录、3 步到位。书的结构几千年来就是 3 层——Skill 的 3 层是同一套设计哲学。第 1 层目录页frontmatter的设计原则目录页是 Skill 的门面——Claude 启动时全量加载、每个 Skill 都看到。这层的核心约束“薄 准 不变”。设计原则 1:薄——每个 Skill 的 frontmatter 控制在 5-10 行。超过 10 行、就是 frontmatter 承载了章节内容、分层失败。设计原则 2:准——description 必须写何时触发而不是做什么——和 SubAgent / 普通 Skill 的 description 是同一个规则第 10 讲详细讲过。description 是 LLM 推理的索引键、写错 触发率 0。设计原则 3:不变——目录页尽量少改动。改一次 影响所有 Claude 启动 风险大。稳定的内容放目录身份 / 工具 / 触发场景、变化的内容放章节具体步骤 / 边界 case。反面把详细步骤 / 边界 case也塞进 frontmatter、比如 description 写 200 字、把做什么 怎么做 边界全包了。结果每个 Skill 的 frontmatter 占 300 tokens,10 个 Skill 就是 3K token、占上下文大头。修正frontmatter 只写何时触发 工具 必要元数据、详细步骤放 SKILL.md 正文。目录页的 4 个标准字段name——Skill 唯一标识、小写连字符、反映能力。description——何时触发 触发词、1-2 句话。allowed-tools——可读 / 可写 / 可执行、白名单形式。license可选——MIT / Apache / Proprietary。4 个字段总行数控制在 5-10 行、description 占 2-3 行、其他各 1 行。第 2 层章节SKILL.md 正文的索引结构章节是 Skill 的主体——description 匹配时整段加载、200 行以内。这层的核心约束“结构化 可扫读 完整闭环”。设计原则 1:结构化——章节必须分 3 个二级标题快速参考 / 详细步骤 / 边界 case 反例。每个标题下放该主题的所有要点、不要按时间线 / 叙事顺序组织LLM 不读故事。设计原则 2:可扫读——Claude 加载章节后、需要在 1-2 秒内扫读找到需要的内容。所以章节必须用列表 二级标题 表格、而不是长段落。设计原则 3:完整闭环——章节是该 Skill 的自包含操作手册。读章节 附录就能完成任务、不要假设读者会看其他文件。章节的 3 段式结构快速参考5-10 行——操作清单、给 Claude 一眼看出我该做什么。详细步骤30-50 行——把快速参考的每一步展开、加参数、命令、错误处理。边界 case 反例50-100 行——常见坑、边界情况、典型反例。这是 Claude 遇到规则没说清楚的情况时的兜底参考。3 段加起来 100-200 行最佳。超过 300 行、就把边界 case 反例拆到 references/。章节的职责边界章节是该 Skill 的主要工作流、不是该 Skill 的所有可能操作。所有可能操作 深度文档放 references/。这是主入口 详细文档的常见工程模式。第 3 层附录references/的按需加载附录是 Skill 的百科全书——按需加载、几千行都不嫌多。这层的核心约束“独立 易找 单一职责”。设计原则 1:独立——每份附录文件自包含、读完就能用、不依赖其他附录文件可以引用但不耦合。设计原则 2:易找——文件名清晰、Claude 一搜就能定位。命名规范小写连字符 / 反映内容 / 和章节标题呼应。设计原则 3:单一职责——一份附录只讲一个主题、不要现金流的深度 利润表的深度塞同一份文件。附录的常见内容类型深度文档——章节的完整版、比如章节只写读 git log、附录写git log 的所有参数详解。API 参考——调用的工具 / 库 / 服务的完整 API 文档。边界 case 完整版——章节放高频边界、附录放全量边界章节装不下。反例合集——常见错误 错误示范 修正方法。参考资料——外部链接 / 引用 / 背景知识。附录的命名规范建议• 财务分析 Skill:references/balance-sheet.md / references/income-statement.md / references/cash-flow.md / references/financial-ratios.md / references/industry-benchmarks.md• 命名一致性全小写 / 全连字符 / 不用下划线 / 不用空格 / 不用中文LLM 对英文路径识别更稳。附录的引用方式在 SKILL.md 正文里用详见 references/cash-flow.md的链接方式引用。Claude 实际需要时再读。维度1 层全量3 层甜区5 层细分加载成本30K全量4K按需7K扫读多个文件命中率1.6%(99% 浪费80%甜区60%(LLM 找不准维护成本1改一处1-2章节 附录4多文件同步推理友好度差噪声大好目录 → 章节 → 附录 3 步差LLM 不知读哪几层适用规模极小 Skill(5K)中大型 Skill(5K-50K)理论可行但实际累财务分析 Skill 实战3 层架构的具体落点用一个真实项目财务分析 Skill把 3 层架构落到具体文件。项目背景用户的需求Claude 能帮财务分析师看公司财报、包括资产负债表 / 利润表 / 现金流 / 财务比率 / 行业基准。Skill 触发词“分析财报” / “看 Q3 财务” / “财务比率” / “行业对比”。1 层全量的问题对比基线把所有内容塞 SKILL.md,30K tokens资产负债表章节5K) 利润表章节5K) 现金流章节5K) 财务比率章节5K) 行业基准章节5K) 案例分析3K) API 文档2K。用户问分析 Q3 现金流,Claude 实际需要的是现金流章节5K中的某 0.5K。但被迫加载 30K 找 0.5K。加载率 30K / 30K 100%每次都加载这么多、命中率 0.5K / 30K 1.6%(99% 的内容没用上。3 层架构的方案目录页frontmatter 5-10 行、description 写分析公司财报、包括资产负债表 / 利润表 / 现金流 / 财务比率 / 行业基准。Use when user says ‘分析财报’ / ‘看 Q3 财务’ / ‘财务比率’ / ‘行业对比’.。章节SKILL.md 正文 200 行、3 段式——快速参考财务分析的 5 步流程 详细步骤每步的具体操作 边界 case常见财报问题 反例。附录5 份独立 references/ 文件——balance-sheet.md深度、1.5K)/ income-statement.md(1.5K)/ cash-flow.md(2K)/ financial-ratios.md(1K)/ industry-benchmarks.md(1.5K。用户问分析 Q3 现金流,Claude 推理1) 看到 description 匹配、加载 SKILL.md(2K);2) 看章节的快速参考、知道要读现金流;3) 读 references/cash-flow.md(2K);4) 实际分析 返回。加载总量2K 2K 4K对比全量 30K、节省 87%。用户问对比 Q3 vs Q2 的财务比率,Claude 推理1) 加载 SKILL.md(2K);2) 看章节知道要查财务比率3) 读 references/financial-ratios.md(1K);4) 完成。加载总量2K 1K 3K节省 90%。3 层 vs 1 层的 token 经济性对比平均每次对话加载量1 层 30K,3 层 3K、节省 90%。命中率1 层 1.6%,3 层 80%加载的 3K 实际都用上。加载率1 层 100%,3 层 10%每次只加载需要的 10% 内容。3 层架构的核心收益加载量降 10 倍、命中率升 50 倍、加载率降 10 倍。Token 经济性的 3 个度量指标3 层架构的质量靠 3 个度量指标评估、任一指标异常 架构有问题。指标 1加载率每次实际加载 / 总大小加载率 单次对话实际加载 tokens / Skill 总大小。理想值 5%-15%大部分内容不加载。• 加载率 30% → 分层粒度不够、3 层太厚——章节文件 1000 行、或附录文件太大。• 加载率 2% → 分层粒度过细、5 层——LLM 找内容花的时间比加载还多。• 加载率 5-15% → 甜区、3 层架构正确。财务分析 Skill 加载率3K / 12K 25%、稍高章节 2K 偏厚。修正把详细步骤再拆、正文只留 1K。指标 2命中率加载内容中实际用到的占比命中率 加载内容中实际被引用的 tokens / 加载总量。理想值 80%。• 命中率 50% → 加载了但没用——LLM 扫读完发现关键信息不在那里、白加载了。• 命中率 95% → 加载内容太对题、可能分层不够细其实可以更精准。• 命中率 70-90% → 甜区。财务分析 Skill 命中率加载 3K、实际用到 2.4K、命中率 80%——甜区。指标 3维护成本新增/修改/删除一个内容点要改几个文件维护成本 单个内容点的修改要触达的文件数。理想值 1改一处生效。• 维护成本 3 → 职责重叠章节和附录都有同一信息、改一处忘一处。• 维护成本 1 → 职责清晰、每个信息只在一个地方。• 维护成本 1 是甜区、但 2 也可以接受章节 附录各一份、职责不同。3 个指标综合判断加载率 5-15% / 命中率 70-90% / 维护成本 1-2,3 个都在甜区 3 层架构正确。层内容加载时机典型大小职责第 1 层frontmatterClaude 启动时全量50 tokens身份 触发器 工具白名单第 2 层SKILL.md 正文description 匹配时2K tokens(200 行内主要工作流快速参考 详细步骤 边界 case)第 3 层references/*.mdClaude 实际需要时1.5K tokens/份深度文档 / API 参考 / 完整反例️ 实战代码 第 12 讲配套完整 3 层目录结构.claude/skills/financial-analysis/)# 财务分析 Skill 完整 3 层目录结构 .claude/skills/financial-analysis/ ├── SKILL.md # 第 2 层:章节(200 行内,触发时加载) │ ├── frontmatter (5-10 行) # 第 1 层:目录页(启动时加载) │ ├── 快速参考 (5-10 行) # 章节第 1 段 │ ├── 详细步骤 (30-50 行) # 章节第 2 段 │ └── 边界 case 反例 (50-100) # 章节第 3 段 └── references/ # 第 3 层:附录(按需加载) ├── balance-sheet.md # 资产负债表深度 ├── income-statement.md # 利润表深度 ├── cash-flow.md # 现金流深度 ├── financial-ratios.md # 财务比率深度 └── industry-benchmarks.md # 行业基准深度 # 总大小 12K tokens(目录 50 章节 2K 附录 7.5K) # 实际加载 3K(章节 2K 1 份附录 1K) # 加载率 25% / 命中率 80% / 维护成本 1-2(都在甜区) 第 12 讲配套财务分析 Skill 目录页 frontmatter(5-10 行--- name: financial-analysis description: Analyze company financial reports including balance sheet, income statement, cash flow, financial ratios, and industry benchmarks. Use when user says 分析财报 / 看 Q3 财务 / 财务比率 / 行业对比 / financial analysis. license: MIT allowed-tools: Read, Bash --- # 注:frontmatter 总共 5-10 行,description 占 2-3 行。 # 详细操作步骤放 SKILL.md 正文,深度文档放 references/。 # 目录页薄 准 不变——不承载具体步骤,只承载何时触发。 # 反面示例(❌ description 写 200 字): # description: Analyze company financial reports. First read balance sheet # from src/finance/, then read income statement, then read cash flow, # then compute ratios, then compare with industry benchmarks. Also # handle edge cases like missing data, currency conversion, etc. # → 200 字,占 300 tokens。10 个 Skill 3K token,占上下文大头。 # → 触发细节应该放 SKILL.md 正文,不是 frontmatter。 第 12 讲配套章节文件 SKILL.md 正文快速参考 / 详细步骤 / 边界 case 三段式# financial-analysis:公司财报分析 ## 快速参考(5 步) 1. 确认分析对象(公司名 / 报告期) 2. 读 4 份基础报表(资产负债表 / 利润表 / 现金流 / 所有者权益变动表) 3. 计算 8 类财务比率(流动 / 偿债 / 营运 / 盈利) 4. 对比行业基准(5 个行业) 5. 输出分析报告(结构化 Markdown) ## 详细步骤 ### 1. 确认分析对象 - 公司名 报告期(Q1/Q2/Q3/Q4 或年报) - 数据来源(本地文件 / API / 第三方数据) - 分析目的(投资 / 信贷 / 内部决策) ### 2. 读 4 份基础报表 - 资产负债表:references/balance-sheet.md - 利润表:references/income-statement.md - 现金流:references/cash-flow.md - 所有者权益变动表:references/balance-sheet.md#equity ### 3. 计算 8 类财务比率 - 流动比率 / 速动比率 / 现金比率(短期偿债) - 资产负债率 / 利息保障倍数(长期偿债) - 应收账款周转率 / 存货周转率(营运) - 毛利率 / 净利率 / ROE / ROA(盈利) - 详见 references/financial-ratios.md ### 4. 对比行业基准 - 5 个行业(科技 / 制造 / 金融 / 消费 / 医疗) - 详见 references/industry-benchmarks.md ### 5. 输出分析报告 - 结构化 Markdown(执行摘要 / 财务健康 / 风险点 / 建议) - 写到 .claude/reports/financial-date.md ## 边界 case - 缺数据(只拿到 3 份报表):标注数据不全,用现有数据 提示 - 跨币种(财报是 EUR,基准是 USD):先汇率换算(用 API) - 非标准财年(4 月 - 3 月):标注财年定义,避免误判 - 集团 vs 子公司:分析对象是合并报表还是单体报表,要明确 ## 反例 - ❌ 只看单期数据不做趋势分析(应该对比 3-5 期) - ❌ 只算比率不做行业对比(没有基准的比率没意义) - ❌ 抄报表数字不做解读(读者已经能看原始数据) - ❌ 忽略报表附注(很多关键信息在附注里,不在主表) 第 12 讲配套附录 references/ 5 份文件清单资产负债表深度 / 利润表深度 / 现金流深度 / 财务比率深度 / 行业基准深度# 5 份 references/ 文件的职责边界 # 1. balance-sheet.md(1.5K tokens) # 资产负债表的深度内容: # - 每个科目的标准定义 常见误解 # - 跨期对比的注意事项(会计政策变更) # - 隐性负债的识别方法(表外负债 / 或有事项) # - 配合财报附注的关键字段 # 引用方式:SKILL.md 第 2 步写读 references/balance-sheet.md # 2. income-statement.md(1.5K tokens) # 利润表的深度内容: # - 收入确认的 5 种方法(总额 vs 净额) # - 非经常性损益的识别(避免被一次性收益误导) # - 毛利率波动的归因分析 # - 所得税费用的有效税率分析 # 3. cash-flow.md(2K tokens) # 现金流的深度内容(财务造假的照妖镜): # - 经营 / 投资 / 筹资 三类现金流的解读 # - 经营现金流 vs 净利润的背离分析(警惕纸面富贵) # - 自由现金流的计算(FCF OCF - CapEx) # - 现金循环周期(CCC)对资金链的影响 # 4. financial-ratios.md(1K tokens) # 8 类财务比率的完整定义 计算公式 解读方法: # - 流动比率 / 速动比率 / 现金比率 # - 资产负债率 / 利息保障倍数 # - 应收账款周转率 / 存货周转率 # - 毛利率 / 净利率 / ROE / ROA # 杜邦分析(ROE 拆解为 3 因子) # 5. industry-benchmarks.md(1.5K tokens) # 5 个行业的财务比率基准 解读方法: # - 科技(高 ROE / 低股息 / 高研发占比) # - 制造(中等 ROE / 中等股息 / 关注产能利用率) # - 金融(极高杠杆 / ROA 关键 / 拨备覆盖率) # - 消费(稳定 ROE / 高股息 / 关注渠道库存) # - 医疗(高研发 / 长周期 / 关注管线价值) # 文件命名规范: # - 全小写 # - 全连字符(不用下划线 / 空格 / 中文) # - 和章节标题呼应(balance-sheet 和读 4 份基础报表对应) # - LLM 搜索友好(英文路径识别更稳)⚠️ 常见坑⚠️ 章节文件写 1000 行等同于伪 3 层、实 1 层)最隐蔽的分层失败陷阱目录 章节 附录 3 个文件都建了、但章节文件 1000 行、把该放附录的深度内容也塞进去。结果——每次 Skill 触发、1000 行一次性加载、加载量 5-10 倍于 3 层方案。这等于伪 3 层、实 1 层。修正章节控制在 200 行内、超过 300 行就该拆——把详细文档 / API 参考 / 完整反例移到 references/。判断标准章节 300 行 该拆了。⚠️ 目录页 description 写得太长占太多 token 反而降加载率常见的过载错误description 写 200-500 字、把做什么 怎么做 触发词 边界全包了。结果——每个 Skill 的 frontmatter 占 300-700 tokens,10 个 Skill 3-7K tokens、占上下文 5-10%。加载率看起来高每次都加载、但命中率低很多 detail Claude 用不上。修正description 控制在 1-2 句话、只写何时触发 触发词、细节放章节。判断标准description 100 字 太长。⚠️ 附录命名混乱balancesheet.md vs balance-sheet.md vs 资产负债表.md,Claude 找不到常见的命名不一致陷阱5 份附录文件命名风格不统一——cashflow.md无连字符/ balance-sheet.md有连字符/ 资产负债表.md中文/ income.md简写/ profit-and-loss.md别名。结果——Claude 找文件时不知道该读哪个、经常猜错或扫读多个文件才找到。修正统一命名规范——全小写 / 全连字符 / 不用下划线 / 不用空格 / 不用中文 / 名称和章节标题严格呼应。判断标准5 份附录命名风格完全一致 正确。⚠️ 第 2 层和第 3 层职责重叠边界 case 既在 SKILL.md 又在 references/、改一处忘一处最常见的维护噩梦同一个边界 case既在 SKILL.md 的边界 case段写了、又在 references/edge-cases.md 里写了完整版。结果——某天发现边界 case描述需要更新、改了 SKILL.md 忘了 references/、两份内容不一致、Claude 推理时不知道该信哪个。修正严格分层——SKILL.md 的边界 case段只放高频 简短的 case、完整版 全部 case 放 references/edge-cases.md,SKILL.md 用详见 references/edge-cases.md链接。判断标准同一信息是否在 2 个地方出现?是、职责重叠、该拆。 一句话备忘Skills 的 3 层渐进式披露是LLM 推理 人类维护的甜区——目录页 50 tokens 全量加载做触发器、章节 2K 触发时加载做主工作流、附录按需加载做深度文档加载率 13% 命中率 80% 维护成本 1-2 分层正确。