前面的随笔讨论了工具、任务恢复和执行边界。接下来还有一个日常问题Agent需要做的事情越来越多每种工作的步骤、模板和注意事项应该放在哪里把所有流程塞进一份长提示词修改和查找都会变得费力。Agent Skills把某一类任务的知识与流程放进独立目录再按任务需要读取。本文从一个虚构的CSV核查技能出发介绍目录结构与分层加载并用小程序观察哪些文件被读取。资料范围截至2026-09-30核对的Agent Skills官方开放格式说明该在线规范未在本文引用页面标注语义版本本文按核对日期说明适用范围。示例使用Python 3.10及以上标准库不调用模型服务也不代表某个Agent产品的完整技能实现。一、一个技能目录组织一类可重复的工作Skill可以包含操作说明、参考材料、模板及脚本。官方格式要求目录内有SKILL.md其中使用YAML frontmatter提供name和description再用Markdown描述任务步骤。name需符合命名约束并与父目录名称一致。见Agent Skills格式规范。一个教学目录可以这样组织csv-review/ ├── SKILL.md ├── references/ │ └── columns.md ├── scripts/ │ └── check_csv.py └── assets/ └── report-template.mdSKILL.md写清楚使用场景、输入、执行步骤和完成条件columns.md放较长的列规则脚本负责确定性的核查模板统一报告格式。目录是组织方式具体读取和执行能力由Agent宿主提供。图中的目录卡用于判断相关性展开的操作册对应完整说明。挑选技能后详细参考材料仍可以等到对应步骤需要时再读取。二、分层加载让当前任务只拿到需要的材料官方把这类方式称为Progressive Disclosure即渐进式披露先发现技能的name与description任务匹配后读取SKILL.md执行时按需读取参考文件或使用脚本。见Agent Skills官方概览。这张图说明加载顺序箭头不代表网络调用也没有表示所有宿主使用同一种内部实现。分层目录减少了把所有材料同时放进当前上下文的需要实际Token开销与任务效果仍应在具体系统中测量。对CSV核查来说初始目录只需让Agent知道“这个技能用于检查CSV列与数据”。决定使用后再读操作步骤检查具体列时再读取columns.md。没有进入报告阶段就无需把报告模板提前展开。三、把步骤写得可执行也写清楚完成条件下面是一段教学用SKILL.md--- name: csv-review description: 检查CSV文件的列名和数据格式。处理CSV核查任务时使用。 --- # CSV核查 1. 确认用户提供的CSV文件与核查范围。 2. 读取references/columns.md确认列规则。 3. 使用允许的工具检查文件记录发现的问题。 4. 根据assets/report-template.md整理核查结果。 完成条件报告包含文件范围、发现的问题与无法判断的项目。这里的步骤是给Agent使用的流程材料。技能文件不能自行扩大工具权限发布、删除或访问额外数据等动作仍要遵守宿主规则与用户授权。scripts目录中的程序也需要先检查来源和执行范围。description适合描述“做什么、什么时候使用”。把大量细节放在发现阶段会削弱分层加载的作用只写“帮助处理数据”又容易让选择范围过宽。四、完整示例观察三个加载阶段下面的程序用内存中的小目录模拟发现阶段再读取对应文件。为突出加载顺序metadata直接写在catalog中没有实现YAML解析、语义选技或模型执行。临时目录里的内容全部由示例创建。frompathlibimportPathfromtempfileimportTemporaryDirectoryclassDemoLoader:def__init__(self,root,catalog):self.rootroot.resolve()self.catalogcatalog self.activeset()self.loaded[]defdiscover(self):returnsorted(self.catalog)defactivate(self,name):ifnamenotinself.catalog:raiseValueError(unknown skill)textself.read(name,SKILL.md)self.active.add(name)returntextdefresource(self,name,relative):ifnamenotinself.active:raiseValueError(activate skill first)returnself.read(name,relative)defread(self,name,relative):ifnamenotinself.catalog:raiseValueError(unknown skill)base(self.root/name).resolve()target(base/relative).resolve()ifnottarget.is_relative_to(base):raiseValueError(outside skill directory)texttarget.read_text(encodingutf-8)self.loaded.append(f{name}/{relative})returntextwithTemporaryDirectory()asfolder:rootPath(folder)skillroot/csv-review(skill/references).mkdir(parentsTrue)(skill/SKILL.md).write_text(---\nname: csv-review\ndescription: 检查CSV列名与数据格式。\n---\n先读取references/columns.md再核查用户提供的文件。\n,encodingutf-8,)(skill/references/columns.md).write_text(必需列name、amount。amount应为非负数。\n,encodingutf-8)catalog{csv-review:{description:检查CSV列名与数据格式。}}loaderDemoLoader(root,catalog)print(discovered:,loader.discover())print(loaded before activation:,len(loader.loaded))loader.activate(csv-review)print(after activation:,loader.loaded)ruleloader.resource(csv-review,references/columns.md)print(rule:,rule.strip())print(loaded files:,len(loader.loaded))try:loader.resource(csv-review,../outside.md)exceptValueError:print(outside path: rejected)else:raiseAssertionError(outside path must be rejected)保存为skills_loading_demo.py后运行python skills_loading_demo.py输出discovered: [csv-review] loaded before activation: 0 after activation: [csv-review/SKILL.md] rule: 必需列name、amount。amount应为非负数。 loaded files: 2 outside path: rejected本例已实际执行。它展示了目录发现与文件读取的区别发现阶段没有读取操作正文激活后读取SKILL.md再按请求读取列规则。最后的检查拒绝指向技能目录之外的路径。路径检查只覆盖这段教学代码的读取边界没有实现脚本沙箱、并发文件替换防护或完整宿主权限系统。示例也没有核查真实CSV更没有把文件读取数量当作模型效果评分。五、与工具接入和长期记忆如何配合从应用设计上可以把三类材料分开组织工具接口提供执行能力Skill提供某类工作的流程与知识长期记忆提供历史记录或偏好。这是本文的职责划分建议并非所有产品都采用相同模块结构。例如CSV核查技能可以指导Agent使用文件读取工具也可以要求先确认用户关心的列。它无须把所有工具协议写进正文更不应把某一次任务的私密输入固化到通用技能里。维护时可以先记录三项信息说明适用哪些输入依赖哪些环境怎样判断完成。规则改动后用几类代表性任务核对触发范围、缺失输入处理与输出同一目录能够跨产品复用也仍需检查各宿主的工具、脚本和发现方式是否兼容。六、 思维导图Agent Skills目录结构SKILL.md入口参考脚本与模板分层加载先看名称与描述激活后读取操作说明执行边界资源按需读取宿主权限继续生效维护验证清楚的触发范围环境与完成条件七、总结总结要点技能目录让某类工作的说明、参考材料与模板集中维护。SKILL.md承担入口职责较长的细节可以拆进对应资源。分层加载让发现、激活和执行阶段拿到不同深度的信息。任务需要什么再读取什么目录结构也应服务这个顺序。执行与验证边界仍由具体宿主落实。技能说明需要明确输入、环境和完成条件资源读取成功之后还要核对任务产物是否满足要求。下一篇随笔继续关注Agent的知识接入结合官方资料讨论检索结果如何保留来源并支持回查。如果你觉得这篇文章对你有所帮助欢迎点赞、收藏、分享
【随笔】Agent Skills如何按需加载：把技能说明放进分层目录
前面的随笔讨论了工具、任务恢复和执行边界。接下来还有一个日常问题Agent需要做的事情越来越多每种工作的步骤、模板和注意事项应该放在哪里把所有流程塞进一份长提示词修改和查找都会变得费力。Agent Skills把某一类任务的知识与流程放进独立目录再按任务需要读取。本文从一个虚构的CSV核查技能出发介绍目录结构与分层加载并用小程序观察哪些文件被读取。资料范围截至2026-09-30核对的Agent Skills官方开放格式说明该在线规范未在本文引用页面标注语义版本本文按核对日期说明适用范围。示例使用Python 3.10及以上标准库不调用模型服务也不代表某个Agent产品的完整技能实现。一、一个技能目录组织一类可重复的工作Skill可以包含操作说明、参考材料、模板及脚本。官方格式要求目录内有SKILL.md其中使用YAML frontmatter提供name和description再用Markdown描述任务步骤。name需符合命名约束并与父目录名称一致。见Agent Skills格式规范。一个教学目录可以这样组织csv-review/ ├── SKILL.md ├── references/ │ └── columns.md ├── scripts/ │ └── check_csv.py └── assets/ └── report-template.mdSKILL.md写清楚使用场景、输入、执行步骤和完成条件columns.md放较长的列规则脚本负责确定性的核查模板统一报告格式。目录是组织方式具体读取和执行能力由Agent宿主提供。图中的目录卡用于判断相关性展开的操作册对应完整说明。挑选技能后详细参考材料仍可以等到对应步骤需要时再读取。二、分层加载让当前任务只拿到需要的材料官方把这类方式称为Progressive Disclosure即渐进式披露先发现技能的name与description任务匹配后读取SKILL.md执行时按需读取参考文件或使用脚本。见Agent Skills官方概览。这张图说明加载顺序箭头不代表网络调用也没有表示所有宿主使用同一种内部实现。分层目录减少了把所有材料同时放进当前上下文的需要实际Token开销与任务效果仍应在具体系统中测量。对CSV核查来说初始目录只需让Agent知道“这个技能用于检查CSV列与数据”。决定使用后再读操作步骤检查具体列时再读取columns.md。没有进入报告阶段就无需把报告模板提前展开。三、把步骤写得可执行也写清楚完成条件下面是一段教学用SKILL.md--- name: csv-review description: 检查CSV文件的列名和数据格式。处理CSV核查任务时使用。 --- # CSV核查 1. 确认用户提供的CSV文件与核查范围。 2. 读取references/columns.md确认列规则。 3. 使用允许的工具检查文件记录发现的问题。 4. 根据assets/report-template.md整理核查结果。 完成条件报告包含文件范围、发现的问题与无法判断的项目。这里的步骤是给Agent使用的流程材料。技能文件不能自行扩大工具权限发布、删除或访问额外数据等动作仍要遵守宿主规则与用户授权。scripts目录中的程序也需要先检查来源和执行范围。description适合描述“做什么、什么时候使用”。把大量细节放在发现阶段会削弱分层加载的作用只写“帮助处理数据”又容易让选择范围过宽。四、完整示例观察三个加载阶段下面的程序用内存中的小目录模拟发现阶段再读取对应文件。为突出加载顺序metadata直接写在catalog中没有实现YAML解析、语义选技或模型执行。临时目录里的内容全部由示例创建。frompathlibimportPathfromtempfileimportTemporaryDirectoryclassDemoLoader:def__init__(self,root,catalog):self.rootroot.resolve()self.catalogcatalog self.activeset()self.loaded[]defdiscover(self):returnsorted(self.catalog)defactivate(self,name):ifnamenotinself.catalog:raiseValueError(unknown skill)textself.read(name,SKILL.md)self.active.add(name)returntextdefresource(self,name,relative):ifnamenotinself.active:raiseValueError(activate skill first)returnself.read(name,relative)defread(self,name,relative):ifnamenotinself.catalog:raiseValueError(unknown skill)base(self.root/name).resolve()target(base/relative).resolve()ifnottarget.is_relative_to(base):raiseValueError(outside skill directory)texttarget.read_text(encodingutf-8)self.loaded.append(f{name}/{relative})returntextwithTemporaryDirectory()asfolder:rootPath(folder)skillroot/csv-review(skill/references).mkdir(parentsTrue)(skill/SKILL.md).write_text(---\nname: csv-review\ndescription: 检查CSV列名与数据格式。\n---\n先读取references/columns.md再核查用户提供的文件。\n,encodingutf-8,)(skill/references/columns.md).write_text(必需列name、amount。amount应为非负数。\n,encodingutf-8)catalog{csv-review:{description:检查CSV列名与数据格式。}}loaderDemoLoader(root,catalog)print(discovered:,loader.discover())print(loaded before activation:,len(loader.loaded))loader.activate(csv-review)print(after activation:,loader.loaded)ruleloader.resource(csv-review,references/columns.md)print(rule:,rule.strip())print(loaded files:,len(loader.loaded))try:loader.resource(csv-review,../outside.md)exceptValueError:print(outside path: rejected)else:raiseAssertionError(outside path must be rejected)保存为skills_loading_demo.py后运行python skills_loading_demo.py输出discovered: [csv-review] loaded before activation: 0 after activation: [csv-review/SKILL.md] rule: 必需列name、amount。amount应为非负数。 loaded files: 2 outside path: rejected本例已实际执行。它展示了目录发现与文件读取的区别发现阶段没有读取操作正文激活后读取SKILL.md再按请求读取列规则。最后的检查拒绝指向技能目录之外的路径。路径检查只覆盖这段教学代码的读取边界没有实现脚本沙箱、并发文件替换防护或完整宿主权限系统。示例也没有核查真实CSV更没有把文件读取数量当作模型效果评分。五、与工具接入和长期记忆如何配合从应用设计上可以把三类材料分开组织工具接口提供执行能力Skill提供某类工作的流程与知识长期记忆提供历史记录或偏好。这是本文的职责划分建议并非所有产品都采用相同模块结构。例如CSV核查技能可以指导Agent使用文件读取工具也可以要求先确认用户关心的列。它无须把所有工具协议写进正文更不应把某一次任务的私密输入固化到通用技能里。维护时可以先记录三项信息说明适用哪些输入依赖哪些环境怎样判断完成。规则改动后用几类代表性任务核对触发范围、缺失输入处理与输出同一目录能够跨产品复用也仍需检查各宿主的工具、脚本和发现方式是否兼容。六、 思维导图Agent Skills目录结构SKILL.md入口参考脚本与模板分层加载先看名称与描述激活后读取操作说明执行边界资源按需读取宿主权限继续生效维护验证清楚的触发范围环境与完成条件七、总结总结要点技能目录让某类工作的说明、参考材料与模板集中维护。SKILL.md承担入口职责较长的细节可以拆进对应资源。分层加载让发现、激活和执行阶段拿到不同深度的信息。任务需要什么再读取什么目录结构也应服务这个顺序。执行与验证边界仍由具体宿主落实。技能说明需要明确输入、环境和完成条件资源读取成功之后还要核对任务产物是否满足要求。下一篇随笔继续关注Agent的知识接入结合官方资料讨论检索结果如何保留来源并支持回查。如果你觉得这篇文章对你有所帮助欢迎点赞、收藏、分享