Skill.md与Llms.txt：LLM应用配置文件的定位、格式与部署实践

这几年 LLM 应用里的文本配置文件越来越多，最容易让人混淆的两份就是 Skill.md 和 Llms.txt。

名字都很短，都跟 AI 有关系，但定位完全不同：

• Skill.md 是给 Agent 看的“操作手册”。它告诉 AI 某个技能该怎么触发、分几步执行、输出什么格式。
• Llms.txt 是给 LLM 抓取工具看的“网站地图”。它告诉大模型应用，某个网站有哪些值得读的内容、链接在哪里。

这两个文件经常被放到一起讨论，是因为它们同时出现在「LLM 应用落地」的部署流程里。一个是让模型更像“会干活的人”，一个是让模型更高效地“拿到外部信息”。很多人一开始会把两者混为一谈，实际它们解决的是两个不同层面的事。

这篇文章会做几件事：

1. 拆开讲清楚 Skill.md 和 Llms.txt 分别负责什么，什么场景只需要其中一个，什么场景需要两个一起上。
2. 给出两份文件的完整格式示例，包含 YAML frontmatter、Markdown 正文、URL 列表写法。
3. 演示如何在本地 Agent 客户端中创建 skill.md 并验证是否被正确加载。
4. 演示如何在网站根目录部署 llms.txt，并用脚本验证可解析性。
5. 补充 API、批量任务、token 资源占用、常见排查方式和最佳实践。

读之前先记住一句最关键的判断：当你在用 Agent/Chat 类工具做自动化任务时，优先关心 Skill.md；当你在运营网站、知识库、文档站，希望被 LLM 应用更容易引用内容时，优先关心 Llms.txt。如果两者同时出现在你的业务链路里，那就需要把两份文件都配置好。

1. 核心能力速览

先给一张表，快速判断两个文件到底差在哪。

从这张表能看出，Skill.md 的产出物往往是“行为”，比如写周报、总结会议纪要、调用某个脚本；Llms.txt 的产出物往往是“内容索引”，让大模型应用知道该去读哪些页面。两者不存在竞争关系，更像是一个在“模型侧”做能力编排，一个在“数据侧”做信息供给。

2. 适用场景与使用边界

Skill.md 适合的场景：

• 团队内部把常用工作流沉淀成技能文件，例如周报生成、代码评审、SQL 查询模板、会议纪要整理。
• 个人把重复性操作固化成标准步骤，例如每天从某个目录读取笔记并生成待办清单。
• 把提示词工程和工具调用结合起来，让文本描述与脚本、命令、API 调用互相配合。

Llms.txt 适合的场景：

• 个人博客或企业文档站希望被 LLM 应用的检索功能直接引用。
• 知识库站点希望降低大模型抓取时的理解成本，用一份索引把重点页面集中暴露。
• 构建 RAG 应用时，用 llms.txt 作为种子链接集合，替代人工搜集 URL 的过程。

这里同时要讲清楚使用边界，越界会导致问题：

1. Skill.md 不是命令执行引擎。它本质是结构化文本，模型读到的是“步骤说明”，真正执行命令或 API 调用的是 Agent 框架。如果某个框架把 skill 内容直接拼进提示词，那么模型可能“照着做”，但不是在执行文件里的命令。因此不要把 skill.md 当成可以远程运行代码的脚本，所有执行权限都应该由 Agent 框架和运行环境约束。
2. Llms.txt 不是 robots.txt。robots.txt 是访问控制声明，告诉搜索引擎哪些路径不能抓；llms.txt 是内容推荐索引，告诉 LLM 哪些页面重要。不能把 llms.txt 当作权限墙，线上敏感数据不放进列表才是正确做法。
3. 涉及版权和隐私时，要确认你有权把页面标题和 URL 列进 llms.txt。同样，skill.md 如果被上传到公共仓库，要检查有没有把内部命令、密钥、接口地址写进去。
4. 如果有人想把 skill.md 用于破解验证码、绕过安全限制、未授权爬取等操作，这是明令禁止的。技能文件只能用于合法、有授权的自动化任务。

