系列《把经验封装成能力Agent Skills 设计与落地》本文是系列第六篇。上一篇我们讲了渐进式加载SKILL.md应该保留主流程和资源路由长资料、脚本和静态资源应该按需加载。这一篇继续往下走专门讨论 Skill 里的资源应该怎么组织什么时候用scripts/什么时候用references/什么时候用assets/。1. 为什么目录组织会影响 Skill 质量写 Skill 时很多人一开始只关注SKILL.md。这没有错。SKILL.md是入口是最小可用结构也是 Agent 触发后最先读取的主说明。但当 Skill 逐渐变复杂仅靠一个文件很快会遇到问题主流程被大量细节淹没。长参考资料每次都占用上下文。确定性操作反复让模型手工完成。模板、示例文件和素材没有稳定位置。修改某个局部时容易影响整套 Skill。这时目录组织就不只是“文件放哪里”的问题而是 Skill 的架构问题。一个好的 Skill 目录应该让 Agent 和维护者都能快速回答主流程在哪里长知识在哪里可执行工具在哪里模板和静态资源在哪里什么时候该读取或调用某个资源如果这些问题答不出来Skill 就会逐渐变成一个大杂烩。2. Skill 的四类内容在设计目录前先把 Skill 内容分成四类。内容类型典型位置作用主流程SKILL.md说明触发后如何执行任务参考资料references/存放长文档、规范、案例、API 说明可执行逻辑scripts/处理确定性、重复性、可验证的操作静态资源assets/存放模板、图片、字体、示例文件等资源这四类内容的区别决定了它们应该放在哪里。可以先记住一个简化判断要让 Agent 每次都知道的主流程放SKILL.md。要让 Agent 按需阅读的长知识放references/。要让程序稳定执行的操作放scripts/。要被复制、引用、嵌入或作为产物素材的文件放assets/。3. 先看一个最小目录一个中等复杂度 Skill 可以从这个结构开始weekly-report/ ├── SKILL.md ├── references/ │ ├── style-guide.md │ └── examples.md ├── scripts/ │ └── validate_report.py └── assets/ └── weekly-report-template.md这个结构里SKILL.md负责说明生成周报的主流程。references/style-guide.md负责存放写作风格和表达规范。references/examples.md负责存放优秀周报样例和反例。scripts/validate_report.py负责校验输出是否包含必要字段。assets/weekly-report-template.md负责提供可复用模板。这比把所有内容都放进SKILL.md更清楚。同时它也比随意创建很多目录更克制。目录不是越多越专业而是要和任务复杂度匹配。4.SKILL.md保留主流程和路由虽然这一篇重点讲资源目录但还是要先明确SKILL.md的职责。它应该保留Skill 的目标。适用范围和不适用范围。输入要求。主执行流程。输出格式。质量标准。安全边界。资源路由。它不应该变成完整 API 文档。所有语言的 SDK 示例集合。大量历史案例堆叠。脚本源码复制。图片、模板、字体等静态资源的文本化版本。换句话说SKILL.md应该像一个任务调度器它知道当前任务怎么走也知道什么时候去找哪个资源。例如## Resource Routing - Read references/style-guide.md when the user asks to polish tone or wording. - Read references/examples.md when the user asks for examples or when the output style is unclear. - Use assets/weekly-report-template.md when the user asks for a reusable weekly report template. - Run scripts/validate_report.py --help before validating a generated report file.这段路由比“更多资料见 references 目录”有用得多。Agent 需要的不只是资源路径还需要使用时机。5.scripts/把确定性工作交给程序scripts/适合放可执行代码。它的核心价值是把稳定、重复、可验证的工作从模型手里拿出来交给程序完成。5.1 什么时候应该用scripts/适合脚本化的任务通常有这些特点规则明确。重复执行。输入输出可定义。结果可以校验。模型手工处理容易出错。失败时需要明确错误信息。例如校验 Markdown 标题层级。检查输出是否包含必填章节。将.docx解包并读取 XML。接受 Word 文档里的修订。重新计算 Excel 公式。启动本地 Web 服务并运行自动化测试。批量转换文件格式。聚合评估结果并生成报告。这些操作不需要模型每次“凭感觉”完成。脚本能提供更稳定的行为。5.2 什么时候不该用scripts/也不是所有逻辑都应该脚本化。不适合放进脚本的内容包括需要大量语义判断的任务。需要和用户反复确认的策略决策。变化很快、尚未稳定的流程。只是为了包装一两行说明的薄脚本。有复杂副作用但缺少安全控制的操作。例如“判断一篇文章的大纲是否有读者价值”更适合 Agent“检查 Markdown 是否包含目标读者和实践任务两个标题”更适合脚本。两者可以配合但不要互相替代。5.3 脚本应该像工具不应该像谜题Agent 使用脚本时最需要的是清晰接口。一个 Agent 友好的脚本应该具备清晰的文件名。--help。明确参数。稳定输出。非零退出码表示失败。可行动的错误信息。尽量避免隐藏副作用。例如python scripts/validate_report.py--helppython scripts/validate_report.py output.md脚本输出应该像这样OK: report contains all required sections.或者ERROR: missing required section: 本周风险这比输出一大段调试日志更适合 Agent 消化。5.4SKILL.md中如何引用脚本不要只写“可以使用 scripts 里的脚本”。应该写清楚脚本用途。什么时候调用。调用前是否先运行--help。失败时怎么处理。是否有副作用。例如## Scripts - Use scripts/validate_report.py after generating a weekly report file. - Always run python scripts/validate_report.py --help before first use. - If validation fails, fix the report and run the script again. - Do not ignore validation errors in the final response.这样 Agent 才知道脚本不是摆设而是流程的一部分。5.5 仓库里的例子这个项目里有几个很好的脚本型例子。docxSkill 把 Word 文档处理的一些确定性操作放进scripts/例如接受修订、处理评论。Word 文档底层是压缩包和 XML让模型手工编辑容易出错用脚本封装更稳。xlsxSkill 有scripts/recalc.py用于重新计算表格公式。公式重算是非常明确的确定性操作适合脚本而不是模型模拟。webapp-testingSkill 有scripts/with_server.py用于管理本地服务生命周期。它还明确要求先运行--help把脚本当黑盒工具使用避免不必要地读取源码污染上下文。skill-creatorSkill 也有多个脚本用于校验、打包、运行评估和生成报告。这类元工具工作流非常适合脚本化因为它们重复、可验证而且需要稳定输出。6.references/把长知识拆成按需资料references/适合放 Agent 需要阅读的长资料。它的核心价值是让主文件保持轻量同时保留复杂任务所需的知识深度。6.1 什么时候应该用references/适合放进references/的内容包括风格指南。API 文档摘要。语言或框架专项说明。平台差异说明。复杂案例。输出示例和反例。评审 checklist。术语表。迁移指南。故障排查手册。这些内容通常有一个共同点有价值但不一定每次都需要。如果每次都放进SKILL.md上下文成本会很高。6.2 什么时候不该用references/不适合拆到references/的内容包括每次都必须遵守的安全规则。任务主流程。Skill 触发条件。最基本的输出格式。缺失信息时的处理原则。这些内容应该留在SKILL.md。原因很简单如果 Agent 没有读取某个参考文件也必须知道这些关键规则。安全边界尤其不能藏得太深。6.3 参考文件应该怎么写一个好的参考文件不是随便堆资料。建议包含文件用途。适用场景。目录。核心规则。示例。常见误区。必要时给出检查清单。例如# Weekly Report Style Guide Use this file when polishing the tone, structure, or wording of a weekly report. ## Table of Contents 1. Reader expectations 2. Recommended tone 3. Section writing rules 4. Good examples 5. Common mistakes参考文件越长越需要目录和稳定标题。6.4 参考文件的拆分维度常见拆分维度有拆分方式适用场景示例按语言SDK、代码生成、API 接入python.md、typescript.md按平台云服务、部署、数据库aws.md、bytecloud.md按任务阶段规划、实现、测试、发布planning.md、testing.md按功能模块鉴权、流式、工具调用、错误处理auth.md、streaming.md按复杂度快速开始、高级配置、故障排查quick-start.md、advanced.md拆分的目标不是文件更小而是读取路径更准确。6.5SKILL.md中如何引用参考资料引用参考资料时要写得具体。不推荐Read files in references/ if needed.推荐## References - Read references/style-guide.md when polishing wording or tone. - Read references/examples.md when the user asks for examples or when the desired style is unclear. - Read references/review-checklist.md before reviewing an existing weekly report.如果参考资料很多也可以用表格| File | Read When | | --- | --- | | references/style-guide.md | Polishing tone or wording | | references/examples.md | Needing examples or style alignment | | references/review-checklist.md | Reviewing an existing report |表格对维护者也很友好。7.assets/存放模板和静态资源assets/适合放静态文件。它和references/的区别是references/主要是给 Agent 阅读的知识。assets/主要是给任务使用、复制、嵌入或作为产物基础的资源。7.1 什么时候应该用assets/适合放进assets/的内容包括Markdown 模板。Word 模板。PPT 模板。示例输入文件。示例输出文件。图片素材。图标。字体。HTML 模板。配置样例。例如assets/ ├── weekly-report-template.md ├── review-template.md └── sample-report.md如果用户要“给我一个可复用模板”Agent 可以直接基于assets/weekly-report-template.md。7.2 什么时候不该用assets/不适合放进assets/的内容包括任务主流程。长篇规范说明。需要频繁编辑的判断规则。脚本逻辑。敏感信息。尤其不要把 token、账号、内部生产地址、私钥、客户数据放进资产文件。资产文件经常会被复制、打包或作为产物的一部分使用敏感信息放在这里风险很高。7.3 资产文件要有清晰命名文件名应该表达用途。推荐weekly-report-template.md incident-review-template.md blog-outline-template.md sample-input.csv sample-output.xlsx不推荐template.md new.md final.md demo2.md copy.md资产文件通常会被 Agent 直接引用或复制命名越清楚误用越少。7.4SKILL.md中如何引用资产引用资产时也要写使用场景。例如## Assets - Use assets/weekly-report-template.md when the user asks for a reusable weekly report template. - Use assets/sample-report.md only as a style example; do not copy project-specific details from it. - Use assets/review-template.md when reviewing an existing weekly report.注意第二条示例资产常常包含具体内容Agent 需要知道哪些可以模仿哪些不能复制。8.examples/要不要单独建有些 Skill 会出现examples/目录。严格来说示例可以放在references/也可以放在assets/甚至单独放examples/。关键取决于示例的用途。示例用途推荐位置给 Agent 阅读理解模式和风格references/examples.md作为可复制或可运行的输入输出文件assets/作为代码运行样例examples/或scripts/examples/例如webapp-testingSkill 使用了examples/来存放 Playwright 使用示例。这类示例更接近“可参考的代码样例”单独建目录也合理。如果你的 Skill 还很小不建议一开始就建太多目录。可以先把示例放在references/examples.md等示例变成可运行代码或独立样本文件时再拆出去。9.agents/、evals/、shared/这些目录怎么理解除了三个基础目录有些复杂 Skill 还会出现其他目录。9.1agents/agents/通常用于存放子 Agent 或评估 Agent 的角色说明。例如一个 Skill 创建工具可能需要分析器。对比器。评分器。这些角色本身不是主流程也不是普通参考资料所以可以单独放agents/。9.2evals/evals/适合存放评估用例、测试 prompt、期望输出和评分配置。当 Skill 需要持续评估触发效果、输出质量或回归问题时可以引入这个目录。如果只是第一版 Skill不必急着加。9.3shared/shared/适合放多个语言、平台或模块都需要的公共资料。例如references/ ├── shared/ │ ├── auth.md │ └── concepts.md ├── python.md └── typescript.md使用shared/的目的是减少重复。但也要克制。过早抽象会让目录变复杂第一版可以先保持简单。10. 目录命名原则目录命名看似小事但会影响长期维护。10.1 按用途命名而不是按作者习惯命名推荐references/ scripts/ assets/ examples/不推荐stuff/ misc/ my-files/ docs2/ old/按用途命名Agent 和维护者都更容易理解。10.2 文件名要能表达任务对象推荐references/error-handling.md references/streaming.md scripts/validate_output.py assets/blog-outline-template.md不推荐references/notes.md references/more.md scripts/tool.py assets/template.md当 Skill 变大时模糊命名会迅速制造维护成本。10.3 层级不要太深大多数 Skill 保持一到两层目录就够了。不推荐references/ └── docs/ └── advanced/ └── language/ └── python/ └── examples/ └── streaming.md推荐references/ ├── python-streaming.md ├── python-tools.md └── troubleshooting.md目录太深会增加路径查找成本也不利于在SKILL.md中清晰路由。10.4 避免用状态命名文件不推荐final.md new.md old.md latest.md v2.md这些名字很快会过期。更好的方式是按内容命名series-planning.md review-checklist.md publishing-notes.md如果确实需要版本建议在文件内说明版本和更新时间而不是用final_final_v3.md这类文件名。11. 如何从单文件 Skill 演进到多目录 Skill不要一开始就追求复杂目录。一个更稳妥的演进路径是11.1 第一阶段只有SKILL.md适合刚开始验证一个任务是否值得 Skill 化。weekly-report/ └── SKILL.md这时重点是写清触发、流程、输出和质量标准。11.2 第二阶段增加references/当你发现正文里出现了很多长规则、样例或风格说明就可以拆参考资料。weekly-report/ ├── SKILL.md └── references/ ├── style-guide.md └── examples.md主文件补上引用规则。11.3 第三阶段增加assets/当用户开始反复要模板或示例文件就可以增加资产。weekly-report/ ├── SKILL.md ├── references/ │ ├── style-guide.md │ └── examples.md └── assets/ └── weekly-report-template.md这时模板和参考说明分开职责更清楚。11.4 第四阶段增加scripts/当某些检查、转换或生成步骤反复出现并且规则稳定就增加脚本。weekly-report/ ├── SKILL.md ├── references/ │ ├── style-guide.md │ └── examples.md ├── assets/ │ └── weekly-report-template.md └── scripts/ └── validate_report.py脚本引入后要在SKILL.md中写清调用时机和失败处理。这个演进过程比一开始创建一堆空目录更健康。12. 一个完整示例生成周报 Skill我们用“生成周报”来设计一个 Skill 目录。目标是用户提供一周工作内容、风险、进展和下周计划Agent 生成一份面向团队或主管的周报。12.1 最小版本weekly-report/ └── SKILL.mdSKILL.md包含description。输入要求。生成流程。输出格式。质量标准。这个版本适合验证任务。12.2 增加参考资料当你发现周报风格要求越来越多可以拆成weekly-report/ ├── SKILL.md └── references/ ├── style-guide.md ├── examples.md └── review-checklist.md文件用途文件用途style-guide.md说明周报语气、粒度和表达风格examples.md存放优秀示例和反例review-checklist.md生成后做质量检查12.3 增加模板资产当模板变成可复用资产可以增加weekly-report/ ├── SKILL.md ├── references/ │ ├── style-guide.md │ ├── examples.md │ └── review-checklist.md └── assets/ └── weekly-report-template.md模板可以包含# 周报[日期范围] ## 本周重点 ## 主要进展 ## 风险与阻塞 ## 下周计划 ## 需要协同的事项注意模板放assets/模板解释和写作规则放references/。12.4 增加校验脚本当你希望稳定检查周报字段可以增加weekly-report/ ├── SKILL.md ├── references/ │ ├── style-guide.md │ ├── examples.md │ └── review-checklist.md ├── assets/ │ └── weekly-report-template.md └── scripts/ └── validate_report.py脚本负责检查是否包含必填章节。是否有空章节。是否缺少下周计划。是否缺少风险或明确说明“暂无风险”。Agent 负责判断内容表达是否清楚脚本负责检查结构完整性。12.5SKILL.md中的路由写法可以这样写## Resource Routing - Read references/style-guide.md when the user asks for a polished or manager-facing weekly report. - Read references/examples.md when the user asks for examples or the expected style is unclear. - Read references/review-checklist.md before finalizing a generated weekly report. - Use assets/weekly-report-template.md when the user asks for a reusable template. - Run python scripts/validate_report.py --help before validating a report file. - Run python scripts/validate_report.py file after writing a report to disk.这样每个资源都有明确用途。13. 资源引用的粒度资源引用太粗Agent 不知道怎么用引用太细SKILL.md又会变得啰嗦。13.1 太粗的引用Use the files in this skill as needed.这句话几乎没有指导价值。13.2 太细的引用Read line 1 to 12 of references/style-guide.md when the user asks for tone, read line 13 to 26 when the user asks for structure, read line 27 to 45 when the user asks for examples...这种写法维护成本太高。参考文件稍微改动行号就可能失效。13.3 合适的引用- Read references/style-guide.md when the task involves tone, wording, or audience-specific expression. - Read references/review-checklist.md before final review.它明确但不过度绑定具体行号。14. 安全和副作用边界资源组织还要考虑安全。14.1 脚本副作用要写清楚如果脚本会修改文件、删除临时目录、访问网络、启动服务或生成输出文件要在SKILL.md或脚本--help中写清楚。例如- scripts/clean_output.py deletes generated files under tmp/output/. Do not run it unless the user asks to clean generated artifacts.这种说明能避免误调用。14.2 资产不要包含敏感信息模板和示例经常被复制到最终产物里。因此不要在assets/中放token。密码。私钥。真实客户数据。生产环境地址。未脱敏日志。如果需要示例数据用脱敏或虚构数据。14.3 安全规则不要藏在深层参考文件例如“不要执行破坏性数据库操作”“修改生产配置前必须确认”“不要上传敏感文件到外部服务”这些规则应该写在SKILL.md的主流程或安全章节里。参考文件可以补充细节但主文件必须保留关键边界。15. 目录组织的反例15.1 所有内容都在SKILL.mdmy-skill/ └── SKILL.md如果SKILL.md已经包含几百行 API 文档、几十个示例和多个脚本说明就会越来越难维护。15.2 所有东西都叫 docsmy-skill/ ├── SKILL.md └── docs/ ├── script.py ├── template.md └── api.md这里脚本、模板、参考资料混在一起职责不清。15.3 目录按作者习惯命名my-skill/ ├── SKILL.md ├── alice/ ├── old/ ├── misc/ └── final/这种结构对 Agent 和新维护者都不友好。15.4 资源拆出去但没有路由my-skill/ ├── SKILL.md └── references/ ├── a.md ├── b.md └── c.md如果SKILL.md没写什么时候读哪个文件拆分就没有形成渐进式加载。15.5 脚本没有帮助信息scripts/run.py如果脚本没有--help没有参数说明输出也不稳定Agent 使用它就会依赖猜测。这会降低脚本带来的确定性收益。16. 目录设计自查清单设计或重构 Skill 目录时可以用下面这张表检查。检查项问题主流程SKILL.md是否只保留主流程、边界和路由参考资料长知识是否拆到references/脚本确定性、重复性操作是否放到scripts/资产模板、示例文件、图片、字体是否放到assets/路由SKILL.md是否写清每个资源什么时候使用命名文件名是否表达用途而不是new、final、misc层级目录层级是否控制在容易理解的范围内去重通用内容是否避免在多个参考文件中复制安全敏感信息是否没有出现在脚本、参考资料和资产中副作用有副作用的脚本是否写清了行为和使用条件维护修改某个子领域时是否只需要改少数文件如果一个目录结构能通过这张清单大概率已经具备不错的可维护性。17. 常见误区17.1 误区一目录越多越专业目录多不代表结构好。如果一个 Skill 只有一页说明就不需要提前创建scripts/、references/、assets/、examples/、evals/。目录应该随着复杂度增长而不是为了显得完整而存在。17.2 误区二脚本可以解决所有不稳定脚本能解决确定性问题但不能替代语义判断。不要把“判断文章是否有洞察”“判断方案是否合理”这种任务强行脚本化。17.3 误区三参考资料越全越好参考资料的目标不是堆满而是好定位、好读取、好更新。如果一个参考文件又长又没有目录Agent 读取它时仍然会迷路。17.4 误区四模板就是规范模板只定义结构不一定定义质量。例如周报模板里有“风险与阻塞”标题但它不说明风险应该怎么写。写法规则应该放在references/style-guide.md或references/review-checklist.md。17.5 误区五资源拆分后不用维护路由路由是多文件 Skill 的关键。没有路由的references/、scripts/、assets/只是把混乱从一个文件移动到多个文件。18. 小结这一篇讲的是 Skill 的资源组织。可以记住三句话SKILL.md放主流程和资源路由负责告诉 Agent 当前任务怎么走。references/放按需阅读的长知识scripts/放确定性可执行逻辑assets/放模板和静态资源。目录设计的关键不是“拆开”而是拆开之后仍然有清晰的使用时机、命名和维护边界。如果第五篇解决的是“为什么要按需加载”第六篇解决的就是“按需加载的资源应该如何落到目录结构里”。下一篇我们会深入scripts/为什么要把确定性工作交给程序以及如何设计一个 Agent 友好的脚本接口。19. 实践任务请为一个“生成周报”的 Skill 设计目录结构并说明每个文件的用途。可以按下面步骤做先写最小目录只包含SKILL.md。判断哪些内容属于长知识拆到references/。判断是否需要模板放到assets/。判断是否有确定性校验放到scripts/。回到SKILL.md写清资源路由。可以使用这个模板weekly-report/ ├── SKILL.md ├── references/ │ ├── style-guide.md │ ├── examples.md │ └── review-checklist.md ├── assets/ │ └── weekly-report-template.md └── scripts/ └── validate_report.py文件用途表文件用途什么时候使用SKILL.md主流程和资源路由每次 Skill 触发后references/style-guide.md周报风格规范需要润色或面向管理者输出时references/examples.md示例和反例风格不明确或用户要示例时references/review-checklist.md质量检查清单最终输出前assets/weekly-report-template.md可复用模板用户要求模板时scripts/validate_report.py结构完整性校验写入文件后进行校验时最后在SKILL.md中补一段## Resource Routing - Read references/style-guide.md when polishing tone or wording. - Read references/examples.md when the expected style is unclear. - Read references/review-checklist.md before final review. - Use assets/weekly-report-template.md when the user asks for a reusable template. - Run python scripts/validate_report.py --help before validating a report file.做完这个练习你会更清楚地看到一个 Skill 的目录结构本质上是在表达“哪些经验是主流程哪些知识按需读取哪些操作交给程序哪些资源可以直接复用”。