母文之外：Skill 文件树七式——热度前三名都不是一篇文档

概述

一、为什么是文件树：三个信号

信号二是本栏自己的测量史。体重学那期量过从一行到全家桶的体重谱系，结论是体重与职责同步膨胀；但量了重量没量分工——19 个文件各自干什么活、文件之间靠什么协作，从未入档。信号三是最实际的一条：用户装完一个 Skill，看到的第一眼不是描述——描述只在路由瞬间常驻，装完之后常驻的是目录。ls 敲下去，文件树就是这个 Skill 的第二门面。描述管唤起，树管信任——这两层的设计纪律是两套学问，后一套至今没人系统讲过。

二、解剖台：一棵 19 文件的一手树

本机 /home/gprshome/skills/skill-creator/ 的一手 Glob 清点，19 个条目原样呈现：

skill-creator/
├── SKILL.md                    # 根上唯一的 .md
├── LICENSE.txt
├── agents/
│   ├── analyzer.md             # 分析角色
│   ├── comparator.md           # 对照角色
│   └── grader.md               # 评分角色
├── references/
│   └── schemas.md              # 契约集中地
├── assets/
│   └── eval_review.html        # 人审界面模板
├── eval-viewer/
│   └── generate_review.py      # 评审页生成器
└── scripts/
    ├── __init__.py
    ├── utils.py                # 共享库
    ├── init_skill.py           # 脚手架
    ├── quick_validate.py       # 体检
    ├── run_eval.py             # 评测
    ├── aggregate_benchmark.py  # 汇总
    ├── improve_description.py  # 优化
    ├── run_loop.py             # 闭环
    ├── package_skill.py        # 打包
    └── __pycache__/            # 一手物证
        ├── quick_validate.cpython-313.pyc
        └── quick_validate.cpython-39.pyc

两个先手事实值得钉在墙上。其一：根上没有 README。官方母文 19 个文件里，唯一的根级文档就是 SKILL.md——它没把 README 和 SKILL.md 写成两份，SKILL.md 即门面。给读者的判据：你的 Skill 若要写 README，先回答「为什么这句话不写进 SKILL.md」。其二：__pycache__ 里恰好只有 quick_validate 一个模块的两个版本编译产物——.pyc 只在模块被导入时生成，两个版本并存说明它在 CPython 3.13 与 3.9 下都真实执行过※；而 scripts 下其余七个入口脚本没有一个留下编译痕迹，符合「入口脚本以 __main__ 直跑、被导入的模块才留 pyc」的解释器行为※。文件树会作证，这是本期全部七式的元命题。

三、评测对比表

权重沿用本栏固定口径：功能 25%、设计 25%、实战 20%、上手 15%（越高越容易）、社区 15%。分数全部沿用已读存档的印刷值，本期不重复估分；无存档总分的两座头部仓库列观察位。

评分说明：四行分数均为各存档期原文印刷值，本期不复议；两座未核验仓库不给数，是因为本期的全部论点恰恰是「树没看过就没有发言权」——不能一边主张树是设计单位、一边对没看过的树打分。

四、文件树七式

式一：一目录一动词式

五个子目录，五个单一职责：scripts 执、references 查、assets 产、agents 演、eval-viewer 审。没有一个目录名需要解释，树本身就是 API 文档。对照官方 SKILL.md 存档里给的三分法（scripts 管确定性任务、references 管按需载入、assets 管输出资产），真实安装多出来的两个目录（agents、eval-viewer）没有挤进老三类，而是各自立户——职责长出来就新增目录，不往旧目录里塞。社区件的常见病正相反：一个 scripts/ 里塞着生成器、校验器、打包器，目录名退化为「杂物间」。

式二：角色文件式

agents/ 下三份 .md，analyzer、comparator、grader——分析、对照、评分三种劳动，一角色一文件（内容未读，角色分工按文件名合约与 09-01 存档记载的评测流程推断※）。这一式在人设件集群（约两百件，普查期已档）里有反面印证：人设件用文件名装一个人，母文用文件名装一个工种。当 SKILL.md 需要以不同身份说话时，正确的反应不是在正文里写「你现在扮演」，而是加一份角色文件——身份是资产，资产进目录。

式三：契约钉死式

契约有两头。数据契约：references/schemas.md 把 schema 集中成一份引用，而 09-01 存档逐字记下了那个著名警告——grading.json 的字段名钉死为 text / passed / evidence，原文特意说「the viewer depends on these exact field names」，不许用 name/met/details 之类的变体。代码契约：utils.py 把共享逻辑收敛一处，七个入口脚本不互相 import 对方※。两头合起来是一句话：目录里的文件靠约定协作，约定的每一段都要有唯一权威出处——schema 改一处，生成器和打分器跟着走。

式四：自带裁判式

