很多开发者在搭建 AI Agent 项目时都会遇到同一个困惑项目仓库里到底应该放 SKILL.md还是放 llms.txt有同学把两个文件都建好塞进代码库结果模型读完之后既没有变得更专业也没有按预期去查外部资料。问题到底出在哪里先说结论SKILL.md 和 llms.txt 不是二选一的配置文件它们解决的是两个完全不同的工程问题。SKILL.md 描述的是“模型拿到某个任务时应该调用什么技能、按什么流程执行”llms.txt 描述的是“模型需要外部信息时去哪个网址找内容”。一个是给 Agent 定流程一个是给 Agent 做导航。如果你正在做 Agent 应用、RAG 知识库系统或者维护一个希望被 AI 正确理解的网站这篇文章值得读完。我会从两个文件的来历、结构、解析规则讲起重点回答一个最近很多人都在问的问题SKILL.md 里#后面的内容到底是不是不执行最后用一个完整示例演示它们如何配合使用并且给出排查思路和工程建议。1. 为什么 Agent 项目需要“文件协议”而不是只靠提示词在 AI 项目里我们经常看到两类文件一类是给人类看的 README、需求文档另一类是给模型看的配置、描述、指令文件。SKILL.md 和 llms.txt 都属于后者但它们把“给模型看的信息”做成了标准化文件目的是让 Agent 在运行时能够自动发现并理解这些信息。想象一下这样的场景你开发了一个客服 Agent它需要处理退款、改地址、查订单三类任务。如果所有指令都写在系统提示词里每次修改都要改代码、发版本如果后续加入新的任务类型提示词会越来越长最终超出上下文窗口或者互相干扰。更麻烦的是Agent 不一定会在每次调用时都读取全部提示词而是根据用户意图动态决定使用哪部分能力。这个时候通过独立的技能描述文件来组织能力就比堆提示词更清晰。llms.txt 的场景则更偏向信息检索。你的网站可能有几十个页面AI 搜索引擎或 Agent 抓取工具如果每个页面都爬一遍成本高而且容易抓到无关内容。llms.txt 就像给模型准备了一份“网站地图”把最重要的页面链接和简介放在根目录让 AI 用最少的请求找到最有价值的内容。所以这两个文件虽然都叫“给模型看的文件”但定位完全不同SKILL.md 面向“模型如何执行任务”llms.txt 面向“模型去哪里找数据”。理解这个区别后续才不会用错。2. SKILL.md 到底是什么给模型看的“技能说明书”2.1 它解决的核心问题SKILL.md 常见的载体是一个技能目录里的核心描述文件。在一个 Agent 项目中每个技能Skill通常对应一个目录目录里会有一个描述该技能的SKILL.md文件若干辅助资源比如提示词模板、代码脚本、参考文档、校验规则。这个文件的核心价值是让模型在运行时能够“发现”一个技能并且知道“什么情况下该用它、用了之后该怎么做”。如果没有 SKILL.mdAgent 即使看到了技能目录也只知道里面有一堆文件却不知道这些文件是干什么用的更不知道应该在哪个场景调用。2.2 典型结构解析一个标准的 SKILL.md 通常包含两部分YAML frontmatter元信息区Markdown 正文指令区。frontmatter 用两行---包裹里面是键值对形式的元数据常见字段包括技能名称、描述、适用场景等。正文部分则是具体的执行指引模型会把它作为上下文来理解任务的执行方式。下面是一个最小示例--- name: order_refund description: 当用户申请退款时使用此技能。包含退款条件校验、退款金额计算和退款结果通知流程。 --- # 退款处理技能 你是一个订单退款处理专家。当用户提出退款请求时按以下步骤执行 1. 获取订单号。 2. 校验订单状态是否为“已支付”。 3. 如果订单已发货提示用户先确认收货再退款。 4. 计算可退金额排除优惠券分摊部分。 5. 调用退款接口并将退款结果返回给用户。 ## 注意事项 - 不要直接向用户承诺到账时间。 - 如果退款失败必须把原始错误信息记录到日志。从结构上就能看出这个文件解决的是“模型在这个任务里该按什么流程走”的问题。而模型是否读取这个文件、何时读取通常由 Agent 框架根据用户意图与description字段的匹配程度来决定。需要提醒的是不同框架对 SKILL.md 的字段名、读取顺序、目录扫描方式可能有差异。本文强调通用思路实际接入时请以你所用框架的官方文档为准。2.3 没有 SKILL.md 时会怎样如果没有 SKILL.md你仍然可以把技能逻辑写进系统提示词但会面临几个问题技能多了之后提示词互相覆盖模型容易混乱不同技能的更新频率不一样改一个技能要动整个提示词文件新增技能需要修改代码无法做到“加一个目录就生效”。所以SKILL.md 的真正价值在于把“能力组织”从代码中解耦出来让技能可以独立开发、独立测试、独立发布。这对 AI Agent 工程化来说是很大的一步。3. Llms.txt 到底是什么网站的“模型版导航”3.1 设计初衷llms.txt 的设计思路与 robots.txt 有点像但目的完全不同。robots.txt 告诉搜索引擎“哪些路径不能抓”llms.txt 是反过来告诉大语言模型“哪些页面最值得读、每个页面大概讲什么”。它希望解决的是 AI 抓取网站时信息密度太低、路径太深、标题语义不清晰的问题。如果你维护一个文档站、博客、企业官网或工具站并且希望自己的内容能被 AI 搜索、AI 问答类产品准确引用那么 llms.txt 是一个不错的标准化方案。它不是让模型“学习”网站内容而是为模型提供一条低成本的入口路径。3.2 标准结构与示例llms.txt 文件通常放在网站根目录语法非常接近 Markdown结构包括网站标题、网站简介、区块标题和链接列表。下面是一个简化示例# Acme Documents Acme 平台的官方文档站提供 API 参考、快速入门、最佳实践等内容。 ## API Reference - [Authentication](https://docs.acme.com/api/auth): 介绍 API 密钥申请、鉴权方式和错误码。 - [Orders API](https://docs.acme.com/api/orders): 创建订单、查询订单、取消订单的接口说明。 - [Refunds API](https://docs.acme.com/api/refunds): 退款申请、退款状态查询的接口说明。 ## Guides - [Quick Start](https://docs.acme.com/guides/quick-start): 5 分钟跑通平台核心流程。 - [Webhook Guide](https://docs.acme.com/guides/webhook): 如何订阅和接收平台事件通知。这里的关键设计是每一条链接后面都尽量跟一句话简介让模型在抓取之前就能判断这个页面是否值得打开。相比直接丢给模型一个完整的 sitemap.xmlllms.txt 的信息更“人性化”也更适合被作为上下文片段传给模型。3.3 llms.txt 和 sitemap.xml 的差别有同学会问网站已经有 sitemap.xml 了为什么还要 llms.txtsitemap.xml 是给搜索引擎爬虫用的它的粒度是全站 URL包含大量无关页面llms.txt 是给语言模型和 Agent 工具用的它强调“重点内容导航”粒度更小、语义更明确。可以这样理解sitemap.xml 是网站的完整目录册llms.txt 是前台递给 AI 的“精选菜单”。两者可以共存并不是替代关系。4. SKILL.md 与 Llms.txt 的核心对比4.1 一页纸对比表对比维度SKILL.mdLlms.txt主要作用定义 Agent 执行任务的技能与流程为 LLM/Agent 提供网站内容导航解决什么问题模型“怎么做”模型“去哪找”典型存放位置技能目录内如skills/xxx/SKILL.md网站根目录如https://example.com/llms.txt使用方Agent 运行时、任务编排器AI 搜索引擎、爬虫、Agent 知识获取模块文件格式Markdown YAML frontmatter类 Markdown 的纯文本是否进入模型上下文技能被选中时可能作为上下文注入通常作为导航索引不会被整体注入更新频率随技能迭代更新随网站内容结构调整更新核心风险Prompt 注入、指令覆盖导航信息过期、内容简介误导4.2 一句话判断标准如果问题是“帮我按流程处理退款”你需要 SKILL.md如果问题是“这个文档站有哪些值得读的 API 页面”你需要 llms.txt。如果你正在做一个垂直领域的 Agent既需要让模型掌握内部业务规则又需要让它实时查询外部资料或文档那么非常常见的情况是两者都需要。SKILL.md 负责定义“业务处理能力”llms.txt 负责告诉模型“外部信息从哪里来”。上一节里的客服 Agent 就是一个典型退款流程用 SKILL.md 定义退货政策和运费标准存放在外部文档站通过 llms.txt 提供入口Agent 再用检索工具去取。5. 关键误区SKILL.md 里 # 后面的内容是不是不执行最近热搜里有人问“skill.md 里面 # 后面的是不是不执行”这个问题问得很有水平因为它背后藏着一个真实的误解很多人把 Markdown 的#当成了代码注释符。5.1 要先分清两种上下文SKILL.md 虽然是 Markdown 文件但它内部其实有两种不同的“语法区域”文件开头的 YAML frontmatter 区域文件正文的 Markdown 区域。这两个区域对#的处理方式完全不同回答“# 后面是不是不执行”之前必须先搞清楚自己说的是哪个区域。5.2 frontmatter 里的 #确实是 YAML 注释在 YAML 中#开头表示注释解析器不会把它当作有效配置。比如--- name: order_refund # 下面这行是备注不会被解析 # 这个技能只适用于已支付订单 description: 处理用户退款申请 ---在这种上下文里#后面的内容确实“不生效”因为它们只是给维护者看的注释。如果你在 frontmatter 里使用#注释来补充说明模型读取到字段时不会把这些注释当成配置项或指令。5.3 Markdown 正文里的 #是标题不是注释但如果你在 Markdown 正文里写# 退款处理技能这里的#表示一级标题解析后会变成带语义的标题结构。模型读取这段内容时不会把“退款处理技能”当成无效内容忽略掉反而会把它作为文档结构信息来理解。也就是说正文中的#会被解析为标题语义它后面的文字会进入模型上下文并不是“不执行”。更准确的说法是Markdown 标题没有“执行不执行”的概念只有“是否被解析为标题结构”的概念。真正会被忽略的只有 YAML frontmatter 里的注释或者某些框架约定好不读取的区块。5.4 真正容易踩坑的地方如果你想让某段话“不给模型看”用#注释是做不到的。因为 SKILL.md 的本质就是给模型读的文档Markdown 标题也会被当作内容输入模型。正确的做法有三种把不想暴露的备注内容放在 frontmatter 之外单独维护利用框架提供的忽略机制比如.gitignore、特定目录过滤把敏感信息放在外部环境变量或配置中心不要写进 SKILL.md。所以以后不要再问“# 后面是不是不执行”了正确的问题是“这段#是在 YAML 区域还是 Markdown 区域这个框架会不会把 Markdown 标题作为上下文传给模型”5.5 不同解析器的差异不同 Agent 框架对 SKILL.md 的解析不一定完全一致。有的框架会把完整文件内容作为文本拼进 prompt有的会先解析 frontmatter 再截取正文还有的会提取所有标题和列表生成一个摘要。这意味着同一份 SKILL.md 在不同框架中的“实际生效内容”可能是不同的。设计文档时最好把最关键、最不希望丢失的指令写在正文靠前的位置并且不要让关键信息只存在于注释或标题后面。6. 完整项目示例一个 Agent 项目里同时使用两个文件为了让你看清两者如何协作下面用一个最小项目演示。假设我们要做一个“退货助手 Agent”用户提交退货申请Agent 判断是否满足退货政策并返回处理结果。6.1 项目目录结构returns-agent/ ├── skills/ │ └── return_request/ │ ├── SKILL.md │ └── helper.py ├── agent.py ├── requirements.txt └── external/ └── llms.txt项目里skills/return_request/SKILL.md是技能定义external/llms.txt是对接外部退货政策文档库的导航索引agent.py是一个最小调用示例。6.2 SKILL.md 文件内容--- name: return_request description: 当用户申请退货、退款、取消订单时使用该技能。 --- # 退货处理技能 你需要根据用户提供的订单号完成以下流程 1. 调用 helper.py 获取订单状态。 2. 如果订单状态不是“已发货”直接提示用户可以申请退货。 3. 如果订单已发货引导用户先签收再申请退货。 4. 从退货政策页面读取退货期限判断当前日期是否在有效期内。 5. 在有效期内引导用户填写退货原因 不在有效期内返回拒绝原因并提供售后联系方式。 ## 政策查询说明 退货政策页面地址和关键页面导航从外部 llms.txt 获取。 查询时优先读取“退货政策”区块对应的链接。6.3 helper.py 示例文件路径returns-agent/skills/return_request/helper.py def get_order_status(order_id: str) - str: # 这里只是演示逻辑真实项目应替换为订单系统 API fake_orders { A1001: paid, A1002: shipped, } return fake_orders.get(order_id, not_found)6.4 外部政策文档的 llms.txt# Returns Policy Docs 退货政策公共文档供 Agent 查询退货规则使用。 ## Return Policy - [Return Window](https://example.com/docs/return-window): 退货期限为签收后 7 天内。 - [Prohibited Items](https://example.com/docs/prohibited): 定制类、生鲜类商品不支持退货。 - [Refund Process](https://example.com/docs/refund): 退款将在审核通过后 3 个工作日内原路退回。这里的设计思路是SKILL.md 告诉模型“退货流程怎么走”llms.txt 告诉模型“退货政策在哪里看”。模型在执行第 4 步时会先从 llms.txt 里定位退货政策链接再去对应页面读取具体规则。6.5 最小调度逻辑下面是一段极简的调度逻辑演示模型如何根据用户问题决定是否读取技能文件路径returns-agent/agent.py from skills.return_request.helper import get_order_status def handle_user_request(message: str): if 退货 in message or 退款 in message: # 实际项目中这一步通常由 LLM 根据 description 自动选择技能 # 这里为了演示直接手动路由到退货技能 order_id extract_order_id(message) status get_order_status(order_id) print(f订单状态: {status}) print(请参考 SKILL.md 中的流程继续处理) print(退货政策请从 external/llms.txt 中的 Return Policy 区块获取) else: print(暂不支持该请求) def extract_order_id(message: str) - str: # 演示用提取逻辑真实场景建议用正则或 LLM 抽取 return A1001 if __name__ __main__: handle_user_request(我要退货 A1001)运行这段代码会输出订单状态: paid 请参考 SKILL.md 中的流程继续处理 退货政策请从 external/llms.txt 中的 Return Policy 区块获取上面的示例中Agent 调度逻辑和技能定义被分开了SKILL.md 描述流程llms.txt 描述外部信息来源。真实项目中还需要用 Agent 框架把这两个文件内容注入模型上下文并让模型自主完成链接抓取和决策。7. 常见问题与排查思路7.1 技能没有被触发问题现象可能原因排查方式解决方案用户提问后模型没有调用 SKILL.mdfrontmatter 中的 description 与用户意图匹配度太低打印技能描述检查语义相关性重写 description加入更多触发关键词和同义词模型读了技能但执行流程不完整正文结构混乱步骤不清晰查看注入上下文是否丢失了后半部分把步骤写成有序列表并放在正文靠前位置模型完全忽略技能文件框架没有把技能目录加入扫描路径检查框架配置和目录扫描规则确认技能目录命名和存放位置符合框架规范7.2 llms.txt 引用失效问题现象可能原因排查方式解决方案Agent 抓取 llms.txt 链接 404页面路径变更但 llms.txt 未同步更新用脚本批量检查链接状态码建立链接巡检任务或结合 CI 校验模型读取了错误页面llms.txt 中的简介与实际页面内容不一致抽查页面标题和简介人工审核简介避免模糊描述llms.txt 太大浪费 token列出过多不相关链接统计模型实际打开过的链接只保留高价值链接按主题分区7.3 解析相关问题现象可能原因排查方式解决方案正文# 标题没有被模型理解框架只提取 frontmatter正文被截断或纯文本化查看框架的解析源码或文档调整文件格式或把关键指令写进 frontmatter 的字段中frontmatter 中的注释影响配置格式错误导致 YAML 解析失败使用 YAML 校验工具检查修复缩进删除多余注释或确保注释符合 YAML 规范SKILL.md 中写了大量环境变量格式不统一检查变量是否被正确替换使用统一的配置中心或环境变量命名规范8. 工程实践与安全建议8.1 SKILL.md 的维护策略技能描述文件会随着业务迭代频繁变化建议做到以下几点一个技能一个目录目录内只放与该技能强相关的文件SKILL.md 的 description 字段要定期复盘观察模型触发准确率技能的指令尽量做到“无状态”不要依赖特定会话历史线上技能和测试技能用不同版本号管理降低改动风险。8.2 llms.txt 的内容治理如果你维护的是企业级文档站llms.txt 不能只“建了不管”。建议建立以下机制链接定期检查防止死链简介由文档负责人审核避免表述歧义涉及敏感页面时不在 llms.txt 中公开内部地址发布流程中加入 llms.txt 更新步骤和文档改版同步。8.3 安全边界是最重要的这两个文件都会把内容注入到模型上下文中因此都面临 Prompt 注入风险。攻击者如果能在 SKILL.md 或 llms.txt 里植入恶意指令可能会导致 Agent 忽略用户意图、泄露保密信息或执行错误操作。这里必须强调几个底线不把密钥、内部地址、客户隐私写进 SKILL.md 或 llms.txt不直接信任从外部链接抓取的文本先做格式校验和脱敏对 Agent 可能执行的敏感操作如下单、退款、删除资源必须增加人工确认步骤在生产环境中技能文件和外部导航文件应有版本审查机制不能随意改动后直接上线。8.4 先跑通最小闭环再扩展无论做 Agent 技能还是外部文档导航都建议先用最小示例验证手动触发一个技能确认模型能读到 SKILL.md 关键步骤手动抓取一个 llms.txt 链接确认返回内容和预期一致再逐步扩大到多个技能、多个文档区块。9. 总结与后续学习方向SKILL.md 和 llms.txt 的共同点是它们都试图用标准化的文件让大模型更高效地工作。不同点在于SKILL.md 把“任务执行能力”从提示词中解耦出来llms.txt 把“外部知识入口”从爬虫抓取中标准化。两者并不冲突在复杂 Agent 项目中经常同时存在。你真正需要记住的是#在 SKILL.md 的 YAML frontmatter 里是注释在 Markdown 正文里是标题。想用注释隐藏内容是不可靠的做法想让技能生效关键是写好 description 和正文步骤并确保框架按预期解析和注入。下一步建议你用一个真实的 Agent 项目做练习先为一种业务编写 SKILL.md再把它的外部政策文档整理成 llms.txt跑通一次完整调用链路。之后可以继续深入研究技能路由策略、提示词注入防护、文档链接巡检工具以及更细粒度的 Agent 上下文管理。