基础工具与工作流 · mattpocock/skills

teach

Teach the user a new skill or concept, within this workspace.

L2 本地 · 限定工作目录V1 已固定读写文件Dual-pass Audit
Author mattpocockGitHub mattpocock/skills ↗Stars 253948License MITCommit 3cca18b368
管控等级描述 skill 的能力与建议配套的管控措施,不代表质量或安全认证,也不表示可用或不可用。是否使用由用户和管理者决定。不同 agent 宿主对权限的约束各不相同,请勿假定宿主一定会提供安全兜底。第三方 skill 版权归原作者,使用风险由使用者自行承担。

1实现原理 · 为什么它能做到

纯 prompt 编排的状态机:把当前目录变成教学工作区,用五类文件(MISSION/RESOURCES/learning-records/lessons/NOTES + reference/assets)持久化跨会话学习状态,无任何脚本或代码。

SKILL.md
Treat the current directory as a teaching workspace. The state of their learning is captured in this directory in several files: - `MISSION.md`: A document capturing the _reason_ the user is interested in the topic. This should be used to ground all teaching. … - `./learning-records/*.md`: A directory of learning records, which capture what the user has learned. These are loosely equivalent to architectural decision records… These should be used to calculate the zone of proximal development.
「状态」不在记忆里而在文件里,跨会话靠重读这些文件续接——文件即记忆,这是该 skill 能支撑 multi-session 教学的根因。

教学难度由 ZPD(最近发展区)算法化决定:读 learning-records + mission,选出最相关且'刚好够挑战'的课题。

SKILL.md
If they don't, figure out their zone of proximal development by: - Reading their `learning-records` - Figuring out the right thing to teach them based on their mission - Teach the most relevant thing that fits in their zone of proximal development
这里在做'基于既往记录的个性化课程调度'——把教育学概念转成可执行的检索规则。

把认知科学(storage vs fluency strength、desirable difficulty、retrieval practice/spacing/interleaving)直接编码为课程设计约束,对抗'学了就忘'的假掌握。

SKILL.md
**Fluency strength**: in-the-moment retrieval of knowledge… **Storage strength**: long-term retention of knowledge. Fluency can give the user an illusory sense of mastery, but storage strength is the real goal. Try to design lessons which build long-term retention by desirable difficulty: - Using retrieval practice (recall from memory) - Spacing (distributing practice over time) - Interleaving (mixing up different but related topics in practice - for skills practice only)
这是教学法层设计,不是功能层:通过 prompt 约束 lesson 的练习形态与反馈环('feedback loop…as tight as possible'),quiz 答案被要求等长以杜绝泄题线索。

知识获取外置化:禁止依赖参数记忆,要求先策展高信任外部资源(RESOURCES.md 带注解、分组 Knowledge/Wisdom、显式 Gaps、无情修剪),lesson 内'布满引用'。

SKILL.md
Before the `RESOURCES.md` is well-populated, your focus should be to find high-quality resources which will help the user acquire knowledge. Never trust your parametric knowledge.
RESOURCES-FORMAT.md 的规则('High-trust only'、'Annotate every entry'、'Surface gaps explicitly'、'Prune ruthlessly')把资源策展变成可持续维护的清单——lesson 的引用锚点都来自这里。

输出纪律:lesson 为自包含 HTML(递增编号 0001-、Tufte 级排版、锚点互链、复用 assets 组件),reference 文档做压缩速查,glossary 术语全课程强制一致。

SKILL.md
Each lesson is one self-contained HTML file, saved to `./lessons/` and titled `0001-<dash-case-name>.html` where the number increments each time. A lesson should be **beautiful**, with clean, readable typography and layout, since the user will return to these later to review. Think Tufte.
产物是持久化教学资产而非一次性聊天文本;'lesson 少被回看、reference 常被回看'的认知决定了知识压缩进 reference 文档。

Wisdom 层设计为社区分流:模型先尝试回答,但默认把真实验证交给社区(论坛/线下班),并尊重用户退出偏好。

SKILL.md
When the user asks a question that appears to require wisdom, your default posture should be to attempt to answer - but to ultimately delegate to a **community**. A community is a place (online or offline) where the user can test their skills in the real world.
为 skill 划清了能力边界:教知识/练技能可以自动化,智慧只能来自真实互动。

2核心能力