quick_validate.py 是全树唯一留下执行痕迹的模块——造 Skill 的件自带体检脚本，而且在两代解释器下真跑过。这一式的可复制版本：你发布的每个 Skill 都该配一个能一键自检的验证器，哪怕只是「SKILL.md 存在、frontmatter 可解析、引用的文件都在」。它同时是本期评测表的评分伦理来源：对一棵没看过的树打分是自相矛盾，验证器的存在让「先验货再打分」从美德变成一行命令。

式五：生命周期映射式

scripts/ 七个文件按生命周期排开：init（脚手架）→ run_eval（评测）→ aggregate_benchmark（汇总）→ improve_description（优化）→ run_loop（闭环）→ package_skill（打包）。目录按动词命名、按序号站队，用户读目录就是读教程——这不是巧合，09-01 存档里 SKILL.md 开篇那句流程鸟瞰（写草稿→跑测试→看反馈→重写）与 scripts/ 的文件清单一一对应。文档说一遍，目录再说一遍，两遍对得上，树就是可信的。

式六：人审界面随件分发式

assets/eval_review.html 加 eval-viewer/generate_review.py——这个 Skill 连「给人看的界面」都当成资产随件分发。09-01 存档记下了全文唯一一处全大写咆哮就留给这里：评审页必须在模型自己评估之前交到用户手里。中间结果不该躺在 JSON 里等人来问，要有专门的生成器把它变成人能看的东西——这是「人是最早的质量关口」在文件树层的落点。

式七：单入口文档式

回到根目录：唯一 .md 是 SKILL.md，其余文档全部下沉 references/，连超 300 行要加目录的细则都写进了存档。反模式是社区常见的 README、SKILL.md、USAGE.md 三头并立——三份文档三份真相，防腐学讲过的版本腐烂在文档层最先发生。一个 Skill 只许一个门面文件，其余都是它的附录。

五、第二门面全景与决策树

flowchart TD
    R["skill-creator 19文件树<br/>一手Glob清点"] --> D1["SKILL.md<br/>根上唯一文档"]
    R --> G1["scripts 八个py<br/>生命周期六段加共享库"]
    R --> G2["agents 三份md<br/>分析 对照 评分"]
    R --> G3["references schemas.md<br/>契约集中地"]
    R --> G4["assets eval_review.html<br/>人审界面模板"]
    R --> G5["eval-viewer<br/>评审页生成器"]
    G1 --> F1["quick_validate<br/>pycache双版本作证"]

把七式翻译成写自己第一个 Skill 的下半篇——09-01 期教过 10 行起步，本表回答「第二个文件什么时候加、加到哪」：

flowchart TD
    A["SKILL.md 写完能跑"] --> B{"同一操作<br/>重复了几次?"}
    B -->|"三次以上"| C["进 scripts 沉淀为脚本"]
    B -->|"未到三次"| D{"正文超过500行?"}
    D -->|"是"| E["按领域拆 references"]
    D -->|"否"| F{"下游脚本<br/>要读你的数据?"}
    F -->|"是"| G["字段名钉死<br/>契约集中一份"]
    F -->|"否"| H{"需要换角色<br/>或分环节?"}
    H -->|"是"| I["一角色一文件"]
    H -->|"否"| J{"用户要看<br/>中间结果?"}
    J -->|"是"| K["配人审页生成器"]
    J -->|"否"| L["保持单文件<br/>发布前写体检脚本"]
    C --> L
    E --> L
    G --> L
    I --> L
    K --> L

安装与使用

# 官方母文（本机已在册，19 文件树已一手核验）
npx skills find skill-creator
git clone --depth 1 https://github.com/anthropics/skills

# 框架三巨头（树未核验，装前先数文件——本期方法论即如此）
npx skills add obra/superpowers
npx skills add mattpocock/skills
npx skills add affaan-m/ECC

# 装完第一件事：把它的第二门面读一遍
find ~/.claude/skills/<名字> -type f | sort
# 再看执行痕迹：有 __pycache__ 的模块，才是真被跑过的模块

推荐排行榜

• 最值得抄的一式：式四 自带裁判——19 文件树里唯一有执行物证的就是体检脚本，官方用 pycache 给「验证先于信任」签了名；成本一个文件，收益是全部下游的可信度。
• 最反直觉的一式：式七 单入口文档——README 不是必备品而是嫌疑犯，母文用缺席投票。
• 最易被忽略的一式：式三 契约钉死——「the viewer depends on these exact field names」是全生态最便宜的前后端课，写在目录里不用写进框架。
• 观察位第一：ECC（4.1）——描述里五个名词（skills/instincts/memory/security/research）大概率就是五个子目录※，树若核实，本期七式可再加一条「名词即部门」；核实之前不升格。
• 本期方法论遗产：对一棵没看过的树不打分——这条纪律比任何一式的分数都值钱。

参考来源

[!tip] 51学通信知识星球 星主：爱卫生（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 星球定位：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 当前规模：5200 篇主题 / 990 个回答，198 元/年。 加入福利：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 AI 加持：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。