这篇解决一个高频问题：Skill 写着写着文件越来越多，最后自己都维护不了。你会得到一条清晰路线：什么时候保持单文件，什么时候拆目录，拆了以后每层放什么，怎么避免后期失控。
本章完成标准
你完成后应该能独立规划一个可维护的 Skill 目录，并能用统一规则管理脚本、模板、示例和资源文件。
先记住一条核心原则
Skill 目录不是越复杂越专业，而是越能支撑迭代越好。先小后大，按复杂度升级。
步骤一：先用最小结构起步
官方最小结构只有一个目录和一个 SKILL.md：
hello-world/
+-- SKILL.md如果你的 Skill 只是流程指令、语气模板、固定输出规则，这一层就够了。
步骤二：出现复杂度再拆目录
满足任意一条就可以考虑拆层：
- 正文出现大段固定模板。
- 开始调用 shell/Node/Python 脚本。
- 需要输入输出示例帮助模型对齐格式。
- 需要存放 schema、样例数据、配置片段。
- 多人协作维护同一个 Skill。
步骤三：按通用目录模板落地
my-skill/
+-- SKILL.md
+-- scripts/
| +-- run.sh
| +-- transform.py
+-- templates/
| +-- output.md
| +-- summary.md
+-- examples/
| +-- input.txt
| +-- expected-output.md
+-- assets/
+-- schema.json
+-- sample-data.json分工建议：
SKILL.md：入口说明、触发条件、执行规则。scripts/：可执行逻辑，避免把长命令塞进正文。templates/：输出骨架和固定文案结构。examples/：输入输出样例，用于对齐行为。assets/：schema、样例数据、静态资源。
步骤四：统一资源引用方式
引用目录内文件时，统一用 {baseDir}：
使用 {baseDir}/templates/summary.md 作为输出模板。
运行 {baseDir}/scripts/transform.py 处理原始数据。不要写本机绝对路径，这会直接破坏可移植性。
步骤五：按“成长路径”升级，不要一次过度设计
- 阶段 1：只有
SKILL.md。 - 阶段 2：增加
templates/。 - 阶段 3：增加
scripts/。 - 阶段 4：补
examples/和assets/。
每次只引入一种复杂度，后续维护成本最低。
6 个最常见结构错误
- 所有文件都塞根目录，几周后无法定位。
- 脚本命名混乱，无法看出用途。
- 模板与资源混放，误删概率高。
- 把长模板塞进
SKILL.md，阅读和修改都很痛苦。 - 路径写死本机目录，换环境即失效。
- 需求很小却提前建了大工程结构。
发布前快速自检
- 目录分层是否一眼可读。
- 脚本是否都在
scripts/，模板是否都在templates/。 - 引用路径是否统一使用
{baseDir}。 - 示例是否最少包含 1 组输入 + 1 组期望输出。
- 删除任意无关文件后，Skill 是否仍可运行。
下一步建议
- 开始接能力：看 调用 Tools / 外部 API。
- 提前排障：看 测试、调试、常见坑。
- 准备发布：看 发布到 ClawHub 完整流程。