`AGENTS.md` 与 `SKILL.md` 是写给谁看的
一个仓库根目录同时躺着 AGENTS.md 和 SKILL.md，两个文件名都带 agent，很容易被当成”同一件事写了两遍”。DeepTutor 里这两份文件是两个不同用途的交接文档，读者不同、失效后果也不同——后一点是本文想讲透的地方。
本文所有行号与数字都对应我们采集的仓库快照：HEAD 456f9c2，采集日 2026-08-10，deeptutor/__version__.py 里的版本号是 1.5.11。你自己 clone 之后行号可能已经漂了，文件名和小节标题是稳的，照着搜即可。
一、两份文件的体量与自我定位
先把最基础的两个数字摆出来，这是后面所有讨论的地基：
| 文件 | 行数（wc -l） | 一级标题 | 受众定位 |
|---|---|---|---|
AGENTS.md | 138 | DeepTutor — Agent-Native Architecture | 文中未明写受众，按 Overview 内容归纳：读代码、改代码的人与 agent |
SKILL.md | 203 | DeepTutor CLI Skill | 副标题原文写明：教你的 AI agent 通过命令行操作 DeepTutor |
第四列要分清两种来源：SKILL.md 那一行是文件自己写的，AGENTS.md 那一行是我们读完开头一段之后的归纳，文件里并没有这么一句话。
AGENTS.md 讲的是这个项目是怎么搭起来的：两层插件模型（单次调用的 Tools 与接管整轮的 Capabilities）、三个入口（CLI、WebSocket、Python SDK），后半段是 Key Files 表与依赖分层（AGENTS.md:1-13、AGENTS.md:100-138）。它列了 7 个 capability 及各自的 stage：chat、mastery_path、deep_solve、deep_question、deep_research、visualize、math_animator（AGENTS.md:58-66）。这类内容的读者是要往仓库里加东西的人——你想加一个工具，得先知道工具挂在哪一层。
SKILL.md 讲的是怎么用命令行把这个东西开起来、用起来。它的副标题一句话写死了受众：教你的 AI agent 通过命令行配置、管理和使用 DeepTutor（SKILL.md:1-3）。里面有安装前置条件、命令分组，以及一张 13 行的 REPL 斜杠命令表（从 /quit 到 /config，SKILL.md:159-173）。这张表和本文的关系只在一点上：它里面有 /kb、/config 这类会改动本机配置与知识库的命令，而这份文件是会被 agent 自动读走的——具体每条命令怎么用，我们另有一篇专门讲命令面。
二、反直觉的那一处：SKILL.md 的读者不是你
大多数人读到”handover doc”会默认这是给新同事看的。但 README 把这份文件的实际消费方式写明了：它是一份交接文档，可以直接交给 Claude Code、Codex 或 OpenCode，这几个工具会自动读取 SKILL.md（README.md:719）。
把这句话拆开看，含义是具体的：这份 Markdown 的第一读者是你本机正在跑的那个 agent CLI，不是你。 按 README 那句话，这几个工具会自动读取 SKILL.md，也就是说你把仓库 clone 下来、在里面开一个 agent 会话，这 203 行会被当作可执行的操作说明照做：装包、初始化配置、建知识库、装技能包——这些动作都发生在你本机，都是真实的程序执行与文件写入。这一段是照 README 的描述推的，我们没有安装过、也没有跑过任何一个 agent 会话去验证。这一点必须说在前面：让 agent 照着一份操作手册在本机执行命令，和你自己一条条敲，风险不是一个量级，尤其是其中包含从外部 hub 安装技能包这类会把第三方内容拉到本地的动作。是否这么用，请结合自己的环境判断。
这个定位差异带来一个直接后果，也是本文的主线：同样是文档与代码对不上，AGENTS.md 写偏了是人看偏，SKILL.md 写偏了是 agent 直接照着做偏。 一个人读到过时的命令，敲一次报错就知道回头查；一个 agent 读到过时的命令，可能会开始自行猜测、重试、换写法，你要从它一串动作里倒推是哪一行文档不对。这一句是按 agent 的通用工作方式推的，不是我们观察到的行为。
所以这两份文件里那些与代码不一致的地方，值得单独拎出来核一遍。下面这些都是我们逐处比对读出来的，按纪律只陈述差异、标明两处位置，不推断原因，也不据此评价项目。
三、六处可核查的差异
1. 默认 skill hub：SKILL.md 说 clawhub，代码是 eduhub
SKILL.md:89 写 hub 引用格式是 <hub>:<slug>[@version]，并注明 hub 前缀默认是 clawhub；SKILL.md:12 的 When to Use 里也只提到 ClawHub。代码这边，deeptutor/services/skill/hub.py:67 是 DEFAULT_HUB = "eduhub"，README 同样说 EduHub 是默认 hub、裸 slug 解析到它（README.md:761、README.md:766）。
这一处对 agent 的影响最直接：安装技能时省略 hub 前缀，落到哪个 hub 由代码里那一行常量决定。核法就一条命令的事——搜 DEFAULT_HUB 看它等于什么。
2. 用户可开关的工具数：AGENTS.md 说 4 个，代码是 7 个
AGENTS.md:34-42 写的是 “Four user-toggleable tools”，表里只列 brainstorm、web_search、paper_search、reason。代码里的 USER_TOGGLEABLE_TOOL_NAMES 是 7 项，多出 geogebra_analysis、imagegen、videogen（deeptutor/tools/builtin/__init__.py:1627-1635）。
这一处有意思的地方在于：README 与 SKILL.md 的表述与代码是一致的（README.md:484、SKILL.md:57）。也就是说四份材料里，对不上的是其中一份。核法：打开 deeptutor/tools/builtin/__init__.py，搜 USER_TOGGLEABLE_TOOL_NAMES，数这个元组里的名字。
3. geogebra_analysis 是不是 “Coming soon”
AGENTS.md:51-52 写它被挂在 COMING_SOON_TOOL_TYPES 下。代码里 COMING_SOON_TOOL_TYPES 是一个空元组，注释写着当前没有工具被挂起（deeptutor/tools/builtin/__init__.py:1610-1614）；而 geogebra_analysis 出现在上一条说的那份用户可开关列表里（deeptutor/tools/builtin/__init__.py:1632）。
这两条差异挨在一起，核的时候一次看完：同一个文件里先搜 COMING_SOON_TOOL_TYPES 看括号里有没有东西，再往下几行看那份名单。
4. deeptutor-cli 到底能不能从 PyPI 装，四处口径不一
这一处牵扯的文件最多，摆成表更清楚：
| 位置 | 写的是什么 |
|---|---|
README.md:372、README.md:755 | CLI-only 包没上 PyPI，只能从源码 checkout 装 |
AGENTS.md:78、AGENTS.md:126 | 安装方式写作 pip install deeptutor-cli # CLI-only |
requirements/cli.txt:7 | 头注写 “Public install: pip install deeptutor-cli” |
SKILL.md:20 | 写 pip install deeptutor-cli 用于 CLI-only |
再看发布侧：.github/workflows/pypi-release.yml:139-153 的校验清单里只要求并发布 deeptutor 一个 wheel。
这一处对 agent 的影响是可以预见的：一个照着 SKILL.md 开头那段安装前置条件走的 agent，装 CLI-only 时会先去 PyPI 拿这个名字。至于那条命令在真实 PyPI 上是什么结果，我们没有联网核实，也没有安装过，不下结论——能确定的只有仓库内这四处写法与发布工作流的产物清单。
5. SKILL.md 的篇幅：README 自称 ~150 行，实际 203 行
README 把根 SKILL.md 描述为 “a ~150-line handover doc”（README.md:719），而 wc -l SKILL.md 数出来是 203。这条差异本身不影响任何行为，把它列出来是因为它最容易验证：一条 wc -l 就能自己复核，适合当作”文档数字要回仓库核”这件事的入门样本。
6. skill 子命令：README 列 8 个，SKILL.md 列 4 个
README 的命令表列出 deeptutor skill search / install / list / remove / login / logout / publish / update（README.md:735）；SKILL.md:92-95 只列了 search / install / list / remove 四个。
对一个只读 SKILL.md 的 agent 来说，它的可见动作面就是这四个。要判断某个子命令到底存不存在，别停在两份文档谁对谁错上，直接跑 deeptutor skill --help 看实际输出——这也是我们唯一推荐的判定方式，因为我们没有安装过这个项目，--help 的真实输出是什么样，本文不做描述。
顺带还有一处与安装相关的口径差：AGENTS.md:129-137 的 “Source extras” 只列了 cli / server / partners / matrix / matrix-e2e / math-animator / dev / all 这几个，README 的安装示例只给 5 个（README.md:265-269），而 pyproject.toml:80-240 里实际定义了 15 个 optional-dependencies key（多出 parse-markitdown、parse-docling、parse-pymupdf4llm、parse、tutorbot、graphrag、rag-lightrag）。其中 tutorbot 在 pyproject.toml:176-177 被注明为 “Legacy alias kept for one release”。
四、你可以照着核的五步
wc -l AGENTS.md SKILL.md，确认 138 / 203 这两个数，再和README.md:719的自称数字比一比。- 打开
deeptutor/services/skill/hub.py，搜DEFAULT_HUB，与SKILL.md:89那句默认前缀对照。 - 打开
deeptutor/tools/builtin/__init__.py，一次看完COMING_SOON_TOOL_TYPES与USER_TOGGLEABLE_TOOL_NAMES两处，再回AGENTS.md:34-52对照。 grep -n "deeptutor-cli" README.md AGENTS.md SKILL.md requirements/cli.txt，把四处写法并排看一遍，再看.github/workflows/pypi-release.yml的产物校验清单。- 真要确认某个子命令是否存在，以
--help的实际输出为准，不以任何一份 Markdown 为准。
以上第 4 步的 grep 是按仓库中的文件路径组合的示例，未经实测，以你本地仓库的实际结构为准。
五、这件事的一般化写法
如果你自己的项目里也放了 AGENTS.md 或 SKILL.md，DeepTutor 这个案例能给的不是”文档要及时更新”这种废话，而是一条更具体的判据：把文档按”读错了谁来兜底”分档。
架构说明写偏，兜底的是读代码的人，他会顺着文件名点进去发现对不上；操作手册写偏，兜底的是一个会自动照做的程序，它没有”觉得不对劲”这一步。DeepTutor 把这两类内容分成了两个文件，这个划分本身是清楚的；而我们上面读出来的六处差异，恰好有一半落在那份会被自动读取的文件上。
至于该多久同步一次、要不要给这类文件加 CI 校验，仓库里没有给出通用做法，我们也不替它补。能确定的是：这个项目已经在做同类校验——发布流程里有一条工作流步骤会读 deeptutor/__version__.py 里的 __version__ 并与 git tag 比对，不一致就报错 “Bump __version__ before tagging.”（.github/workflows/pypi-release.yml:72-99）。版本号这一处对上了，文档里的命令与常量则各自为政。说完就停。
需要说明的边界：本文只读了 AGENTS.md 与 SKILL.md 的全文、README 中与这两份文件相关的段落，以及被引用到的那几处代码行；deeptutor_cli/ 全部未读，所以两份文档里列出的 CLI 子命令与选项，我们没有逐条与 Typer 定义核对过。上面提到的默认值与常量都是源码中的取值，不是运行结果的保证。文中所有 capability 与工具名只作结构说明，不涉及它们的教学设计是否有效——那类判断需要的证据本文一条都没有。
本文依据 DeepTutor 官方仓库（github.com/HKUDS/DeepTutor）的 README、AGENTS.md、
pyproject.toml 与 deeptutor/ 下的源码整理，核对日 2026-08-10，对应仓库快照 456f9c2（版本 1.5.11）。
本文内容为仓库源码与文档口径，我们没有安装、部署或运行过该项目，也没有调用过其中任何一个模型 API，
因此不涉及生成质量、响应速度与教学效果的任何描述。
参数与默认值随版本变动，请以仓库最新代码与 --help 的实际输出为准。
安全相关做法请结合自身环境评估，本文不构成安全方案建议。