01有状态多会话教学:以当前目录为工作区,持久化 mission/resources/learning-records/lessons/NOTES 并跨会话续接
02生成自包含 HTML lesson:递增编号、Tufte 排版、短小可速完成、HTML 锚点互链、可选 CLI 打开
03ZPD 个性化难度校准:据 learning-records + mission 挑选'刚好够挑战'的下一课
04抗遗忘课程设计:retrieval practice / spacing / interleaving + 紧反馈环 + 等长 quiz 答案防泄题
05高信任外部知识策展:RESOURCES.md 注解分组/显式 Gaps/无情修剪,lesson 布满引用,禁参数记忆
06参考文档 + 规范词汇表系统:glossary 一经创建全课程强制遵守
07可复用组件资产库:共享样式表/quiz 组件优先复用,新需求先沉淀为组件再引用
08学习记录管理(ADR 式):仅在有理解证据时记录、支持 superseded 状态与编号扫描递增

3外部依赖

KindDependency / Endpoint
cli本地文件打开命令(具体二进制未指定,如 open/xdg-open 类)
network教学流程引导 agent 检索外部高信任资源/社区作为知识输入(宿主浏览工具行为,skill 内无固定端点、无代码调用)

4管控建议与判定依据

建议配套管控措施
面向 Agent
限定工作目录
面向管理者
保留操作记录
判定依据(文件路径与关键语句摘要)
  • 本地工作目录: 文件读写与工件输出: MISSION.md / RESOURCES.md / NOTES.md(工作区根)
审计说明: 。纯 prompt 编排、零可执行代码/脚本,仅对当前工作区做本地读写(教学状态文件与 HTML 产物);无凭证读取、无网络外发、无固定网络端点;可能按 'If possible, open the lesson file for the user by running a CLI command.' 调用本地 CLI 打开 lesson HTML(有条件的、面向用户的本地动作);教学流程会引导 agent 检索外部高信任资源/社区,属宿主浏览工具在用户发起下的行为。

5第二遍独立确认

  • [ok] 外部 CLI:'open the lesson file … by running a CLI command' — SKILL.md Lessons 段实存(行 55),且为条件式 'If possible',未指定具体二进制
  • [ok] 无隐藏脚本/可执行代码 — 目录仅 SKILL.md、4 个 FORMAT.md、agents/openai.yaml;glob 枚举无遗漏
  • [ok] 无网络外发/固定端点/凭证读取 — 全目录 grep 无 curl/wget/fetch/api_key/token/env/secret;唯一 URL 是 RESOURCES-FORMAT.md 模板中的 example.com / reddit.com 示例
  • [ok] 仅用户显式触发 — SKILL.md frontmatter disable-model-invocation: true 与 agents/openai.yaml policy.allow_implicit_invocation: false 双端一致
  • [ok] 实现原理与功能声明相符 — description 言 'Teach the user a new skill or concept, within this workspace'——实际能力即 prompt 状态机 + 文件产物,无夸大;skill 自身不含检索/教学引擎,依赖宿主模型能力
  • [discrepancy] GLOSSARY 文件归属一致性 — SKILL.md 工作区清单把 glossaries 归入 ./reference/*.html;GLOSSARY-FORMAT.md 则定义根级 'GLOSSARY.md is the canonical language for this teaching workspace',且 LEARNING-RECORD/RESOURCES FORMAT 以 [[GLOSSARY.md]]/[[MISSION.md]] wiki 链接引用——glossary 究竟存为 reference HTML 还是根 GLOSSARY.md 未对齐,agent 执行时可能出现双份或歧义(仅文档结构问题,无安全影响)

6结论

  • 真·多会话教学框架:文件即状态,mission + learning-records 让每次会话都能续接并校准难度
  • 教学法有据:storage/fluency strength、desirable difficulty、retrieval/spacing/interleaving、紧反馈环均写入 prompt,且用等长答案防泄题这类可执行细节落地
  • 反'模型瞎教'设计:禁参数记忆、强制高信任主源引用、RESOURCES 带 Gaps 与修剪机制,降低编造知识风险
  • 产物为可回看的教学资产(HTML 课程/速查卡/glossary/ADR 式记录),并强制组件复用与术语一致
  • 攻击面克制:用户显式触发、无脚本无网络无凭证,安全档位低
  • 适合: 适合:在 agent 工作区(Claude Code/Codex 类)想系统学一个主题、愿意接受'档案化学习'(留下 HTML 课程/速查卡/记录)并能跨多会话持续回来的自驱学习者;知识型(语言/理论/健身等)与轻技能型主题尤其匹配。
    不适合: 不适合:只要即时聊天式解答、不想要目录文件的人;依赖真实设备/环境演练的重技能(skill 只产出 HTML 练习与指引,无法替代实操环境);医疗/财务等需专业认证的领域(应找人类教师与真实社区);无持续投入意愿的'一次性提问'场景。
    Install Agent-Ready
    ① Verified Mirror 2026-09-06
    Option A · Direct DownloadDownload teach.tar.gz
    sha256: 372546b23d29f964…
    Option B · Copy Guide for Agent
    install.json
    agent 读 JSON 指南后会自动从本站下载安装,无需更多说明。
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit 3cca18b368.