authoring-agent-skills

能力目标

把一段领域规范写成一个可挂载的技能目录，挂进智能体后：不相关任务时它只占几十个 token 的摘要、相关任务时智能体自己把全文读进来并严格按规范产出。换一个领域只改三处内容、结构不动。

前置

• 已能构造智能体（见 bootstrapping-deepagents-env）。
• 会写基础 Markdown 与 YAML 头部（就是用三横线包起来的几行键值对）。
• 一个硬依赖：技能加载靠的是智能体手里的 read_file 工具。必须用装具入口 create_deep_agent 构造（它同时配齐技能中间件与文件系统中间件），裸构造器建出来的智能体没有工具节点、看得见技能读不进全文。

实操流程

1. 建目录。技能是一个以技能名命名的目录，不是单个文件：

   WORKSPACE="/path/to/your/workspace"
   mkdir -p "$WORKSPACE/skills/weekly-report/references"
   

   目录结构为技能名目录下放一个必备的技能文件，可选带参考资料目录与脚本目录。目录名必须等于技能文件里 name 字段的值。

2. 写技能文件 SKILL.md，头部两个字段加正文指令：

   ---
   name: weekly-report
   description: Write a structured weekly work report in Chinese. Use when the user asks to draft, create, or write a weekly report or work summary.
   ---
   
   # weekly-report
   
   ## Instructions
   
   When this skill activates, produce a weekly report with exactly three sections:
   
   1. **本周完成** - List tasks completed this week using bullet points.
   2. **进行中** - List work still in progress.
   3. **下周计划** - List planned tasks for next week.
   
   Additional rules:
   - Keep the total under 300 Chinese characters
   - Use concise bullet points (one line each)
   - Start each bullet with a verb
   - Output in Chinese
   
   For detailed format template, see references/template.md
   

   三处要点：name 等于目录名；description 必须写清「做什么 + 什么时候用」，它是常驻阶段唯一进系统提示的实质内容、模型完全靠它判断要不要加载全文；正文末尾指向参考资料的那行引用，会让模型在需要更详细模板时再去读那个文件。

3. 正文保持克制。社区共识是正文控制在 500 行、5000 token 以内，大段模板与长示例下沉到参考资料目录、可执行操作放脚本目录。理由是激活时注入的是正文全文，正文越肥每次激活越贵。

4. 挂进智能体。挂载路径是相对后端根目录的虚拟路径，不是磁盘绝对路径，所以必须显式指定一个把磁盘目录映射成虚拟根的后端：

   from deepagents import create_deep_agent
   from deepagents.backends.filesystem import FilesystemBackend
   
   backend = FilesystemBackend(root_dir=str(WORKSPACE), virtual_mode=True)
   agent = create_deep_agent(
       model=model,
       tools=[],
       skills=["/skills/"],          # 虚拟路径，对应磁盘 WORKSPACE/skills/
       backend=backend,
       system_prompt="你是一个助手。请用中文回答。",
   )
   result = agent.invoke({"messages": [{"role": "user", "content": "帮我写一份本周工作总结……"}]})
   

5. 多来源分层时按优先级从低到高排列，同名技能由靠后的来源覆盖靠前的：

   skills=["/skills/base/", "/skills/project/"]   # 同名时项目层覆盖基线层
   

   来源标签会从路径自动推导。把某个来源指向本机其他智能体工具的技能目录，那些技能会原样出现在清单里——同一份技能文件格式是通用的。

6. 换领域时只改三处：新建目录、技能文件里的 name 与 description、正文指令。接入方式一字不改。

校验回路

• 目录树核对：技能文件与参考资料各就各位；name 等于目录名的断言为真。
• 触发一个匹配任务，检查消息流里出现一次 read_file('/skills/<你的技能名>/SKILL.md', ...)——这一次工具调用就是加载时刻，没有别的匹配器或激活工具。
• 跑一个不相关任务做负例：消息流里 read_file 调用次数为 0、全文自始至终没进上下文。
• 产出严格符合你写的规范（例如恰好三个指定小节），同一技能连跑两次结构一致。
• 想看常驻阶段的开销，就把不触发时的系统提示导出来检查：里面只有技能框架文本加技能名与描述摘要，没有正文。

常见陷阱

• 挂载时传磁盘绝对路径：技能静默不加载、不报错。默认后端不挂载任何磁盘目录，必须用映射后端加虚拟路径。
• 缺 description：框架打印跳过该技能的提示并直接丢弃，技能从清单消失。这是唯一致命的字段错误。
• name 与目录名不一致：只打印一条警告、技能仍会加载。但仍应坚持写成相等，因为依赖精确匹配的多来源覆盖会因此出错。
• 用裸构造器接技能：没有文件系统工具，技能加载不可能发生。必须用装具入口。
• 把「两次 read_file」当成两次激活：正文里若写了指向参考资料的引用，模型读完正文会顺手把引用的文件也读了。那是一次激活加一次按需加载引用，不是两次激活。
• 以为激活后全文会被卸载：不会。全文作为工具返回结果永久留在消息历史里，框架没有卸载逻辑。所以激活的代价是「全文体量 × 激活后的剩余轮数」。
• 以为挂技能一定省 token：常驻的框架文本本身就有约 380 到 400 token 每轮的固定开销（随框架文本与技能数微浮动，是量级估计不是精确值），且每次模型调用都重新注入。玩具体量的技能（正文约 82 token）在只有一到三个技能时是净亏的，要到八个才转正；真实体量的技能（正文约 326 token）从第二个起就开始净省。比较时两侧必须都含或都不含框架开销，混用口径会拼出虚假的净省。膨胀是线性的，不要夸大成指数级。
• 拿「产出更好看」当价值：不带技能的智能体行为是非确定的，强模型有时反而产出更丰富、有时会声称按格式写了却一个标题都没给。技能的准确价值是让格式遵循从可选变成必然，在批量生成与多智能体协作里，行为可预期比单次更好看重要得多。