针对“ComfyUI 与 LLM 必须在同一台电脑上么”这类本地部署问题，可以顺带说明：Skill.md 只负责定义 LLM 侧的行为，真正执行生图任务的 ComfyUI 通常通过 HTTP API 被外部调用。只要网络互通、端口可达，LLM 与 ComfyUI 不需要装在同一台机器上。反过来说，如果你把 ComfyUI 相关操作写进 skill，只要 API 地址能被 LLM 客户端访问，本地部署和远程部署都可以跑通。

3. 格式与语法拆解

3.1 skill.md 的典型结构

skill.md 的典型结构是“YAML frontmatter + Markdown 正文”。frontmatter 位于文件最顶部，用---包裹，描述技能的名称和触发条件；正文则写具体的执行方法、步骤、示例输出。

--- name: weekly-report description: 当用户需要生成周报、写工作总结或整理本周进展时使用。 --- # 周报生成技能 ## 触发方式 用户说“帮我写周报”“生成周报”“本周总结”等语句时，自动使用本技能。 ## 执行步骤 1. 询问用户本周的时间范围。 2. 读取 `work-log.md`，筛选该时间范围内的记录。 3. 按以下模板输出周报草稿： - 本周完成事项 - 遇到的问题 - 下周计划 - 需要的支持 4. 输出后请用户补充遗漏项，再整理成 Markdown 文档。

这里面的name和description是常见字段。name是技能标识，description是给模型看的语义描述，决定模型什么时候该触发这个技能。不同客户端可能还支持模型文件、脚本附件等，具体以你使用的 Agent 客户端文档为准。

3.2 llms.txt 的典型结构

llms.txt 是放在网站根目录的纯文本文件。格式上接近 Markdown，支持#标题、>描述和[文字](地址)链接。核心逻辑很简单：把所有值得被 LLM 阅读的重要页面列出来，并加上简短说明。

# llms.txt # 示例博客 > 这个站点分享 AI 工具、模型部署教程和 LLM 应用实战。 [首页](https://example.com) [关于本站](https://example.com/about) [AI 工具部署教程](https://example.com/posts/ai-deployment) [Skill.md 详解](https://example.com/posts/skill-md-guide) [Llms.txt 索引实践](https://example.com/posts/llms-txt-practice)

从格式上看，llms.txt 与普通 Markdown 文件差异不大，读起来很直观。支持 llms.txt 的抓取工具会把文件中的链接作为初始 URL 列表，再决定进入哪些页面做深度抓取。相比让 LLM 从整站 HTML 里猜重点，这种方式定位准确，也节省抓取预算。

3.3 skill.md 里#后面到底要不要“执行”

“skill.md 里面 # 后面的是不是不执行”这个问题，在社区里经常被问到。其实要分两层看：

• 如果#出现在文件最上方的 YAML frontmatter 里，比如# 这是注释，那么在 YAML 解析层它会被当作注释，不参与后续数据。
• 如果#出现在正文里，它是 Markdown 标题语法，比如# 周报生成技能是一级标题。Agent 读取时，这些文本会作为上下文供模型理解，而不是被某个解释器“执行”。

真正会触发执行动作的，是模型根据正文里的步骤，决定去调用某个工具、执行某条命令、请求某个 API。也就是说，“#”本身不是命令，问题应当是“模型看完这段描述之后会不会照着做”。如果描述里明确要求“删除临时文件”，而 Agent 的框架又允许执行文件删除操作，那它就可能执行删除，但这与#是否存在无关。所以不要把 skill.md 理解成“带 # 的代码脚本”，更安全的做法是：技能正文里只写你有权限、且希望模型执行的操作，必要时在文件开头加上“需要用户确认后执行”的约束。

4. 环境准备与前置条件

先泼一盆水：Skill.md 和 Llms.txt 都属于“文本配置型”文件，没有很高的硬件门槛。你不需要为测试这两个文件专门买显卡，也不需要安装重型依赖。需要考虑的主要是“谁来消费这份文件”。

4.1 测试 skill.md 需要什么

要验证 skill.md 是否生效，至少需要一个支持 Agent Skills 约定的客户端或 LLM 框架。当前比较常见的选择包括：Claude 桌面客户端、Claude Code，以及社区中不少支持自定义 skill 目录的 LLM 框架。不同工具的 skill 存放目录可能有差异，常见位置是用户目录下的.claude/skills/，每个技能一个子目录，子目录里放skill.md。

建议准备：

