llms.txt 与 SKILL.md 的区别：AI 时代网站与 Agent 的配置文件解析

之前在调试 AI 智能体项目时看到同事同时提交了两类配置文件一个放在网站根目录叫llms.txt一个放在 Agent 技能目录叫SKILL.md。当时第一反应是这俩是不是一回事后来发现完全不是。很多朋友在评论区也问同一个问题——skill.md里面#后面的内容是不是不执行这句话在 Shell 和 Python 里是对的但到了 Markdown 技能文件里结论完全相反。这篇文章不绕弯子直接围绕两个文件展开llms.txt是做什么的SKILL.md是做什么的两者到底能不能互相替代以及为什么越来越多项目开始同时使用它们。文末还会专门解释#后面内容不执行这个热门疑问并给出一份可直接参考的技能文件模板。1. 为什么突然同时关注 Skill.md 与 Llms.txt先说一个最简单的观察大模型应用正在从“对话”走向“工程化”。过去使用大模型是打开一个聊天窗口把问题丢进去。现在不一样了无论你是做 SEO、做知识库还是做 AI 编程助手都需要给大模型喂一套“提前整理好的上下文”。这些上下文文件越来越多llms.txt和Skill.md是其中比较有代表性的两个。它们解决的问题不同llms.txt解决的是“大模型怎么读懂一个网站”的问题。网站内容通常被 JS、广告、导航栏包裹大模型直接抓取 HTML 时噪声很大。llms.txt给出一份干净的 Markdown 链接清单相当于给大模型准备了一张“信息地图”。Skill.md解决的是“AI 智能体怎么学会一个技能”的问题。当一个 Agent 需要执行代码审查、生成接口文档、处理 Excel 数据时它可以读取一个名为SKILL.md的文件文件中包含该技能的说明、步骤和示例Agent 按照这些指令完成特定任务。一个是“广度入口”一个是“深度能力”。现在很多技术团队在同时做两件事对外把网站内容用llms.txt暴露给 AI 搜索引擎对内把团队的开发规范、代码生成模板整理成SKILL.md给 AI 编程助手使用。这就是为什么这两个本来不相关的文件会频繁出现在同一个技术讨论里。2. 先搞清楚最热门的疑问skill.md 里面 # 后面的内容到底会不会执行这个疑问在很多社区和热搜里都出现了代表性表述是skill.md 里面的 # 后面的内容是不是不执行先说结论在 Markdown 文件中#是标题标记后面的内容是给 AI 阅读的指令不是注释。AI 会读取并理解#后面的文字但它不会像执行 Shell 命令那样“执行”它们。2.1 “# 不执行”的说法从哪来这个说法大概率来自编程经验。在 Python 中#表示注释#后面的内容不会被执行print(hello) # 这里是注释不会执行在 Shell 脚本中#同样表示注释echo hello # 这里是注释不会执行但在 Markdown 中#是标题语法。下面这段文字如果放在SKILL.md中AI 会把它理解为“生成教育插图”的技能标题并且会继续阅读下面的内容# 生成教育插图 当用户要求解释某个抽象概念时先生成一幅流程图再生成文字说明。这里的#并不会让后面那句话失效。AI 读取这段内容后会遵循标题下的指令。2.2 Markdown 的 # 是标题不是注释要理解这个问题需要区分三种不同场景场景#的含义后续内容是否被处理Python / Shell注释不执行Markdown一级标题正常被解析和阅读YAML Frontmatter注释部分工具会忽略在SKILL.md这类文件中AI 读取的是整个 Markdown 文本。标题的作用是让 AI 快速理解结构比如# 概述、# 操作步骤、# 示例。AI 不会因为看到#就跳过后面的内容。2.3 真正的“不执行”场景如果你发现SKILL.md中某些指令没有被 AI 遵循通常不是因为#而是下面几种原因指令被放在了 YAML Frontmatter 中的description字段里。很多 Agent 框架只读取description来决定“什么时候用这个技能”不一定会把description中的详细步骤作为长期指令。指令被包在 HTML 注释!-- --中。Markdown 解析器通常会忽略 HTML 注释AI 可能看不到。指令写得模糊没有明确动作。比如只写“注意质量”AI 不知道具体要做什么。指令放在了一个 Agent 不会加载的独立文件中而SKILL.md里没有引用它。所以回到热搜问题本身#后面的内容不是不执行而是“不执行”这个说法用错了语境。Markdown 中的#是排版语法AI 会读取标题和标题下的正文并把它们当作行为指令。3. Llms.txt 是什么写给大模型的站点地图如果说robots.txt是给搜索引擎爬虫看的路标那么llms.txt就是给大模型看的“内容精选清单”。3.1 出现背景2024 年Jeremy Howardfast.ai 创始人提出llms.txt标准。核心痛点很明显大模型训练或知识增强时通常需要抓取网站内容。但一个网站首页的 HTML 可能包含几十 KB 导航、广告、组件代码真正有用的正文只有一小段。如果让大模型直接抓取效率低、成本高、效果差。llms.txt就是一个放在网站根目录的 Markdown 文件它用简洁的链接列表告诉大模型哪些页面值得阅读。文件名借鉴了robots.txt的命名方式llms.txt “给 LLM 看的 txt 文件”。3.2 标准结构官方建议的结构非常轻量主要是 Markdown 格式# 网站名称 一句话描述这个网站以及该文件适合哪些大模型场景。 ## 可选章节 - [页面标题](https://example.com/page1) - [页面标题](https://example.com/page2)其中#后是网站名称。后是简短说明。链接使用 Markdown 链接格式-开头表示列表项。章节标题使用##。这个格式的好处是大模型不需要解析复杂的 HTML直接读取 Markdown 就能获得页面清单。3.3 一个真实可用的实例下面是一个技术博客的llms.txt示例# DevNotes 技术博客 DevNotes 覆盖 Java、Python、数据库、AI 应用等技术教程内容适合开发者和运维阅读。 ## 最新教程 - [Spring Security 实战教程](https://example.com/spring-security-guide) - [Python 异常处理最佳实践](https://example.com/python-exception-handling) ## 项目实战 - [基于 Spring Boot 的在线考试系统](https://example.com/online-exam-system) - [基于 Flask 的自动化报表工具](https://example.com/flask-report-tool) ## 关于本博客 - [关于我们](https://example.com/about)这个文件放在网站根目录后当 AI 搜索引擎或大模型需要了解这个网站时可以直接抓取https://example.com/llms.txt快速获得一份页面索引。3.4 Llms.txt 对 SEO 与 AI 检索的影响llms.txt目前还不是搜索引擎官方排名因素但它的作用已经很明确帮助以 Perplexity、Bing AI 等为代表的新一代 AI 搜索更快理解站点结构。降低网站内容被大模型抓取时的噪声。为 LLM 提供更高质量的链接输入变相提升内容被引用的概率。如果你的网站是技术博客、API 文档站、产品手册站强烈建议加上llms.txt。成本几乎为零但能提升对 AI 系统的友好度。4. Skill.md 是什么AI Agent 的技能说明书与llms.txt面向网站不同SKILL.md面向的是 AI Agent智能体。它描述的是一个 Agent 可以执行的“技能”。4.1 技能文件体系在 Claude Code、Cline 等 AI 编程工具以及很多 Agent 框架中技能Skill通常以目录形式组织skills/ excel-processor/ SKILL.md scripts/ process_excel.pySKILL.md是技能的入口文件它告诉 Agent 这个技能什么时候用、怎么用。其他文件脚本、模板、示例作为附件资源。4.2 SKILL.md 的 Frontmatter 与正文SKILL.md使用 Markdown 格式通常包含两部分YAML Frontmatter元信息包括name和description。Markdown 正文具体指令、示例、注意事项。YAML Frontmatter 是用---包裹的--- name: 代码审查 description: 当用户要求检查代码质量、发现潜在 Bug 或安全风险时使用。 ---name是技能名称description是触发条件。Agent 会先读取description判断当前用户请求是否匹配这个技能。如果匹配再加载正文内容。4.3 一个完整的 Skill.md 示例下面是一个“生成 API 接口文档”技能的示例--- name: 生成 API 接口文档 description: 当用户需要根据 Controller 或路由代码生成接口文档时使用。适用于 Spring Boot、Flask、Express 等项目。 --- # 生成 API 接口文档 ## 1. 收集信息 - 找到所有 Controller 或路由文件。 - 提取 HTTP 方法、路径、请求参数、返回类型。 ## 2. 生成文档结构 使用以下格式输出每个接口 - 接口名称 - 请求方式 - 请求路径 - 请求参数 - 返回示例 ## 3. 输出规范 - 使用中文描述接口用途。 - 参数表格包含参数名、类型、必填、说明。 - 返回示例使用 JSON 格式。 ## 示例 接口路径/api/user/{id} 请求方式GET 接口说明根据用户 ID 查询用户信息 返回示例 json { code: 0, data: { id: 1, name: 张三 }, message: success }注意文档中不要暴露真实数据库连接信息只描述业务字段。注意上面代码块嵌套的问题在真实 SKILL.md 中JSON 示例代码块可以正常嵌套。这里的重点是正文中的 # 标题、列表、示例代码AI 都会读取只要指令明确AI 就会遵循。 ### 4.4 AI Agent 如何调用 Skill.md AI Agent 调用技能的过程通常是 1. 用户提出请求例如“帮我把这个 Controller 转成接口文档”。 2. Agent 读取技能目录下所有 SKILL.md 的 Frontmatter匹配 description。 3. 匹配成功后Agent 加载对应 SKILL.md 正文。 4. Agent 按照正文中 #、## 划分的步骤逐步执行。 所以在 SKILL.md 中合理使用 # 标题不仅不会导致内容“不执行”反而能够帮助 Agent 更好地理解任务的分步结构。 ## 5. Skill.md 与 Llms.txt 的核心区别 把两者放在一起对比可以看得更清楚。 | 维度 | Llms.txt | Skill.md | | --- | --- | --- | | 核心作用 | 向大模型/搜索引擎提供网站内容清单 | 向 AI Agent 提供技能步骤和指令 | | 主要面向 | 网站站长、SEO、内容团队 | 开发者、AI Agent 配置者 | | 存放位置 | 网站根目录如 https://example.com/llms.txt | 项目技能目录或 Agent 技能目录 | | 文件格式 | Markdown以链接列表为主 | Markdown含 YAML Frontmatter 和指令正文 | | 使用方 | 大模型、AI 搜索引擎、爬虫 | AI Agent、编程助手 | | 变更频率 | 网站内容更新时同步更新 | 技能步骤或规范调整时更新 | | 是否可独立存在 | 可以网站可单独提供 | 可以Agent 可只加载技能 | 一句话区分 - llms.txt 回答“这个网站有哪些内容”。 - SKILL.md 回答“这件事该怎么做”。 ## 6. 什么时候只要一个什么时候需要两者 很多读者会问我到底应该部署哪个 ### 6.1 只放 Llms.txt 的网站 如果你运营的是 - 技术博客 - 产品文档站 - 公司官网 - 在线知识库 那么优先配置 llms.txt。它能让 AI 搜索更快收录你的内容也能降低内容被抓取时的解析成本。这类场景不太需要 SKILL.md因为网站本身不涉及 Agent 自动化任务。 ### 6.2 只用 Skill.md 的项目 如果你正在做 - 基于 Claude Code 的 AI 编程助手 - 企业内部 AI Agent - 自动化代码审查工具 - 文档生成机器人 那么 SKILL.md 是核心。你需要把团队的编码规范、接口文档规范、命令操作流程写成技能文件让 Agent 读取并执行。 ### 6.3 推荐双文件组合的场景 某些场景下两个文件同时使用效果更好 - 你的网站同时提供 API 文档并且 Agent 需要调用文档。此时 llms.txt 引导大模型找到文档页面SKILL.md 告诉 Agent 如何解析并调用接口。 - 你的团队维护一个内部技术博客同时让 AI 助手写博客。llms.txt 可以让 AI 了解博客已有内容SKILL.md 可以让 AI 按照团队风格生成新文章。 - 你正在开发一个 AI 搜索应用既需要抓取站点清单又需要对抓取结果做清洗和总结。前者用 llms.txt后者写成 SKILL.md。 简单来说**网站内容暴露给大模型用 llms.txtAgent 执行任务用 SKILL.md。两者解决不同问题可以同时存在。** ## 7. 面向开发者的实战建议 以下是基于实际项目经验整理的编写建议可以直接参考。 ### 7.1 如何从零开始编写 Llms.txt 第一步列出网站最重要的 10 到 20 个页面优先放教程、文档、核心产品页。 第二步按照下面的模板填写 markdown # 网站名称 网站简短介绍包含核心受众和主要内容方向。 ## 核心文档 - [文档标题](https://example.com/docs/page1) - [文档标题](https://example.com/docs/page2) ## 最新文章 - [文章标题](https://example.com/blog/article1)第三步放到网站根目录。第四步用curl验证curl https://example.com/llms.txt建议定期更新内容变化后就刷新一次。7.2 如何从零开始编写 Skill.md第一步明确技能边界。一个SKILL.md只描述一个技能不要把“生成文档代码审查数据库操作”混在一起。第二步编写 Frontmatter--- name: 技能名称 description: 在什么场景下使用包含触发关键词和适用项目类型。 ---第三步编写正文。正文建议包含#技能整体目标## 触发条件## 操作步骤## 输出格式## 示例第四步将技能目录放入 Agent 可加载的位置。Claude Code 通常读取~/.claude/skills/或项目.claude/skills/具体根据工具文档确认。第五步实测验证。用一条典型用户请求触发技能观察输出是否满足预期。7.3 写技能文件时的自查清单是否只包含一个技能如果不是拆分成多个目录。description是否能准确描述触发场景步骤是否使用明确动词例如“提取”“生成”“校验”“替换”是否给出了输出格式示例是否包含不应执行的操作限制敏感信息是否写入其他配置而不是硬编码在SKILL.md中8. 常见问题速查表问题原因解决思路AI 没有遵循 SKILL.md 里的指令指令放在 description 中或正文描述不具体将指令写入正文步骤使用动词开头skill.md 中#后面的内容没生效常见误解Markdown 的#是标题不是注释确认指令在标题下正文中并用示例说明LLM 抓取网站内容太慢没有 llms.txt抓取整个 HTML添加 llms.txt提供精选链接列表llms.txt 与 robots.txt 冲突robots.txt 禁止抓取但 llms.txt 被允许检查 robots.txt 是否禁止了爬虫访问根目录多个技能互相冲突两个 Skill 描述相同场景合并为一个技能或修改 description 区分场景技能输出格式不一致缺少输出格式规范在 SKILL.md 中明确模板和示例9. 总结llms.txt和SKILL.md就像大模型时代的两种基础设施一个负责把网站信息变成大模型能轻松读取的结构化清单一个负责把团队经验变成 AI Agent 能遵循的操作手册。两者并不替代而是各管一段。关于文章开头提出的热搜疑问最终的结论是在SKILL.md这个 Markdown 文件中#后面的内容不是“不执行”而是“被 AI 阅读并作为指令依据”。真正要注意的是把指令写清楚、放在正确位置而不是纠结于#的注释语义。建议下一步动手做两件事第一给自己维护的网站加上llms.txt并观察 AI 搜索的抓取效果第二挑一个日常重复度最高的开发任务写一个最小可用的SKILL.md让 AI 助手帮你跑通一次完整流程。只有当文件在你的真实工作流里产生反馈它们才算真正落地。