Workflow & Core Tools · mattpocock/skills

teach

Name: teach
Author: mattpocock/skills

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

L2 Local · Restricted workspaceV1 Commit-PinnedWrite FileDual-pass Audit

Author mattpocockGitHub mattpocock/skills ↗Stars 253948License MITCommit 3cca18b368

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Pure prompt-orchestrated state machine: Transforms the current directory into a teaching workspace, persisting cross-session learning states using five categories of files (MISSION/RESOURCES/learning-records/lessons/NOTES + reference/assets) without any scripts or code.

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.

State resides not in model memory but in files, and cross-session continuation relies on re-reading these files—files serve as memory, which is the foundational reason this skill supports multi-session instruction.

Instructional difficulty is algorithmically determined by the Zone of Proximal Development (ZPD): Reads learning-records + mission to select the most relevant topic that is 'just challenging enough.'

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

This implements 'personalized curriculum scheduling based on past records'—translating pedagogical concepts into actionable retrieval rules.

Directly encodes cognitive science principles (storage vs. fluency strength, desirable difficulty, retrieval practice/spacing/interleaving) as curriculum design constraints to combat the illusion of mastery where users 'forget right after learning.'

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)

This operates at the pedagogical design layer, not the functional layer: prompt constraints govern lesson exercise formats and feedback loops ('feedback loop…as tight as possible'), requiring quiz answers to be of equal length to eliminate giveaway clues.

Externalizes knowledge acquisition: Prohibits reliance on parametric memory and mandates curating high-trust external resources upfront (annotated RESOURCES.md, categorized into Knowledge/Wisdom, explicit Gaps, ruthless pruning), with lessons 'heavily cited.'

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.

Rules in RESOURCES-FORMAT.md ('High-trust only', 'Annotate every entry', 'Surface gaps explicitly', 'Prune ruthlessly') turn resource curation into a sustainably maintained list—providing all citation anchors used in lessons.

Output discipline: Lessons are self-contained HTML (sequential numbering 0001-, Tufte-style layout, anchor interlinking, reusable assets components), reference docs serve as condensed quick-lookups, and glossary terminology is strictly enforced across the entire course.

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.

Deliverables are persistent instructional assets rather than ephemeral chat text; the cognitive insight that 'lessons are rarely revisited, whereas references are frequently revisited' drives the condensation of knowledge into reference documents.

Wisdom layer designed for community handoff: The model attempts an initial answer but defaults to delegating real-world verification to communities (forums/in-person classes), while respecting user opt-out preferences.

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.

Draws a clear capability boundary for the skill: teaching knowledge and practicing skills can be automated, but wisdom originates exclusively from real-world interactions.

2Core Capabilities

01Stateful multi-session teaching: Treats the current directory as a workspace, persisting mission/resources/learning-records/lessons/NOTES and resuming across sessions

02Generate self-contained HTML lessons: Sequential numbering, Tufte layout, bite-sized and quickly completable, HTML anchor cross-linking, optional CLI open

03ZPD personalized difficulty calibration: Selects the 'just challenging enough' next lesson based on learning-records + mission

04Retention-oriented curriculum design: Retrieval practice / spacing / interleaving + tight feedback loops + equal-length quiz options to prevent answer leakage

05High-trust external knowledge curation: RESOURCES.md with annotated groupings/explicit Gaps/ruthless pruning, heavily cited lessons, parametric memory prohibited

06Reference documentation + standardized glossary system: Enforces glossary consistency across the entire course once created

07Reusable component asset library: Prioritizes reusing shared stylesheets/quiz components, formalizing new requirements into components before referencing

08Learning record management (ADR-style): Records only when evidence of understanding exists, supporting superseded status and sequential number scanning

3External Dependencies

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

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Restrict working directory

For Administrators

Retain operation logs

Evidence & Triggers (File Paths & Excerpts)

本地工作目录: File read/write operations and artifact outputs: MISSION.md / RESOURCES.md / NOTES.md (workspace root)

Audit Notes: Pure prompt orchestration with zero executable code or scripts, performing only local read/write operations on the current workspace (instructional state files and HTML artifacts); no credential access, no outbound network requests, and no fixed endpoints; may execute local CLI commands to open lesson HTML files per 'If possible, open the lesson file for the user by running a CLI command' (a conditional, user-facing local action); instructional workflows guide the agent to query external high-trust resources and communities via the host environment's browsing tools under user initiation.

5Second-Pass Verification

[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 执行时可能出现双份或歧义（仅文档结构问题，无安全影响）

6Verdict & Scenarios

True multi-session instructional framework: Files serve as state; mission + learning-records enable every session to resume seamlessly and calibrate difficulty

Pedagogically sound: Storage/fluency strength, desirable difficulty, retrieval/spacing/interleaving, and tight feedback loops are baked into prompts, reinforced by actionable details like equal-length answers to prevent leakage

Anti-hallucination design: Prohibits parametric memory, enforces primary high-trust citations, and incorporates Gaps and pruning mechanisms in RESOURCES to mitigate knowledge fabrication risks

Deliverables are revisitable instructional assets (HTML lessons, quick reference cards, glossary, ADR-style records) with mandatory component reuse and terminological consistency

Restrained attack surface: Explicitly triggered by the user, zero scripts, no network requests, no credentials, maintaining a low security risk profile

Best for: Ideal for: Self-directed learners inside an agent workspace (such as Claude Code or Codex-style environments) who want to systematically study a topic, embrace 'archival learning' (producing HTML lessons, cheat sheets, and records), and return consistently across multiple sessions; exceptionally suited for knowledge-based (languages, theory, fitness, etc.) and lightweight skill-based topics.

Not for: Not suitable for: Users seeking only instant chat-based Q&A without directory artifacts; heavy hands-on skills requiring physical hardware or real-world practice environments (the skill only produces HTML exercises and guidance, incapable of replacing actual practice environments); certified domains like medicine or finance (human instructors and real-world communities should be consulted); one-off questioning scenarios without ongoing commitment.

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

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit 3cca18b368.