• 一个可运行的 Agent 客户端或本地 LLM 框架。
• 一个用于测试的技能目录，例如~/.claude/skills/test-skill/。
• 一个文本编辑器，建议支持 Markdown 和 YAML 语法高亮。
• 如果技能要调用外部脚本或 API，还需要对应运行环境，例如 Python、Node.js、网络访问权限。

4.2 测试 llms.txt 需要什么

llms.txt 静态托管就可以。任何能托管 HTML 的服务器或对象存储服务，都能托管 llms.txt。本地测试只需要一个可访问的目录，或一个临时 Web 服务。

建议准备：

• 一个可公网访问或内网可访问的网站根目录。
• 域名解析正常，能通过https://你的域名/llms.txt访问。
• Python 环境（用于写解析验证脚本），或者直接用 curl 做请求检查。
• 如果网站已有 robots.txt 和 sitemap.xml，建议同步检查，确认 llms.txt 没有被 robots 规则误拦。

这里不涉及具体的 CUDA、PyTorch 版本要求，因为 Skill.md 与 Llms.txt 本身不依赖模型推理环境。真正对显存和计算资源有要求的，是运行 Agent 或大模型推理的底层服务。比如你的 skill 需要调用本地 LLM 的 API，那么那台提供模型服务的机器才需要关注显卡、显存、模型体积和推理框架版本。

5. skill.md 创建、加载与效果验证

5.1 创建技能目录与文件

以常见的 Claude Code 风格目录为例，新建一个名为weekly-report的技能目录，里面放skill.md：

mkdir -p ~/.claude/skills/weekly-report cd ~/.claude/skills/weekly-report touch skill.md

Windows 用户可以用资源管理器创建：

C:\Users\<你的用户名>\.claude\skills\weekly-report\skill.md

然后把上一节的示例内容写进skill.md。保存时注意编码用 UTF-8，文件后缀小写.md。

5.2 重启客户端并触发

在支持 Agent Skills 的客户端里，保存文件后一般需要重启或刷新会话，让客户端重新扫描技能目录。重启后，在对话中输入：

帮我写这周的周报

如果客户端加载正常，它会根据description中的语义描述识别出weekly-report技能，然后按正文步骤执行：询问时间范围、读取工作日志、生成草稿。你可以在回复里看到它是否引用了 skill 中的步骤模板。

如果触发失败，先检查三件事：

1. 文件路径是否在客户端扫描的 skill 目录内。
2. frontmatter是否用---完整包裹，且没有语法错误。
3. description是否足够明确，模型能不能判断“这句话应该触发这个技能”。

5.3 用脚本验证 skill.md 可解析性

不启动客户端，也可以用一个简单脚本验证文件结构是否合法。下面这个示例用 Python 读取skill.md，解析前 2 行---中间的 YAML，把元信息和正文分离：

from pathlib import Path import yaml skill_file = Path.home() / ".claude/skills/weekly-report/skill.md" content = skill_file.read_text(encoding="utf-8") if content.startswith("---"): parts = content.split("---", 2) meta = yaml.safe_load(parts[1]) body = parts[2].strip() print("技能名：", meta.get("name")) print("描述：", meta.get("description")) print("正文前 200 字：") print(body[:200]) else: print("未找到 frontmatter，请确认文件以 --- 开头。")

这段脚本不验证“模型会不会执行”，只验证文件格式是否可能被客户端正常解析。如果你用的客户端对 frontmatter 字段有额外要求，比如必须有name且不能为空，脚本可以进一步补充字段检查。

5.4 判断成功的标准

一次完整的 skill 测试，建议用下面几个标准判断是否成功：

• 客户端能列出或在日志中识别到该技能。
• 在对话中用接近description语义的话能够触发技能。
• 模型按正文步骤生成了目标产物，而不是自由发挥。
• 如果技能包含工具调用，步骤中出现的操作确实被执行，输出结果是预期格式。

如果以上任何一个环节不通过，说明 skill.md 的位置、格式或描述还不够准确，需要回到配置侧排查。

6. llms.txt 部署、解析与效果验证

6.1 添加文件到网站根目录

把第 3 节的 llms.txt 示例内容保存为纯文本，上传到网站根目录。假设你的域名是example.com，那么最终访问地址应当是：

https://example.com/llms.txt

这里要注意，文件必须能通过公网直接访问，不要放在需要登录鉴权的目录里。部署后先用浏览器或命令行确认返回内容：

curl -sI https://example.com/