Skill 的创建、内容结构、运行方式、参数配置，以及多 Skill 协作

Skill 的创建、内容结构、运行方式、参数配置以及多 Skill 协作是 LangChain / Deep Agents 生态中最实用的部分。1. Skill 怎么生成和创建必须包含哪些内容创建方式推荐优先级Deep Agents CLI最方便# 用户级 Skill存在 ~/.deepagents/agent_name/skills/dcode skills create my-skill# 项目级 Skill存在 .deepagents/skills/ 或 skills/dcode skills create my-skill--project会自动生成标准目录和空的SKILL.md。手动创建skills/ └── my-skill/ # 目录名必须与 name 一致 ├── SKILL.md # 必须 ├── scripts/ # 可选可执行脚本 ├── references/ # 可选详细文档 └── assets/ # 可选模板、图标等AI 辅助生成LangSmith Fleet 或对话中直接对 Agent 说“把刚才这个流程做成一个可复用的 Skill”或在 Fleet 中用自然语言描述需求系统自动生成。安装社区/官方 Skillnpx skillsaddlangchain-ai/langchain-skills--skill*--yes# 或指定 skillnpx skillsaddlangchain-ai/langchain-skills--skilllanggraph-fundamentals--yesSKILL.md必须包含的内容YAML Frontmatter必须---name:my-skill# 必须小写字母、数字、连字符1-64 字符必须与目录名一致description:清晰描述这个 Skill 做什么、什么时候用。最多 1024 字符这是 Agent 发现它的关键license:MIT# 可选compatibility:Requires internet# 可选环境要求metadata:# 可选author:your-nameversion:1.0allowed-tools:read_file write_file# 可选预批准的工具列表实验性---Markdown 正文必须写给 Agent 看的指令建议结构# Skill 名称 ## Overview 简要说明用途。 ## When to Use - 明确的触发条件Agent 根据这个判断是否加载 - 用户提到 XXX 时 - 需要做多步骤 YYY 时 ## Instructions 1. 第一步做什么 2. 第二步做什么 3. 决策标准什么情况下用 A 方法什么情况下用 B 方法 4. 成功标准 / 输出格式示例 ## Resources如果有 - 需要时读取 references/xxx.md - 执行脚本时使用 scripts/helper.py最佳实践description写得越精准越好这是发现的关键。正文建议控制在 500 行 / 5000 token 以内。细节放到references/里再在正文中引用。只补充 Agent本身不具备的领域知识或固定流程不要重复通用能力。2. 在 LangChain / Deep Agents 中运行 Skill 的具体指令方式一Deep Agents 原生支持推荐fromdeepagentsimportcreate_deep_agentfromdeepagents.backendsimportFilesystemBackend# 或 StateBackendbackendFilesystemBackend(root_dir.)# 或你的 skills 根目录agentcreate_deep_agent(modelanthropic:claude-sonnet-4-5-20250929,# 或其他模型backendbackend,skills[/skills/,/skills/user/,/skills/project/],# 关键路径列表)# 运行resultagent.invoke({messages:[{role:user,content:帮我写一个复杂的 SQL 查询}]},config{configurable:{thread_id:user-123}})Agent 启动时只会看到所有 Skill 的name description。当它判断当前任务匹配某个 Skill 的 description 时会自动调用文件系统工具read_file加载完整SKILL.md然后按指令执行。方式二普通 LangChain Agent 自定义load_skill工具渐进式披露模式fromlangchain.toolsimporttoolfromlangchain.agentsimportcreate_agent SKILLS{write_sql:{description:SQL 查询专家处理业务数据库查询,content:open(skills/write_sql/SKILL.md).read()},# ...}tooldefload_skill(skill_name:str)-str:当需要某个领域的详细指令时调用此工具加载完整 Skill 内容。ifskill_nameinSKILLS:returnfLoaded skill:{skill_name}\n\n{SKILLS[skill_name][content]}returnfSkill {skill_name} not found. Available:{list(SKILLS.keys())}agentcreate_agent(modelgpt-4.1,tools[load_skill],system_prompt(你是一个助手。可用 Skills\n- write_sql: SQL 查询专家\n- review_legal: 法律文档审核\n需要详细指令时请调用 load_skill 工具。),)3. 运行时的参数配置参数位置说明skillscreate_deep_agent(...)技能源路径列表POSIX 风格如[/skills/, /skills/project/]。后面的源会覆盖同名 Skilllast wins。backendcreate_deep_agent或SkillsMiddleware存储后端FilesystemBackend磁盘、StateBackend内存、StoreBackend跨会话持久化、CompositeBackend混合。sourcesSkillsMiddleware(backend..., sources...)与skills相同可传(path, label)元组来自定义显示名称。system_promptSkillsMiddleware可自定义注入到 system prompt 的模板默认有{skills_list}等占位符。thread_idinvoke的 config用于持久化和多轮对话。allowed-toolsSKILL.md frontmatter实验性限制该 Skill 可使用的工具。示例更完整的配置fromdeepagents.middleware.skillsimportSkillsMiddlewarefromdeepagents.backendsimportFilesystemBackend middlewareSkillsMiddleware(backendFilesystemBackend(root_dir/path/to/root),sources[/skills/base/,(/skills/user/,User),/skills/project/,],)agentcreate_deep_agent(middleware[middleware],# 或直接用 skills 参数# 其他参数...)4. Skill 作为模块多 Skill 如何联系起来运行Skill本身是独立模块默认互不依赖。它们通过以下机制协作自动发现 按需加载Agent 同时看到所有 Skill 的 description根据当前任务自主选择一个或多个相关 Skill 加载。分层覆盖Layeringbase → user → project → team同名 Skill 后面的覆盖前面的。适合“公司通用 项目定制 个人偏好”。在 Skill 内部引用其他资源或其他 Skill在SKILL.md中写如果需要进一步处理结果请先加载 data-cleaning Skill再执行本流程。Agent 会再调用加载工具。与 Sub-agent 结合主 Agent 可以把任务委托给带有特定 Skills 的子 Agentsubagents[{name:sql-expert,skills:[/skills/sql/],# 子 Agent 只拥有自己的 Skills...}]注意自定义子 Agent默认不继承主 Agent 的 Skills必须显式指定。与 Tools / Memory 的配合Skills 提供“怎么做”的流程和知识。Tools 提供“能做什么”的原子动作。MemoryAGENTS.md提供始终存在的偏好和项目约定。Interpreter Skills进阶可在 Skill 中包含可执行模块TypeScript/PythonAgent 通过解释器直接调用函数实现更确定的工作流。总结使用流程创建目录 写好精准的description 详细指令的SKILL.md。把 skills 目录路径传给create_deep_agent(skills[...])或SkillsMiddleware。Agent 启动只加载元数据 → 任务匹配时自动加载完整内容 → 按指令执行可再加载脚本/参考文件。多个 Skill 通过 description 自动路由或在指令中显式互相引用实现松耦合协作。官方推荐优先使用Deep Agents的原生 Skills 支持它已经把渐进式披露、文件系统访问、分层加载都封装好了。如果需要更轻量的实现就用load_skill工具模式。