先别急着纠结要不要在项目里同时放 Skill.md 和 llms.txt先搞清楚一个更基础的问题它们到底在帮谁干活。前阵子我在设计一个“让 AI 帮忙查产品文档”的小助手同事给我提了两个建议一个说“写个 Skill.md 吧这样 Agent 就知道怎么用这个技能了”另一个说“建个 llms.txt 吧这样模型能理解你的站点内容”。我一开始也差点以为这是同一个东西的两种写法后来仔细拆了一遍才发现这两个文件一个管“行动”一个管“认知”服务对象完全是两个方向。如果你也在做 Agent 技能、文档站、知识库或者 AI 应用建议花五分钟把这两个文件的关系理清。选错文件或者摆错位置配置写再认真也不会按预期生效。1. 先搞清楚一个前提它们不是同一层的东西服务对象完全不同很多人把 Skill.md 和 llms.txt 放在一起讨论是因为它们看起来都像是“给 AI 看的文本文件”。但这种归类方式会误导后续设计。它们真正服务的对象不一样工作链路也不一样。1.1 Skill.md 是给 Agent 自己的“操作手册”Skill.md 在常见的 Agent 工程里是一个技能描述文件。它通常放在 Agent 的技能目录下里面描述的是一个技能的名字、什么时候该用、执行步骤是什么、有哪些约束条件。它解决的是“Agent 怎么把一个具体任务做完”的问题。你可以把它理解成岗位说明书。一个 Agent 可能具备多个技能有人负责写代码有人负责做数据分析有人负责查文档。Agent 本身不知道每个技能里有什么逻辑而是在用户请求到来时根据请求内容匹配到某个技能然后按技能文件里的步骤执行。这里的关键是Skill.md 不是给普通读者看的产品介绍而是给 Agent 的执行框架读取的指令单元。它更像是你给员工的一份 SOP而不是贴在店门口的菜单。所以Skill.md 生效的前提是运行 Agent 的框架认识这个文件会扫描技能目录会解析里面的元信息并把它注入到模型上下文中。如果你的项目只是放了一个 Markdown 文件没有任何加载逻辑那它就是一个普通文档不会产生“技能效果”。1.2 llms.txt 是给外界模型看的“站点索引”llms.txt 则完全站在另一个方向。它通常放在网站根目录是一个纯文本文件内容是一份经过挑选的 Markdown 页面清单甚至可以附带简单说明。它存在的意义是让外部 LLM 客户端在访问某个站点时不用从头到尾爬一遍整个网站就能通过这个文件快速了解站点有哪些关键内容、分别放在哪些 URL。你可以把它理解成“图书馆的馆藏目录”。读者进图书馆不需要把每一层楼都翻过去先看目录知道哪些书在哪个房间然后再按需去取。但要注意llms.txt 的阅读对象不一定是你的 Agent。它面向的是任何可能访问你网站的 LLM 客户端。你的官网、文档站、知识库一旦放了这个文件相当于告诉外部 AI“我的内容结构是这样的你按这个索引来读最省力。”1.3 一句话区分一个管“怎么做事”一个管“内容在哪”对比维度Skill.mdllms.txt服务对象Agent 本身和执行框架外部 LLM 客户端、爬虫、AI 工具文件位置Agent 技能目录属于工程代码的一部分网站根目录属于站点公开资源核心内容技能名称、触发条件、执行步骤、约束页面 URL 列表、简要说明解决问题模型不知道技能怎么触发、怎么执行模型不知道站点有哪些内容、内容结构是什么生效时机Agent 加载技能、按需注入上下文时外部客户端访问站点时主动读取典型错误放在网站根目录只做展示放在 Agent 技能目录试图控制行为看到这个对比应该已经明白了它们不是同一个东西的两种写法而是两个不同链路里的协作文件。2. 各自到底解决了什么问题为什么过去不好解决既然它们是两种文件那它们各自对应的痛点也完全不一样。只有理解了“为什么以前做不到”你才知道这个文件的价值边界在哪里。2.1 Skill.md 解决的问题模型知道有技能但不知道什么时候该调用以前想让大模型完成一个固定流程最常见的做法是写系统提示词。比如“当用户问日报时先读取昨天的日志再生成摘要最后发送到指定频道”。这个思路单看没问题但一旦技能多了系统提示词会越来越长多个技能的说明混在一起模型经常出现误触发、漏触发或者执行到一半串场。Skill.md 的做法是把每个技能拆成独立文件。执行框架只会在合适的时机把相关的技能说明加载进来。模型需要看到的信息变少了判断也更准确。但它能不能触发很依赖两个字段技能名称要唯一不能和其他技能冲突。技能描述要写清楚什么时候用、什么时候不用最好包含关键词和边界条件。这是很多人容易忽略的点。例如一个技能描述里只写“生成日报”那用户说“写个今日总结”时模型可能不会触发它。但如果描述写成“当用户要求生成日报、周报、今日总结或工作汇总时使用输出格式固定”触发准确率就会明显提升。Skill.md 更底层的价值是把“一次临时对话里完成的指令”固化成“可以重复加载的执行单元”。它改变的不是单次问答的质量而是让 Agent 在多任务环境下不用把所有逻辑都塞进一个上下文里。2.2 llms.txt 解决的问题模型能抓网页但要理解整个站成本太高在 llms.txt 出现之前LLM 要了解一个网站主要有两条路要么爬取 HTML 网页再用工具把正文提取出来要么先把 sitemap.xml 读一遍再一个个访问页面。问题是 HTML 里噪音太多导航、脚本、样式、广告代码都会混进上下文里既浪费 token又容易干扰回答。llms.txt 的思路很简单站点所有者主动提供一份“适合 LLM 阅读”的目录每行一个 Markdown 页面地址加上一句话说明。这样外部模型就能先读目录再按需访问目标页面。需要说明的是这不代表所有爬虫都会遵守也不代表搜索引擎会因此改变抓取逻辑。它更像是一个“约定”而不是强制标准。所以它的价值取决于你的使用场景如果你的文档站长期会被 AI 工具、RAG 检索、外部 Agent 访问那么提供 llms.txt 有实际收益如果站点几乎只有人类用户浏览那它的优先级可以放低。2.3 两者的共同底层都是给模型减负但减的负担不一样Skill.md 和 llms.txt 的底层逻辑其实一脉相承用结构化的文件替代模型自己摸索。模型不需要自己去猜网站里有什么也不需要每一步都靠提示词现场设计。区别在于Skill.md 减少的是“执行不确定性”它让模型知道怎么做。llms.txt 减少的是“信息检索成本”它让模型知道去哪里找。理解了这一层你就知道为什么不能随便二选一了。因为它们解决的问题不在同一条线上。3. 二选一还是两个都要先看你在做哪一层的事接下来的问题是我到底需要哪个还是两个都放这不能拍脑袋要看你现在建设的是“技能体系”还是“内容体系”。3.1 什么时候只需要 Skill.md如果你正在开发 Agent 技能目标是让模型自动完成某个端到端任务那核心就是 Skill.md。典型场景包括让 Agent 每天定时生成项目周报。让 Agent 根据用户提问调用内部 API 查数据。让 Agent 理解一段 SQL 的生成规则并自动执行。让 Agent 完成“读取原始材料 → 整理 → 输出特定格式”的工作流。这些场景的共同点是任务的关键在于“执行方式”不在于“需要多少外部知识”。你把执行步骤固化在 Skill.md 里对模型来说就已经够用了。但有个前提你使用的 Agent 框架要支持技能加载机制。如果框架本身不认识 Skill.md只是把文件当作普通附件那效果会大打折扣。落地前先确认框架版本和文档不要想当然地认为所有平台都支持同一个字段格式。3.2 什么时候只需要 llms.txt如果你运营的是一个文档站、官网、产品手册或知识库且你希望外部 AI 产品能正确理解你的内容那 llms.txt 是更合适的起点。典型场景有你有一个产品帮助中心希望 AI 助手能基于准确文档回答问题。你维护了一套公开 API 文档希望外部 Agent 在集成时能快速定位到关键页面。你有一个技术博客希望自己的文章能被 LLM 类工具更好地索引和引用。这时你不一定需要写 Skill.md。因为你并不想控制模型“怎么做事”你只想让模型“更容易读到你的内容”。llms.txt 放在网站根目录保持公网可访问保持内容链接有效就已经把该做的事做完了。注意llms.txt 只负责提供索引不负责保证内容一定能被所有模型读取。用它之前先确认自己的页面是静态 Markdown 或清晰 HTML而不是登录后才能访问的动态页面。3.3 什么时候两个都要比较复杂的情况是你既要让 Agent 能执行任务又要让 Agent 在执行任务时使用大量外部文档。举个例子。你打算做一个“产品售后答疑 Agent”用户会问“某某设备怎么重置”。这时候需要 Skill.md 告诉 Agent当用户询问设备操作步骤时先读取产品文档索引再对应回答不要凭记忆编造。需要 llms.txt 告诉 Agent产品手册、FAQ、故障排查分别在哪几个 URL对应什么主题。两个文件的配合关系就变成了Skill.md 提供执行策略llms.txt 提供知识来源。没有 llms.txtAgent 可能不知道该去哪找内容没有 Skill.md即使知道内容在哪也可能不知道该怎么组织回答。场景Skill.md 的作用llms.txt 的作用内部自动化任务定义步骤和触发条件一般不需要公开文档站一般不需要提供内容索引方便外部 AI 读取基于文档的 Agent定义“如何检索、如何回答”提供“检索哪些 URL”混合型工作流调度多个子任务定义上下文加载规则每个子任务对应的知识来源所以如果你的项目里“有明确的动作执行”那就需要 Skill.md如果“有持续更新的对外内容”那就需要 llms.txt。两者不冲突只是在不同的层级各司其职。4. 争议点Skill.md 里以 # 开头的内容是不是不会被执行这个话题在不少开发者群里反复出现“skill.md 里面 # 后面的是不是不执行” 第一次看到这个问题时我先愣了一下因为这不是一个无效提问它背后隐藏着一个常见误区。4.1 这个疑问从哪里来的很多配置文件会把#当作注释符号比如 Python、YAML、Shell 配置文件。开发者一看到 Markdown 文件里的#下意识觉得这是“被注释掉的文字”因此认为它不会进入模型上下文也不会被执行。但 Skill.md 本质上是一个 Markdown 文件在 Markdown 语法里#是标题标记不是注释。# 技能名称表示这是一级标题不会因为这一行以#开头Agent 就不会读取它。更准确地说Skill.md 被加载后文本内容通常会整体进入模型上下文包括标题、段落、列表、代码块。标题里的#起的是语义结构作用帮助模型识别内容层级而不是“跳过”的意思。4.2 如果你真的希望某段内容不被执行该怎么办实际工程里确实会有一些内容你想写进去但不想让它被当作执行指令。比如给维护者看的备注、不生效的旧说明、内部备注等。这时候不要依赖#因为它在 Markdown 里不是注释。更可靠的方法取决于你使用的框架把元信息放到 YAML frontmatter 的合适字段里比如 description、metadata。把只有人看的说明放到单独的维护文档中不要混进技能正文。如果框架支持ignore或disabled字段按框架文档操作。需要让 Agent 不触发某个技能应该修改描述词里的边界条件而不是在正文里加注释。其实“# 后面不执行”这个说法本身就不太准确。对模型来说执行指令是一个语义判断过程不是逐行解析。模型会把整个技能文档当作背景再根据用户请求决定怎么行动。某个段落以什么符号开头不等于它会严格按注释规则被丢弃。4.3 真正要检查的是“有没有被加载”而不是符号当技能不生效时很多人第一反应是格式化、改标题、改符号但这些往往没用。按照经验应该先检查文件路径是否在框架扫描范围内。frontmatter 是否被正确解析字段名是否和框架要求一致。技能描述是否足够具体能不能被用户问题触发。加载日志里有没有报错、有没有成功读入该文件。如果框架压根没有加载这个技能正文里写什么都白搭。技能没生效和#符号之间通常没有因果关系。建议先做最小验证写一个只包含 3 行描述的 Skill.md确认能触发再逐步扩展正文。不要一开始就堆很长的指令否则一旦出错很难判断是哪一段的问题。5. 两者一起落地时怎么设计文件、怎么验证下面落到实操。两个文件不是互相冲突但设计时要有清晰的边界否则很容易写成一个“四不像”文件。5.1 一个最小可运行的 Skill.md 示例这是一个常见结构具体字段名取决于你使用的框架但整体思路是相通的--- name: read_product_docs description: 当用户询问产品功能、操作步骤、故障处理时使用。先读取站点 llms.txt 获取文档索引再抓取对应 Markdown 页面并回答。如果问题与产品无关不要使用本技能。 --- # 执行步骤 1. 读取 https://example.com/llms.txt。 2. 从索引列表中找到与用户问题最匹配的页面 URL。 3. 抓取该 URL 对应的 Markdown 内容。 4. 基于抓取内容回答并说明信息来自哪份文档。 5. 如果索引里没有对应内容明确告诉用户找不到而不是猜测。这个示例里有几个值得注意的地方描述词涵盖了触发场景和排除场景。执行步骤是顺序清晰的。最后一步约束了模型“不要猜测”。它以#开头的“执行步骤”是标题不是注释模型会把它当作任务结构理解。5.2 一个最小可运行的 llms.txt 示例llms.txt 的结构相对简单。它的设计初衷是让模型快速读懂网站有哪些内容代码如下# example.com 面向 LLM 提供的产品文档索引优先推荐 Markdown 页面。 - https://example.com/README.md: 产品简介 - https://example.com/docs/getting-started.md: 新手入门指南 - https://example.com/docs/api.md: API 参考 - https://example.com/docs/faq.md: 常见问题 - https://example.com/docs/troubleshooting.md: 故障排查要注意几点文件要放在公网可以访问的根目录比如https://example.com/llms.txt。链接尽量指向稳定、可直接读的 Markdown 页面而不是需要 JS 渲染的页面。每行 URL 后面加一个冒号和一句话说明帮助模型判断是否需要点开。不需要把所有页面都列进去优先列用户最常需要、内容质量最高的页面。5.3 验证方法写完文件之后不能用“打开看一眼”来判断有效。技术上的验证可以这样做curl -I https://example.com/llms.txt curl https://example.com/llms.txt第一行看响应头确认文件存在、返回正常状态码、没有被重定向到登录页第二行看正文内容确认编码正常、链接能访问。还可以抽查文件里的 URL确保都能返回 200。Skill.md 的验证则要看 Agent 的加载日志。通常在对话中输入一个可以触发技能的问题然后观察日志里是否出现了该技能的加载记录。如果没有再回到第 4 节提到的排查顺序。5.4 排查链路文件不生效时按什么顺序查两个文件都可能遇到不生效的情况。不要凭感觉乱试按这个顺序来观察现象。技能没有触发还是触发后回答错误llms.txt 完全没被读取还是读取后链接打不开。检查输入侧。Skill.md 的描述是否覆盖用户问题llms.txt 的 URL 是否写错。检查格式侧。frontmatter 是否缺少字段文件编码是不是 UTF-8是否存在多余字符。检查加载侧。是否在框架扫描范围内有没有缓存策略路径有没有大小写问题。检查模型边界。当前使用的基础模型是否支持这种技能机制llms.txt 是否被当前客户端支持。检查工具版本。很多这类能力还处于快速迭代中文档和实际行为可能存在差异落地前先确认依赖版本。这套链路适用于大多数“配置文件不生效”的问题。核心是先确定问题出在哪一层再去动那一层的配置。6. 长期建议先跑通最小闭环再考虑规模最后聊一点长期使用的经验。这两个文件看起来都很简单真正放到生产环境里问题往往出在维护而不是创建。6.1 不同阶段应该用什么配置如果你只是学习和验证阶段默认配置通常够用。先让一个 Skill.md 能触发再让一个 llms.txt 能访问不用追求完整。如果进入小规模使用阶段就要考虑日志。每次技能触发是否成功、llms.txt 有没有更新、缓存策略是什么这些都要透明可见。否则出了问题很难定位。如果要放进生产环境几个容易被忽视的工程点llms.txt 如果放在 CDN 后面更新策略要明确不能改完文件后一直命中旧缓存。Skill.md 最好纳入版本管理跟着代码一起评审、回归。技能描述不要越写越长触发条件要保持清晰否则多个技能会互相干扰。如果文档站经常改动目录需要建立 llms.txt 的自动更新流程而不是手工维护。6.2 最容易被忽略的三个坑第一把两个文件混淆在一个目录里。有人会在网站根目录放一个 Skill.md又在 Agent 技能目录放一个 llms.txt以为这样能同时生效。实际上 Skill.md 只有放在 Agent 能扫描到的地方才有意义llms.txt 也只有放在公网根目录才符合规范。放错位置两个都不生效。第二描述词写得太泛。比如“用户问问题时用”这种描述基本等于每次都会触发会让技能变成一个巨大的常驻指令反而影响模型判断。描述词越具体触发越稳定。第三把 llms.txt 当成 sitemap 的替代品。sitemap 给传统搜索引擎爬虫看llms.txt 给 LLM 客户端看两者并不冲突。如果你有完整的站点结构完全可以同时维护。但也不要指望所有搜索引擎因为 llms.txt 就提升排名它的定位不是 SEO 工具。6.3 回到起点先回答一个最根本的问题每次要做配置之前先问自己一句我到底是想让模型更会做事还是更懂内容想让模型会做更多任务核心是 Skill.md。想让外部 AI 更懂我的内容核心是 llms.txt。想让 Agent 基于内容自动完成复杂任务两个都要但要让它们各管一段。我的建议是从小样本开始。先写一个 20 行的 Skill.md再写一个只有 5 个链接的 llms.txt跑通一次“从文档索引到技能执行”的完整链路确认每一步都能看见日志。之后再逐步加技能、加文档、加约束。这类文件的真正价值从来不是让你一次性写出一个完美的配置而是让 AI 应用的复杂度变成可维护、可追踪、可迭代的结构化资产。明白这一点就不会再纠结到底该选哪个了。