两年前我们讨论网页如何被搜索引擎爬虫理解时只需要一个robots.txt就够了。如今当 AI 应用开始大规模读取网站、调用工具、执行任务时一个新的问题摆在了每一个开发者面前你的网站和项目到底应该如何向 AI 描述自己这段时间Skill.md和Llms.txt这两个文件名频繁出现在 AI 工程化的讨论里。很多人第一次看到它们时第一反应是这俩是不是同一个东西或者一个是另一个的替代品如果你也有这种困惑不要紧因为从表面看它们确实都长得很像 Markdown 文件目标都是让 AI 更懂我们。但它们的定位、读取方式、服务对象完全不同。这篇文章会讲清楚三件事Skill.md到底是什么Llms.txt到底是什么以及在一个真实的 AI 项目中你什么时候只需要其中一个什么时候必须两个都上。读完你就能直接判断自己的项目该怎么配。1. 为什么这两个文件最近突然被频繁讨论先说一个背景。过去一年AI 应用的形态发生了明显分化一类是内容消费型比如 ChatGPT、Claude 这类对话产品要读取你的网页内容另一类是任务执行型比如各类编程助手、Agent 框架要调用你的工具、执行你的命令。这两类需求催生了两种不同的文件约定。Llms.txt解决的是第一类问题。2024 年年中fast.ai 创始人 Jeremy Howard 提出了一份草案规范让网站提供一个简单的 Markdown 文件用人类和 LLM 都能读懂的格式概括网站的核心信息、主要页面和内容入口。你可以把它理解成给 AI 看的站点地图 网站简介。它要解决的问题很直接现在的 LLM 抓取网页时网页里大量导航、广告、脚本会严重干扰理解模型经常找不到真正有用的正文内容。而llms.txt就是让网站主动告诉 AI我的核心内容在这里重点看这几个页面。Skill.md解决的是第二类问题而且是在 Agent 生态爆发之后才成为热点的。以 Claude 为代表的 Agent 平台开始支持一种技能Skills机制在一个项目里放一个SKILL.md文件里面用 Markdown 描述这个 Agent 应该掌握的一项能力包括触发条件、执行步骤、注意事项等。这个文件不是给人类用户看的而是给 Agent 的模型看的。它会在合适的时候被注入到上下文中告诉 Agent你有一个技能可以用按这个流程来做。从实际开发来看很多人把这两个文件混在一起或者在不该用的时候强行使用导致配置了llms.txt却抱怨 Agent 不执行技能或者写了SKILL.md却期望它能被搜索引擎收录。定位混乱是当前最大的坑。本文的重点就是帮你把这两个文件彻底区分开并给出可以直接复用的配置方案。2. Skill.md 与 Llms.txt 的核心定位与本质差异先给出最核心的判断Skill.md是给 Agent 看的技能说明书Llms.txt是给 LLM 看的网站说明书。一个管怎么做一个管有什么。2.1 二者定位对比维度Skill.mdLlms.txt规范来源Anthropic Claude Skills 等 Agent 框架约定Jeremy Howard 提出的开放草案规范服务对象Agent具备工具调用能力的 AI通用 LLM、AI 爬虫、RAG 系统核心作用定义一项可执行技能的操作流程提供网站的概要信息与内容索引文件位置项目根目录或特定 skills 目录下网站根目录内容形式YAML frontmatter Markdown 指令正文纯 Markdown标题 无序列表读取方式由 Agent 运行框架按需注入上下文由 AI 爬虫主动请求或开发者主动抓取是否可执行描述流程具体执行由 Agent 调用工具完成不涉及任何执行逻辑这张表是理解两者差异的关键。注意看是否可执行这一行很多人的困惑就出在这里Skill.md里面的内容确实会影响 Agent 的执行行为但它本身不是一段代码脚本。它是一个描述文件真正执行动作的是 Agent 的模型加工具调用。而Llms.txt连影响执行都算不上它只是一个被动的信息源。2.2 用两个类比快速理解Llms.txt更像一个公司前台指引牌。你到一家公司先看到门口写着这里是 XX 科技主营业务是 SaaS 软件核心产品文档在 /docs联系方式在 /contact。 AI 看到这个指引牌就知道这个网站是干嘛的值得抓哪些页面不用把整栋楼每个房间都翻一遍。Skill.md更像员工操作手册。你面试了一个新员工Agent他能力很强但不知道你们公司的具体流程。你在他的工位上放一本手册上面写着当客户要求退款时先验证订单状态再走退款流程最后发送通知邮件。 员工需要执行这个任务时就会翻看这本手册。一个是前台指引一个是员工手册服务对象和用途完全不同。3. Skill.md 的完整格式拆解它到底在项目里怎么工作市面上现在有好几种 Agent 技能格式Claude 的 Skills、Cline 的 Skills、开源社区的 Agent Skills 规范等细节上有差异但核心结构基本一致。我们用最通用的格式来说明。3.1 文件位置与命名在 Claude 生态中技能文件约定放在项目的.claude/skills/skill-name/SKILL.md路径下也可以在项目根目录直接放置SKILL.md。在 Cline、Roo Code 等 VS Code 插件中通常是在.claude/skills/或.cursor/skills/目录下按技能名建子目录每个子目录里有一个SKILL.md文件。还有一些框架支持直接读项目根目录的SKILL.md作为全局技能。不同框架的目录路径可能不一样但文件命名基本都遵循SKILL.md或skill.md这个约定。3.2 文件内部结构一个标准的SKILL.md包含两部分YAML frontmatter 和 Markdown 正文。YAML frontmatter 用---包裹放在文件最顶部用来定义技能的元信息最关键的是name和description。name是技能名description是给 Agent 看的技能描述。这里有一个很多人误解的细节description不是给人读的功能介绍而是触发条件描述。Agent 会根据当前任务和这个 description 做语义匹配决定要不要加载这个技能。所以 description 里要写清楚什么时候用这个技能、解决什么问题、有什么前置条件。Markdown 正文部分是技能的具体操作指令。这里可以写清楚执行步骤、注意事项、示例、工具调用建议等。Agent 在决定使用某个技能后会把这份正文内容注入到上下文中作为行为约束。3.3 一个可直接使用的 SKILL.md 示例以为项目编写 README这个技能为例完整配置如下--- name: project-readme-writer description: 当用户要求为当前项目创建或更新 README 文档时使用这个技能。 适用于新项目初始化、代码重构后文档同步、开源项目文档发布等场景。 技能会分析项目结构、核心代码和依赖信息生成结构清晰的 README 文件。 --- # 项目 README 编写技能 ## 目标 根据当前代码仓库的实际情况生成或更新 README.md 文件使其内容准确、结构清晰、易于新用户快速上手。 ## 执行步骤 1. 使用文件读取工具扫描项目根目录获取文件列表和目录结构。 2. 读取项目的包管理文件如 package.json、requirements.txt、pom.xml 等提取项目名称、版本、依赖信息。 3. 查看源码目录的入口文件和核心模块了解项目的核心功能和架构。 4. 按以下结构输出 README.md - 项目简介一句话 详细说明 - 功能特性列表 - 环境要求 - 安装步骤 - 快速开始示例 - 项目结构说明 - 常见问题 5. 如果已存在 README.md先读取原文保留仍有用的信息再补充缺失内容。 ## 注意事项 - 安装命令和 API 示例必须从代码中确认不要凭空编写。 - 版本号以实际依赖文件为准不要写死。 - 如果项目没有包管理文件明确说明暂无自动构建配置。# 这段 YAML 是 frontmatter 元信息不是 Markdown 正文 name: project-readme-writer description: 当用户要求为当前项目创建或更新 README 文档时使用这个技能看到这个文件你应该能理解为什么很多人会产生#后面的内容不执行的疑惑。在 YAML frontmatter 中#开头的位置是注释确实会被解析器忽略但在 Markdown 正文中#是标题语法不是注释Agent 会把它当作语义结构来理解而不是忽略。严格来说SKILL.md里没有不执行的代码它本来就是一份供模型阅读的指令文本影响的是 Agent 的行为而不是一段解释执行的脚本。3.4 Skill.md 在 Agent 运行时的工作流程了解工作流程会更清楚这个文件的作用Agent 收到用户指令比如帮这个项目生成 README。Agent 框架把所有可用技能的元信息name description加载进来。模型根据当前指令与技能 description 做语义匹配。匹配成功后框架把对应的SKILL.md正文注入到对话上下文中。Agent 根据正文内容的步骤调用文件读写工具完成任务。这五个流程中最容易出问题的就是第 3 步。如果 description 写得太泛Agent 可能在该用的时候不加载写得太窄又可能在无关场景下误触发。所以 description 的措辞非常关键。4. Llms.txt 的规范与实现给 LLM 一个干净的信息入口明确了Skill.md的全貌之后我们再来看Llms.txt。它解决的完全是另一类问题当 LLM 访问你的网站时如何快速获取准确、结构化、无干扰的信息。4.1 背景与设计初衷这个规范最初由 Jeremy Howard 于 2024 年年中提出目的是对标robots.txt但服务对象从搜索引擎爬虫换成了LLM 和 AI 爬虫。传统网页的 HTML 结构是为浏览器设计的里面有大量导航栏、侧边栏、广告模块、脚本代码LLM 直接抓取时信息信噪比极低。llms.txt的设想是网站主动提供一个纯净的 Markdown 文件把网站的核心信息、重要页面入口、内容摘要放进去AI 系统只要读这一个文件就能快速判断这个网站值不值得深入抓取。这个文件的设计哲学是简单到极致它就是一份普通的 Markdown 文本不需要特殊语法不需要 JS 渲染不需要 API 认证。任何能发 HTTP 请求的 AI 系统都能直接获取。4.2 标准格式llms.txt草案的格式相当简洁主要内容包括标题一级标题通常是网站名称。说明段落一两句话介绍网站定位和核心内容。无序列表列出网站的关键页面或资源的相对 URL 和链接文本。这里刻意用了 Markdown 的标题和无序列表语法是因为 LLM 对这两种结构理解得最好。规范甚至建议使用不带前言介绍的裸列表格式减少无意义文本。4.3 一个符合草案的 llms.txt 示例假设你维护一个技术博客网站根目录下的llms.txt可以这样写# TechBlog AI Docs TechBlog 是一个专注于 AI 工程实践的开发者博客内容涵盖大模型应用开发、 Agent 框架实践、向量数据库、RAG 系统和模型评测。 ## 核心页面 - [首页](https://example.tech/blog/index.html): 最新文章列表和站点介绍 - [AI Agent 入门教程](https://example.tech/blog/guide/agent-intro.html): 从零开始搭建 Agent 的完整教程 - [RAG 系统实践](https://example.tech/blog/guide/rag-practice.html): 基于向量数据库的 RAG 实现步骤 - [模型评测方法论](https://example.tech/blog/guide/eval-method.html): 大模型效果评估的常见维度和方法 - [关于本站](https://example.tech/blog/about.html): 站点作者和内容方向说明这就是一个标准的llms.txt。注意几个细节说明部分只有一两句话点到为止。链接全部使用完整 URL方便 AI 直接拼接访问。每条链接有一行简短说明帮助模型判断是否值得抓取。4.4 部署与验证部署llms.txt不需要任何后端逻辑只需把文件放在网站根目录保证可以通过https://yourdomain.com/llms.txt访问即可。验证是否生效可以直接用一个简单的请求测试curl https://example.tech/llms.txt# 期望输出 # TechBlog AI Docs # # TechBlog 是一个专注于 AI 工程实践的开发者博客内容涵盖大模型应用开发、 # Agent 框架实践、向量数据库、RAG 系统和模型评测。如果返回 200 状态码且内容正确说明你的网站已经可以被 AI 系统读取。顺带一提robots.txt还在两者职责不同robots.txt规定哪些路径 AI 不能抓llms.txt指引哪些内容 AI 应该优先读。两者完全可以共存。5. 彻底搞懂两者的读取机制差异很多人配置完发现不生效问题往往出在以为写了文件就会自动生效。事实是这两个文件都不是魔法都需要有人主动读取。5.1 谁在读取 Skill.mdSkill.md的读取方是 Agent 框架不是模型本身。也就是说你在项目里放好了这个文件还必须依赖你使用的 Agent 框架支持这种技能约定。不同框架对技能目录的扫描逻辑、加载时机、上下文注入策略都不一样。如果你把文件放在了错误的位置或者框架本身不支持这个约定这个文件就不会被加载。另外Skill.md的加载不是每轮对话都发生的。框架通常只加载技能的元信息name 和 description用于匹配只有在真正命中技能时才把完整正文注入进来。这是为了节省上下文窗口。所以你可能会遇到技能文件写得很详细但 Agent 就是没用上的情况核心原因往往是 description 没有和用户任务匹配上。5.2 谁在读取 Llms.txtLlms.txt的读取方是外部的 AI 系统。从目前的实践来看主要有三类第一类是支持该规范的 AI 搜索引擎或爬虫它们在抓取网站前会主动请求llms.txt优先读取其中的内容而不是直接解析整个 HTML。第二类是 RAG 系统你可以把llms.txt作为种子文件先让系统了解网站全貌再有针对性地爬取页面。第三类是开发者自己在构建 AI 应用时手动请求llms.txt来获取数据源。注意llms.txt不是服务端主动推送的它需要被主动请求。当一个 AI 系统访问你的网站时它不会自动知道你的llms.txt在哪除非它主动去请求根目录下的这个固定路径。5.3 两者在 AI 应用架构中的位置差异从架构层面看Skill.md位于Agent 应用层它服务于你的 Agent 应用属于应用内部资产Llms.txt位于外部数据接入层它服务于任何访问你网站的外部 AI 系统属于公网资产。用一句话总结Skill.md让你的 Agent 会干活Llms.txt让外面的 AI 能找到你。一个是内力一个是招牌。6. 三个典型场景到底该用哪个了解了原理最实际的问题来了我的项目应该配置哪个6.1 场景一个人博客、公司官网、文档站点这一类场景的核心诉求是让 AI 准确理解我的内容。推荐配置llms.txt并且只配置它。原因很简单这类网站不需要 Agent 执行任务只需要让 AI 搜索和 RAG 系统能准确获取内容。配置llms.txt可以显著提升 AI 引用你内容的准确性减少因 HTML 噪声导致的错误信息抓取。6.2 场景二本地 CLI Agent 项目、AI 编程助手使用的工作流如果你在维护一个代码仓库并且团队使用 Claude Code、Cline、Roo Code 这类编程助手那么配置Skill.md是正确选择。举例来说你的项目有自己独特的代码规范、测试命令、部署流程你可以把这些写成技能让 Agent 在相关任务里自动遵循规范而不用每次口头交代。6.3 场景三AI 驱动型产品两者都要如果你的产品同时具备两个特征就需要两者都配置。典型的例子是你开发了一个提供 API 的技术文档站同时你又在项目里内置了一个 AI 助手让它能帮用户完成一些操作。这时文档站的llms.txt让外部 LLM 能理解你的 API 文档而在项目仓库里的Skill.md则让你自己的 AI 助手掌握项目特有的操作流程。另外一个常见组合是公开网站 抓站型 Agent。例如你运营一个招聘平台网站上配置llms.txt让 AI 搜索引擎能搜索到你的职位信息同时你用 Agent 监控竞争平台的信息这个 Agent 需要访问你公司内部数据库的技能那就在 Agent 项目中配置SKILL.md。6.4 一个简单的判断规则如果不确定怎么选可以问自己两个问题这个文件服务的对象是谁如果是给外部 AI/搜索引擎看的 →llms.txt如果是给自己项目里的 Agent 用的 →Skill.md这个文件需要跟项目代码一起管理迭代吗不需要属于内容发布 →llms.txt需要跟随代码仓库、有版本演进 →Skill.md两个问题都指向同一个答案时就只配那一个指向不同答案就两个都配。7. 实战在同一个 AI 文档站中同时配置两个文件为了让你更直观地理解两者如何协同我们用AI 命令行工具文档站这个场景演示完整配置。7.1 项目结构假设项目结构如下ai-terminal-tool/ ├── .claude/ │ └── skills/ │ └── command-docs/ │ └── SKILL.md ├── docs/ │ ├── install.md │ ├── usage.md │ └── api.md ├── site/ │ ├── index.html │ └── llms.txt └── README.md在这个结构里site/llms.txt是给外部 AI 搜索引擎看的.claude/skills/command-docs/SKILL.md是给项目开发环境里的 Claude Code 助手用的。7.2 编写 Llms.txt# AI Terminal Tool Docs AI Terminal Tool 是一个开源的命令行效率工具支持智能命令推荐、 历史命令搜索和自动化脚本生成。核心功能包括交互式命令面板、 模糊搜索、别名管理和跨平台同步。 ## 核心页面 - [首页](https://ai-terminal-tool.example.com/index.html): 工具简介、功能列表和下载入口 - [安装指南](https://ai-terminal-tool.example.com/docs/install.html): 支持 macOS、Linux、Windows 的安装方法 - [使用教程](https://ai-terminal-tool.example.com/docs/usage.html): 命令面板、快捷键和配置示例 - [API 参考](https://ai-terminal-tool.example.com/docs/api.html): 插件开发接口和事件说明 - [GitHub 仓库](https://github.com/example/ai-terminal-tool): 源码、Issue 和贡献指南7.3 编写 Skill.md在.claude/skills/command-docs/SKILL.md中定义一项技能当用户询问如何使用 AI Terminal Tool 的某个命令时Agent 根据这份文档生成精确的命令示例和解释。--- name: command-docs-explainer description: 当用户询问 AI Terminal Tool 的具体命令用法、参数含义或配置方式时 使用这个技能从项目文档中提取准确信息并生成使用示例。 --- # AI Terminal Tool 命令文档解释技能 ## 目标 基于项目 docs/ 目录中的官方文档为用户提供准确、可执行的命令示例。 ## 执行步骤 1. 读取 docs/api.md 和 docs/usage.md定位用户所询问的命令或配置项。 2. 从文档中提取命令语法、参数表格和示例代码。 3. 如果文档中缺少某个命令的说明明确告诉用户官方文档未覆盖该命令不要自行猜测参数。 4. 输出时按以下格式组织 - 命令用途一句话 - 语法格式完整命令 - 参数说明表格 - 常用示例至少两个 5. 如果用户的要求涉及插件开发补充读取 docs/api.md 中的事件说明。 ## 注意事项 - 所有命令示例必须能从官方文档中找到依据禁止编造参数。 - 版本相关的内容标注所用文档版本如果文档未显示版本则说明以最新稳定版为准。 - 如果用户在项目源码场景提出疑问优先查看源码中的注释和测试用例。7.4 如何验证两者都生效验证llms.txtcurl -s https://ai-terminal-tool.example.com/llms.txt | head -n 5如果输出第一行是# AI Terminal Tool Docs说明配置正确。验证Skill.md在项目目录下启动你的 Agent 工具输入列出这个工具的 API 参考里所有事件说明观察 Agent 是否自动加载了command-docs-explainer技能并按照docs/api.md中的内容回答。如果 Agent 回答了官方文档未覆盖或自行猜测说明技能没有匹配上需要检查description中是否包含足够多的相关关键词。8. 常见问题与排查思路实际使用中大部分问题集中在不生效和读错两类。下表整理了最常遇到的问题和对应的排查手段问题现象可能原因排查方式解决方案Agent 没有使用 SKILL.md 中的指令description 与用户任务不匹配查看 Agent 日志中技能加载记录重写 description明确技能适用场景增加任务关键词SKILL.md 放在项目里但完全没被扫描到目录路径不符合框架约定对照所用框架的 skills 目录文档移到框架约定的目录如.claude/skills/name/SKILL.mdSKILL.md 中#后面的内容没有按预期生效把 Markdown 标题当成了 YAML 注释区分 frontmatter 与正文检查是否存在格式错误确认 frontmatter 用---包裹正文的#是标题不是指令开关curl https://域名/llms.txt返回 404文件未放到网站根目录或 CDN 缓存检查服务器文件路径和部署日志将文件放到根目录并刷新缓存LLM 抓取网页仍然很乱llms.txt存在但外部 AI 系统未遵循该规范搜索该 AI 系统的官方文档只能等待支持方逐步适配或主动向 RAG 系统注入该文件技能文件内容很多但响应变慢技能正文太长注入上下文占用了大量 token查看上下文 token 使用量精简技能正文只保留必要步骤和关键示例多个技能 description 相似Agent 选错技能技能之间语义空间重叠对比各技能的 description 措辞为每个 skill 定义清晰的边界和独特的行为动词几个特别值得强调的点关于#不执行的问题。这是近期社区里非常高频的一个疑问。结论是SKILL.md中 YAML frontmatter 里的#是注释格式会被解析器忽略而 Markdown 正文中的#是标题语法是结构信息Agent 会正常理解。根本不存在#后面的内容不执行的说法因为SKILL.md本来就不是一段执行的代码它是一份供模型阅读的指令文本。执行的是 Agent 模型在理解这份文本之后的行为决策。关于 llms.txt 和 sitemap.xml 的区别。这是另一个容易混淆的点。sitemap.xml是给搜索引擎的 XML 格式链接清单包含所有页面的优先级和更新频率llms.txt是给 LLM 的语义化内容概要。前者重链接元数据后者重内容理解。9. 最佳实践与工程建议到了落地环节结合社区实践和自身使用经验提出下面几条建议。9.1 为 Skill.md 编写高质量 descriptiondescription决定了技能何时被触发是所有配置中权重最高的一项。建议在description中包含技能的适用任务类型动词 对象、前置条件、不适用场景。例如description: 当用户要求生成 SQL 查询语句或分析数据库表结构时使用。 本技能适用于 MySQL 和 PostgreSQL 数据库不适用于 NoSQL 数据库。 如果用户只是询问数据库概念不需要使用本技能。9.2 保持 Llms.txt 内容精简llms.txt的核心价值是简洁。不要在文件里堆砌所有页面链接只列出最重要的入口和内容分类。一个常见误区是把llms.txt写成sitemap.xml的 Markdown 版几百个链接全部堆上去。这样反而稀释了 AI 的注意力让它难以识别什么才是重点。建议控制在 20 到 30 条链接以内并按类别分组用二级标题分隔。9.3 不要把敏感信息写进这两个文件llms.txt是公网可访问的SKILL.md在团队协作时也会被更多人看到。不要在llms.txt中暴露内部 API 端点、数据库地址或未公开的页面路径不要在SKILL.md中写入含有真实密钥、密码的操作步骤。需要涉及敏感操作时建议在技能中引用环境变量或外部安全存储而不是明文写死。9.4 为 Skill.md 建立版本和测试机制技能文件会随着项目演进而修改。建议把技能名、用途写入变更历史并在修改后做一轮回归测试用相同的历史任务输入观察 Agent 行为是否符合预期。可以在项目 README 中增加一个章节记录技能清单和各自对应的测试用例路径方便后续维护。9.5 将 Llms.txt 纳入发布流程如果你维护的是内容型网站建议把llms.txt的生成纳入静态站点构建流程。比如在做完站点编译后自动从页面元数据中提取核心链接生成llms.txt并部署到根目录。这样能避免内容更新后llms.txt长期不同步的问题。9.6 理解规范的演进性需要提醒的是llms.txt目前仍是草案规范还没有形成像robots.txt那样的行业标准。这意味着并不是所有 AI 爬虫都会支持它。SKILL.md的格式则在不同框架之间存在差异。因此在生产环境中建议关注你所使用的框架的官方文档以最新约定为准不要死守某一版格式。本文描述的是一套通用思路和最小可行示例具体实现以你手上的框架版本为准。10. 总结与后续实践路径现在回到最开始的判断Skill.md是给 Agent 看的技能说明书Llms.txt是给 LLM 看的网站说明书。前者管怎么做事后者管怎么理解内容。如果你的项目是一个内容驱动的网站配置llms.txt让 AI 更容易找到你、读懂你。如果你的项目是 Agent 驱动的工具或代码仓库配置SKILL.md让你的 Agent 更规范、更稳定。如果你两者兼顾那就在公网侧放llms.txt在仓库里放SKILL.md各司其职。下一步建议从最小改动入手先为你的博客或公司官网写一个极简llms.txt并用curl验证再为你的 Agent 项目写一个只解决单一任务的SKILL.md跑通一次完整的任务 → 技能匹配 → 执行 → 输出流程。跑通之后再逐步扩展技能数量和llms.txt的页面覆盖范围。这两个文件的本质都是在 AI 时代重新定义如何向机器描述自己的世界。想清楚服务对象你就已经避开了大多数人都会踩的坑。