如何为自己的 Agent 编写 SKILL.md 技能文件frontmatter 格式与按需加载机制【免费下载链接】learn-claude-codeBash is all you need - A nano claude code–like 「agent harness」, built from 0 to 1项目地址: https://gitcode.com/GitHub_Trending/an/learn-claude-code当你有一批领域规范、审查清单或操作流程希望自己的 Agent 在开发任务中遵循时把全文塞进 system prompt 的代价是每次 LLM 调用都会把全部文档发给模型而其中大部分与当前任务无关白白消耗输入 token 和上下文空间。learn-claude-code 仓库的 s07 Skill Loading 章节给出了两层方案system prompt 只保留一份“名称 描述”的技能目录模型需要时再调用load_skill工具把完整的SKILL.md以tool_result形式注入消息列表。本文以仓库中可运行的实现 s07_skill_loading/code.py 为准讲清楚如何按 frontmatter 格式编写自己的技能文件、它怎样被扫描注册以及如何验证按需加载真的生效。适用前提Python 环境 Anthropic SDK 的 harness本仓库 s07 章节技能文件放在工作目录的skills/下。按需加载机制两层知识注入机制的两层结构来源s07_skill_loading/README.md内容进入模型的位置何时加入技能名称和描述system prompt启动时完整SKILL.mdtool_result调用load_skill时三个关键点启动时SkillLoader扫描skills/*/SKILL.md从 YAML frontmatter 读取name和descriptioncatalog()只输出名称与描述列表build_system_prompt()把这份目录拼进 system prompt并附带指令 “Use load_skill to read the full instructions when a skill applies.”。load_skill(name)中的name是查询启动时建立的注册表不会被解释成文件路径工具的输入 schema 只有一个必填的name字段。命中时返回完整文件内容并作为新的tool_result追加进消息列表未命中时返回Error: Unknown skill {name}. Available: {available}注册表为空时available显示为none。返回的内容是SKILL.md的完整原文含 frontmatter不只是正文。启动时组装出的 system prompt 实际长这样目录部分为文档示例仅示意格式You are a coding agent at {WORKDIR}. Use tools to solve tasks. Act, dont explain. Skills available: - code-review: Perform thorough code reviews... - pdf: Process PDF files... Use load_skill to read the full instructions when a skill applies.准备依赖、环境变量与 skills 目录安装 requirements.txt 声明的依赖anthropic0.25.0、python-dotenv1.0.0、pyyaml6.0pip install -r requirements.txt按模板创建.env并填写两个必填项ANTHROPIC_API_KEY和MODEL_ID模板默认claude-sonnet-4-6cp .env.example .env.env的格式见 .env.exampleANTHROPIC_API_KEYsk-ant-xxx MODEL_IDclaude-sonnet-4-6 # ANTHROPIC_BASE_URLhttps://api.anthropic.com如果走 Anthropic 兼容供应商按模板里的注释解开对应的ANTHROPIC_BASE_URL与MODEL_ID组合模板列出了 MiniMax、GLM、Kimi、DeepSeek 的国内外端点。两个代码层面的行为要注意code.py通过MODEL os.environ[MODEL_ID]读取模型名缺失会直接报错退出当设置了ANTHROPIC_BASE_URL时代码会自动移除ANTHROPIC_AUTH_TOKEN。工作目录决定技能扫描位置code.py中WORKDIR Path.cwd()、SKILLS_DIR WORKDIR / skills所以要从仓库根目录运行且技能文件只有放在当前工作目录的skills/下才会被识别。编写 SKILL.md目录结构每个技能是一个直接位于skills/下、包含SKILL.md的目录skills/ code-review/SKILL.md pdf/SKILL.md my-skill/SKILL.md仓库自带的 code-review、pdf、mcp-builder、agent-builder 都是可直接参照的样例。以 code-review 为例完整结构是--- name: code-review description: Perform thorough code reviews with security, performance, and maintainability analysis. Use when user asks to review code, check for bugs, or audit a codebase. --- # Code Review Skill You now have expertise in conducting comprehensive code reviews. Follow this structured approach: ## Review Checklist ...正文即模型加载后要遵循的工作流与检查清单一份最小可用的SKILL.md由两部分组成frontmatter 决定它在目录中的展示方式正文是自由 Markdown写模型加载后应当遵循的完整指令。frontmatter 格式规则解析逻辑在SkillLoader.parse_frontmattercode.py以下每条规则都能在代码和 tests/test_skill_loading.py 的断言中找到依据开头与结尾的---必须各占独立一行。首行必须恰好是------not frontmatter这种写法不会被识别结束符是其后第一个恰好等于---的独立行。因此 YAML 块标量内部的---行不会误关 frontmatter多行description: |中可以安全包含---见test_skill_frontmatter_requires_standalone_delimiters测试用例。frontmatter 必须是 YAML mapping。用yaml.safe_load解析解析出错或结果不是 dict 时按空字典处理等价于没有 frontmatter。name必须是字符串它是技能的注册名——既是目录的 key也是模型调用load_skill时传的参数。name缺失、为空或不是字符串如name: [bad]时自动回退为技能目录名。description必须是字符串。首尾空白被去除内部空白统一折叠为单空格允许多行块标量仓库中 agent-builder 就是这样写的节选--- name: agent-builder description: | Design and build AI agents for any domain. Use when users: (1) ask to create an agent, build an assistant, or design an AI system ... ---折叠后在目录中变成单行。目录的具体行格式由测试断言固定文档示例来自测试所用的 manifest- code-review: Review code for bugs, regressions, and missing tests.description缺失、为空或不是字符串时的回退取正文第一行去掉行首的#与空白并折叠空白。例如正文首行是# Body description时目录中的描述就是Body description正文为空则描述为空字符串。扫描规则哪些文件会被跳过scan()按排序顺序遍历skills_dir.glob(*/SKILL.md)只有同时满足以下条件才会注册位于skills/目录名/SKILL.md这一层skills/直接下一级更深的目录不会被扫到是普通文件名为SKILL.md的目录会被跳过解析后的路径位于 skills 根目录之内——指向skills/外部的符号链接不会注册测试用例linked-skill验证了这一点。整个skills/目录不存在时catalog()输出(no skills found)其余流程不受影响。注册表只在启动时构建一次模块级SKILL_LOADER SkillLoader(SKILLS_DIR)触发scan()。新增、删除或修改技能文件后需要重启进程才会生效。运行与验证在仓库根目录运行 s07 harnesscd learn-claude-code python s07_skill_loading/code.py进入s07 提示符后输入问题输入q退出。README 建议的三个测试 promptWhat skills are available?—— 模型应基于 system prompt 中的目录作答Load the code-review skill and follow its instructions—— 直接触发load_skillReview README.md and load the relevant skill first—— 让模型自行判断该加载哪个技能。验证标准以 README 给出的两个检查点为准system prompt 中只有技能目录名称 描述不包含任何技能的全文完整的SKILL.md只在load_skill被调用之后才出现形态是tool_result消息。tests/test_skill_loading.py 可以直接对照这些行为它断言目录不泄漏正文assert UNIQUE_FULL_INSTRUCTION not in lesson.SYSTEM、load返回完整原始文件、frontmatter 分隔符与回退逻辑、以及 s07 只暴露基础工具加load_skill。常见问题现象依次检查对应代码逻辑新增技能不出现在目录中进程未重启注册表在启动时构建文件不在skills/目录/SKILL.md这一层是指向外部的符号链接整个文件按“无 frontmatter”处理名称用了目录名首行不是独立的---YAML 不是 mapping 或解析失败name缺失、为空或不是字符串触发目录名回退目录中的描述和预期不符description不是字符串或为空回退到正文第一行去除行首#与空白多行描述被折叠成单行目录中描述为空字符串frontmatter 的description与正文第一行都为空测试中---\nname: empty-skill\n---\n的空文件即此情况load_skill返回Error: Unknown skill ...传入名称与 frontmatter 中name的注册名不一致注册名是name值不一定是目录名或技能文件在启动后才变更而未重启。错误信息末尾的Available: ...会列出当前全部注册名可逐一对比边界与下一步这套机制的边界是模型在 system prompt 层面只知道目录load_skill之前它对技能内部一无所知。所以description是否写清“何时使用”直接决定模型会不会主动加载——仓库各样例的Use when ...措辞如 code-review 的 “Use when user asks to review code, check for bugs, or audit a codebase”正是为此服务的。随着工具调用积累messages[]会保留较早的文件内容和工具结果README 指出的下一步是 s08 Context Compact用于缩短较早消息、为后续调用腾出上下文空间。把技能加载组装进完整 agent 循环的集成实现见 s15 Integrated Harness。【免费下载链接】learn-claude-codeBash is all you need - A nano claude code–like 「agent harness」, built from 0 to 1项目地址: https://gitcode.com/GitHub_Trending/an/learn-claude-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
如何为自己的 Agent 编写 SKILL.md 技能文件frontmatter 格式与按需加载机制【免费下载链接】learn-claude-codeBash is all you need - A nano claude code–like 「agent harness」, built from 0 to 1项目地址: https://gitcode.com/GitHub_Trending/an/learn-claude-code当你有一批领域规范、审查清单或操作流程希望自己的 Agent 在开发任务中遵循时把全文塞进 system prompt 的代价是每次 LLM 调用都会把全部文档发给模型而其中大部分与当前任务无关白白消耗输入 token 和上下文空间。learn-claude-code 仓库的 s07 Skill Loading 章节给出了两层方案system prompt 只保留一份“名称 描述”的技能目录模型需要时再调用load_skill工具把完整的SKILL.md以tool_result形式注入消息列表。本文以仓库中可运行的实现 s07_skill_loading/code.py 为准讲清楚如何按 frontmatter 格式编写自己的技能文件、它怎样被扫描注册以及如何验证按需加载真的生效。适用前提Python 环境 Anthropic SDK 的 harness本仓库 s07 章节技能文件放在工作目录的skills/下。按需加载机制两层知识注入机制的两层结构来源s07_skill_loading/README.md内容进入模型的位置何时加入技能名称和描述system prompt启动时完整SKILL.mdtool_result调用load_skill时三个关键点启动时SkillLoader扫描skills/*/SKILL.md从 YAML frontmatter 读取name和descriptioncatalog()只输出名称与描述列表build_system_prompt()把这份目录拼进 system prompt并附带指令 “Use load_skill to read the full instructions when a skill applies.”。load_skill(name)中的name是查询启动时建立的注册表不会被解释成文件路径工具的输入 schema 只有一个必填的name字段。命中时返回完整文件内容并作为新的tool_result追加进消息列表未命中时返回Error: Unknown skill {name}. Available: {available}注册表为空时available显示为none。返回的内容是SKILL.md的完整原文含 frontmatter不只是正文。启动时组装出的 system prompt 实际长这样目录部分为文档示例仅示意格式You are a coding agent at {WORKDIR}. Use tools to solve tasks. Act, dont explain. Skills available: - code-review: Perform thorough code reviews... - pdf: Process PDF files... Use load_skill to read the full instructions when a skill applies.准备依赖、环境变量与 skills 目录安装 requirements.txt 声明的依赖anthropic0.25.0、python-dotenv1.0.0、pyyaml6.0pip install -r requirements.txt按模板创建.env并填写两个必填项ANTHROPIC_API_KEY和MODEL_ID模板默认claude-sonnet-4-6cp .env.example .env.env的格式见 .env.exampleANTHROPIC_API_KEYsk-ant-xxx MODEL_IDclaude-sonnet-4-6 # ANTHROPIC_BASE_URLhttps://api.anthropic.com如果走 Anthropic 兼容供应商按模板里的注释解开对应的ANTHROPIC_BASE_URL与MODEL_ID组合模板列出了 MiniMax、GLM、Kimi、DeepSeek 的国内外端点。两个代码层面的行为要注意code.py通过MODEL os.environ[MODEL_ID]读取模型名缺失会直接报错退出当设置了ANTHROPIC_BASE_URL时代码会自动移除ANTHROPIC_AUTH_TOKEN。工作目录决定技能扫描位置code.py中WORKDIR Path.cwd()、SKILLS_DIR WORKDIR / skills所以要从仓库根目录运行且技能文件只有放在当前工作目录的skills/下才会被识别。编写 SKILL.md目录结构每个技能是一个直接位于skills/下、包含SKILL.md的目录skills/ code-review/SKILL.md pdf/SKILL.md my-skill/SKILL.md仓库自带的 code-review、pdf、mcp-builder、agent-builder 都是可直接参照的样例。以 code-review 为例完整结构是--- name: code-review description: Perform thorough code reviews with security, performance, and maintainability analysis. Use when user asks to review code, check for bugs, or audit a codebase. --- # Code Review Skill You now have expertise in conducting comprehensive code reviews. Follow this structured approach: ## Review Checklist ...正文即模型加载后要遵循的工作流与检查清单一份最小可用的SKILL.md由两部分组成frontmatter 决定它在目录中的展示方式正文是自由 Markdown写模型加载后应当遵循的完整指令。frontmatter 格式规则解析逻辑在SkillLoader.parse_frontmattercode.py以下每条规则都能在代码和 tests/test_skill_loading.py 的断言中找到依据开头与结尾的---必须各占独立一行。首行必须恰好是------not frontmatter这种写法不会被识别结束符是其后第一个恰好等于---的独立行。因此 YAML 块标量内部的---行不会误关 frontmatter多行description: |中可以安全包含---见test_skill_frontmatter_requires_standalone_delimiters测试用例。frontmatter 必须是 YAML mapping。用yaml.safe_load解析解析出错或结果不是 dict 时按空字典处理等价于没有 frontmatter。name必须是字符串它是技能的注册名——既是目录的 key也是模型调用load_skill时传的参数。name缺失、为空或不是字符串如name: [bad]时自动回退为技能目录名。description必须是字符串。首尾空白被去除内部空白统一折叠为单空格允许多行块标量仓库中 agent-builder 就是这样写的节选--- name: agent-builder description: | Design and build AI agents for any domain. Use when users: (1) ask to create an agent, build an assistant, or design an AI system ... ---折叠后在目录中变成单行。目录的具体行格式由测试断言固定文档示例来自测试所用的 manifest- code-review: Review code for bugs, regressions, and missing tests.description缺失、为空或不是字符串时的回退取正文第一行去掉行首的#与空白并折叠空白。例如正文首行是# Body description时目录中的描述就是Body description正文为空则描述为空字符串。扫描规则哪些文件会被跳过scan()按排序顺序遍历skills_dir.glob(*/SKILL.md)只有同时满足以下条件才会注册位于skills/目录名/SKILL.md这一层skills/直接下一级更深的目录不会被扫到是普通文件名为SKILL.md的目录会被跳过解析后的路径位于 skills 根目录之内——指向skills/外部的符号链接不会注册测试用例linked-skill验证了这一点。整个skills/目录不存在时catalog()输出(no skills found)其余流程不受影响。注册表只在启动时构建一次模块级SKILL_LOADER SkillLoader(SKILLS_DIR)触发scan()。新增、删除或修改技能文件后需要重启进程才会生效。运行与验证在仓库根目录运行 s07 harnesscd learn-claude-code python s07_skill_loading/code.py进入s07 提示符后输入问题输入q退出。README 建议的三个测试 promptWhat skills are available?—— 模型应基于 system prompt 中的目录作答Load the code-review skill and follow its instructions—— 直接触发load_skillReview README.md and load the relevant skill first—— 让模型自行判断该加载哪个技能。验证标准以 README 给出的两个检查点为准system prompt 中只有技能目录名称 描述不包含任何技能的全文完整的SKILL.md只在load_skill被调用之后才出现形态是tool_result消息。tests/test_skill_loading.py 可以直接对照这些行为它断言目录不泄漏正文assert UNIQUE_FULL_INSTRUCTION not in lesson.SYSTEM、load返回完整原始文件、frontmatter 分隔符与回退逻辑、以及 s07 只暴露基础工具加load_skill。常见问题现象依次检查对应代码逻辑新增技能不出现在目录中进程未重启注册表在启动时构建文件不在skills/目录/SKILL.md这一层是指向外部的符号链接整个文件按“无 frontmatter”处理名称用了目录名首行不是独立的---YAML 不是 mapping 或解析失败name缺失、为空或不是字符串触发目录名回退目录中的描述和预期不符description不是字符串或为空回退到正文第一行去除行首#与空白多行描述被折叠成单行目录中描述为空字符串frontmatter 的description与正文第一行都为空测试中---\nname: empty-skill\n---\n的空文件即此情况load_skill返回Error: Unknown skill ...传入名称与 frontmatter 中name的注册名不一致注册名是name值不一定是目录名或技能文件在启动后才变更而未重启。错误信息末尾的Available: ...会列出当前全部注册名可逐一对比边界与下一步这套机制的边界是模型在 system prompt 层面只知道目录load_skill之前它对技能内部一无所知。所以description是否写清“何时使用”直接决定模型会不会主动加载——仓库各样例的Use when ...措辞如 code-review 的 “Use when user asks to review code, check for bugs, or audit a codebase”正是为此服务的。随着工具调用积累messages[]会保留较早的文件内容和工具结果README 指出的下一步是 s08 Context Compact用于缩短较早消息、为后续调用腾出上下文空间。把技能加载组装进完整 agent 循环的集成实现见 s15 Integrated Harness。【免费下载链接】learn-claude-codeBash is all you need - A nano claude code–like 「agent harness」, built from 0 to 1项目地址: https://gitcode.com/GitHub_Trending/an/learn-claude-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
