{"id":"6c887d2f-6d1d-4573-a2c1-771f7bcc5da4","slug":"ai-technical-classroom","kind":"skill","name":"ai-technical-classroom","summary":"An evidence-gated, multi-role AI technical classroom skill that turns papers, code, and engineering topics into auditable learning archives and publishable offline HTML reports.","owner":"HowieYin","repoUrl":"https://github.com/HowieYin/ai-technical-classroom","license":"MIT","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-10-08T08:21:52.000Z","addedAt":"2026-10-21T23:59:56.672Z","logoUrl":"https://avatars.githubusercontent.com/u/160447654?u=619d94c419095f4ddd7afcdd36d8b7fb0f9160f0&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["browser-web","developer-tools"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-22T00:45:25.595Z","sample":false,"url":"https://conduits.dev/tools/ai-technical-classroom","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# AI Technical Classroom\n\n[![Language: English](https://img.shields.io/badge/Language-English-1f6feb)](README.md)\n[![语言：简体中文](https://img.shields.io/badge/%E8%AF%AD%E8%A8%80-%E7%AE%80%E4%BD%93%E4%B8%AD%E6%96%87-dc4a22)](README.zh-CN.md)\n\n> A portable **Agent Skill** for turning a technical topic, research paper, codebase, URL, local artifact, or engineering question into an evidence-grounded learning archive and a publication-quality, offline HTML technical report.\n\n`ai-technical-classroom` is not a chatbot, a hosted service, or an LLM SDK. It is a **`SKILL.md`-based workflow package**: install it into a capable coding agent (Claude Code, Codex, TraeX, or another agent runtime that loads Agent Skills), then ask that agent to run a technical course. The agent supplies the model, tool use, file access, browser/research ability, and—in strict timed mode—a durable runner.\n\n## Why This Exists\n\nMost “summarize this paper” workflows produce a thin overview, leak unsupported claims, or stop at an attractive web page. This Skill enforces a deeper technical loop:\n\n```text\ndirect material\n      ↓\npaper-first research and evidence map\n      ↓\nAlex / Bob technical teaching and adversarial mastery checks\n      ↓\nreader-facing article + mechanism-specific interactive component\n      ↓\nAlex / Leo / Alice reviews + Nora timing audit\n      ↓\noffline HTML report + reproducibility / submission package\n```\n\nIt is designed for AI, ML systems, hardware, mathematics, software architecture, and similar technical subjects where primary sources, equations, source code, experiments, figures, trade-offs, and failure modes matter.\n\n## What You Get\n\n| Capability | What it enforces |\n| --- | --- |\n| Five-role workflow | Alex Tensor teaches and fact-checks; Bob Prompt learns and writes; Leo performs paper-style technical review; Alice reviews HTML/accessibility; Nora records and audits timing. |\n| Paper-first research | Direct user material first; then primary papers, official implementations, official docs, and reproducible evidence. |\n| Technical depth | Mechanism, variables/shapes/units, numerical examples, implementation/data flow, complexity, alternatives, and failure modes. |\n| Publishable HTML | A reader-facing offline `report.html`, not a transcript or classroom homework page. |\n| Meaningful interaction | At least one separate `components/*.html` tool that teaches a real mechanism through an adjustable technical variable. |\n| Review gate | Two substantive review/revision/verification rounds for Alex, Leo, and Alice. |\n| Evidence gate | Optional PID-backed active-time accounting, checkpoints, and Nora's eligibility verdict. |\n| Research package | Editable-paper, code, data, results, venue, mock-review, revision, integrity, and A/B/C verdict scaffolding. |\n\n## When to Use It\n\nUse this Skill when you want an agent to:\n\n- deeply read and teach a paper, survey a field, or explain an implementation;\n- transform a local repository, debugging artifact, or system design into a durable technical article;\n- create a self-contained HTML report with source figures/tables and a mechanism-specific interactive explainer;\n- create an audit trail for research, classroom dialogue, technical review, and reproducibility boundaries;\n- distinguish a quick research draft from a genuinely timed, evidence-gated autonomous course.\n\nDo **not** use it for a one-paragraph summary, ordinary prose editing, generic marketing pages, or a claim of experimental evidence that you cannot reproduce or source.\n\n## Requirements\n\n### Required\n\n- An agent runtime that can load a directory containing `SKILL.md`.\n- A model capable of technical reasoning and tool use.\n- Read/write access to a workspace.\n- Python **3.10+** for the bundled helpers. They use only the standard library.\n\n### Strongly Recommended\n\n- Web or browser tools for accessing primary sources and official documentation.\n- A browser or HTML renderer for desktop and narrow-screen review.\n- A persistent agent runner if you want the strict, timed-course qualification.\n\n### Important: Skill vs. Model/API\n\nThis repository does **not** send requests to an LLM by itself and it never stores an API key. Your **agent host** owns LLM configuration:\n\n```text\nAgent host configuration  →  model / API key / endpoint / tools\nai-technical-classroom    →  research, course, review, and deliverable workflow\nyour workspace            →  course-records/<date>-<topic>/\n```\n\nThe Skill remains useful with a local model, a direct provider API, an OpenAI-compatible gateway, or an Anthropic-compatible gateway—as long as the chosen agent runtime can use that model and call local tools.\n\n## Installation\n\nClone once, then install the repository root—the directory containing `SKILL.md`—into your agent's Skill search path.\n\n```sh\ngit clone https://github.com/HowieYin/ai-technical-classroom.git\n```\n\nThe exact discovery path is host-specific. Common layouts are below; check your installed agent version if it uses a different configured Skills directory.\n\n### Claude Code\n\nInstall for one user:\n\n```sh\nmkdir -p ~/.claude/skills\ngit clone https://github.com/HowieYin/ai-technical-classroom.git \\\n  ~/.claude/skills/ai-technical-classroom\n```\n\nOr make it repository-local so a team can version the workflow with the project:\n\n```sh\nmkdir -p .claude/skills\ngit clone https://github.com/HowieYin/ai-technical-classroom.git \\\n  .claude/skills/ai-technical-classroom\n```\n\nRestart Claude Code or start a new session after installation. Invoke it explicitly with `$ai-technical-classroom`, or describe a task that matches the Skill metadata.\n\n### Codex CLI / Codex Agents\n\nInstall for one user:\n\n```sh\nmkdir -p ~/.codex/skills\ngit clone https://github.com/HowieYin/ai-technical-classroom.git \\\n  ~/.codex/skills/ai-technical-classroom\n```\n\nFor a project-local setup:\n\n```sh\nmkdir -p .codex/skills\ngit clone https://github.com/HowieYin/ai-technical-classroom.git \\\n  .codex/skills/ai-technical-classroom\n```\n\nStart a fresh Codex session and invoke:\n\n```text\nUse $ai-technical-classroom to teach and write a technical report about ...\n```\n\n### TraeX / TRAE CLI\n\nInstall globally:\n\n```sh\nmkdir -p \"${TRAE_HOME:-$HOME/.trae}/skills\"\ngit clone https://github.com/HowieYin/ai-technical-classroom.git \\\n  \"${TRAE_HOME:-$HOME/.trae}/skills/ai-technical-classroom\"\n```\n\nOr install it only for the current workspace:\n\n```sh\nmkdir -p .trae/skills\ngit clone https://github.com/HowieYin/ai-technical-classroom.git \\\n  .trae/skills/ai-technical-classroom\n```\n\nOpen a fresh session, then use `$ai-technical-classroom`.\n\n### Other Agent Runtimes\n\nUse any runtime that supports the open `SKILL.md` convention:\n\n1. Place this repository root in its configured Skill directory.\n2. Ensure the runtime can read the Skill directory and execute `python3`.\n3. Start a new agent session so it rescans Skills.\n4. Ask the agent to use `ai-technical-classroom`, explicitly naming the Skill if implicit discovery is unavailable.\n\nIf your runtime does not natively support Skills, attach the contents of `SKILL.md` to its system/developer instructions and keep `references/` and `scripts/` accessible at their relative paths.\n\n## Configure the LLM/API in the Agent Host\n\nDo this in the **host**, not in this repository. Never commit an API key to a Skill repository, `SKILL.md`, course archive, or `manifest.md`.\n\n### Claude Code\n\nAuthenticate or configure your Claude Code provider using its normal login/API-key mechanism, then launch Claude Code from a shell where the provider credential is available:\n\n```sh\nexport ANTHROPIC_API_KEY=\"replace-with-your-secret\"\nclaude\n```\n\nIf you use an Anthropic-compatible proxy or enterprise gateway, follow that gateway's Claude Code configuration requirements and keep its URL/key in environment variables or the host's private configuration—not in this repository.\n\n### Codex / OpenAI-Compatible Hosts\n\nFor a direct OpenAI-compatible host, the common pattern is:\n\n```sh\nexport OPENAI_API_KEY=\"replace-with-your-secret\"\n# Optional only if your host/provider documents a compatible endpoint:\nexport OPENAI_BASE_URL=\"https://your-gateway.example/v1\"\n```\n\nThen configure the host's selected model/provider according to its documentation. Different Codex distributions and versions use different configuration files and provider names, so this repository intentionally does not hard-code a potentially stale config snippet.\n\n### Generic Agent Host\n\nUse this secure pattern:\n\n```sh\nexport PROVIDER_API_KEY=\"replace-with-your-secret\"\nexport PROVIDER_BASE_URL=\"https://provider.example/v1\"  # if required\nagent-cli --model \"provider-model-name\"\n```\n\nVerify four things before a long course:\n\n1. the agent can make one successful model call;\n2. the agent has file-write permission in the target workspace;\n3. browser/research tools are available if the topic needs external sources;\n4. a durable runner exists if you need verified active-time completion.\n\n## Invoke the Skill\n\nExplicit invocation is the most portable option:\n\n```text\nUse $ai-technical-classroom to turn [topic / paper / URL / repository / log] into a rigorous technical course and offline HTML report.\n```\n\nGive the agent a clear topic and optional scope. The human is the **course owner**, not the simulated student: do not answer Alex/Bob questions or approve individual stages.\n\n### Prompt: Paper Deep Read\n\n```text\nUse $ai-technical-classroom.\n\nTopic: FlashAttention and the IO-aware view of exact attention.\nDirect source: https://arxiv.org/abs/2205.14135\nScope: derive the IO model, explain the tiled forward algorithm, compare the\nmemory/computation trade-off with standard attention, and create an interactive\ntile-size / memory-traffic explainer. Deliver an offline English HTML report.\n```\n\n### Prompt: Code / Systems Analysis\n\n```text\nUse $ai-technical-classroom.\n\nTopic: Explain the scheduler and KV-cache lifecycle in this repository.\nDirect material: ./path/to/repository\nScope: trace the real request path, identify data ownership and state\ntransitions, compare prefill and decode behavior, and write an offline HTML\narchitecture report with an interactive timeline. Do not invent benchmarks.\n```\n\n### Prompt: Untimed Draft\n\n```text\nUse $ai-technical-classroom to create an untimed, evidence-grounded research\nand HTML draft about speculative decoding. Do not claim the 30m+30m+2h+1h\ntimed-course qualification unless a persistent runner is actually available.\n```\n\n## End-to-End Example\n\nThis example shows the **agent-facing** workflow and the optional command-line helpers. The agent should normally run these steps; you do not have to manually simulate the five roles.\n\n### 1. Initialize an Archive\n\n```sh\ngit clone https://github.com/HowieYin/ai-technical-classroom.git\ncd ai-technical-classroom\n\npython3 scripts/init_course.py \\\n  --output ~/technical-courses \\\n  --topic \"FlashAttention IO model\" \\\n  --source \"https://arxiv.org/abs/2205.14135\"\n```\n\nThe command prints a new directory like:\n\n```text\n~/technical-courses/course-records/2026-10-08-flashattention-io-model\n```\n\nIt includes source maps, plans, review tables, a report target, a component directory, timer files, and a submission-package scaffold.\n\n### 2. Ask the Agent to Run It\n\n```text\nUse $ai-technical-classroom and work in\n~/technical-courses/course-records/2026-10-08-flashattention-io-model.\n\nRead the direct source first. Complete the research map and paper lineage,\nthen conduct the course autonomously. Keep the classroom record internal;\nwrite a reader-facing report.html and a standalone components/io-tile-explorer.html.\n```\n\n### 3. Optional: Attach a Durable Runner to the Timer\n\nOnly use this when your runtime has a genuinely persistent, content-producing runner. Assume its PID is `${RUNNER_PID}` and it is still alive:\n\n```sh\nCOURSE=~/technical-courses/course-records/2026-10-08-flashattention-io-model\n\npython3 scripts/course_timer.py init \"$COURSE\"\npython3 scripts/course_timer.py start-session \"$COURSE\" \"$RUNNER_PID\" \"alex-preparation\"\n# The runner writes substantive material to $COURSE/alex-preparation.md.\npython3 scripts/course_timer.py end-session \"$COURSE\" \"Alex prepared source map\"\npython3 scripts/course_timer.py checkpoint \"$COURSE\" alex_preparation \\\n  source-map alex-preparation.md \"Primary sources and teaching path recorded\"\n```\n\nRepeat the live-session/checkpoint pattern for the remaining gates. The timer intentionally rejects skipped phases, dead PIDs, insufficient active time, and missing evidence. It is an integrity mechanism, not a stopwatch to leave running.\n\n### 4. Validate Before Delivery\n\nAfter all artifacts, reviews, and timing evidence are complete:\n\n```sh\npython3 scripts/validate_delivery.py \\\n  ~/technical-courses/course-records/2026-10-08-flashattention-io-model\n```\n\nThe validator checks for:\n\n- the full course and submission-package inventory;\n- a valid completed timer plus Nora's `eligible` verdict;\n- semantic HTML, source/reference content, no internal classroom leakage, and at least one standalone interaction;\n- accessible native controls and reduced-motion handling;\n- two recorded review rounds for Alex, Leo, and Alice;\n- one explicit A/B/C submission verdict.\n\n## Course Output\n\n```text\ncourse-records/YYYY-MM-DD-topic/\n├── preparation-brief.md       # scope, direct materials, and role boundary\n├── research.md                # evidence map and source status\n├── papers.md                  # lineage and source-figure plan\n├── alex-preparation.md        # internal preparation record\n├── bob-preparation.md         # independent learner preparation\n├── transcript.md              # internal technical dialogue\n├── nora-log.md                # internal chronological audit record\n├── mastery.md                 # internal recall/transfer evidence\n├── report.html                # public, offline technical article\n├── components/\n│   └── *.html                 # standalone technical interactions\n├── reviews.md                 # issue → change → verification record\n├── manifest.md                # artifact and validation inventory\n├── timer.state / timer.log    # active-session timing evidence\n└── submission-package/        # editable source, code, data, results, review, verdict\n```\n\n## Strict Timed Course vs. Untimed Draft\n\n| Mode | What is allowed | What you may claim |\n| --- | --- | --- |\n| Untimed draft | Research, instruction, HTML, review, components, and submission scaffolding without a persistent runner. | “Evidence-grounded draft” or “untimed course draft.” |\n| Timed course | Valid live runner sessions, evidence-file growth, all phase durations/checkpoints, timer completion, and Nora eligibility. | The full 30m + 30m + 2h + 1h evidence-gated course. |\n\nDo not use sleep, idle wall time, a terminated CLI/model turn, fabricated transcript timestamps, or human follow-up messages to satisfy timing gates.\n\n## Repository Layout\n\n```text\nSKILL.md                       The machine-facing Skill entry point\nREADME.md                      This human-facing guide\nagents/openai.yaml             Optional UI metadata for compatible hosts\nreferences/course-protocol.md  Portable course, artifact, and review contract\nscripts/init_course.py         Create a course archive and submission scaffold\nscripts/course_timer.py        Enforce PID-backed active-time and checkpoint gates\nscripts/validate_delivery.py   Validate the finished archive\n```\n\n## Security and Research Integrity\n\n- Never commit API keys, session tokens, proprietary source code, private papers, or sensitive course records.\n- Use direct/primary sources before secondary explanations.\n- Attribute figures, tables, experiments, and claims; do not fabricate source material or quantitative results.\n- A/B/C is a readiness verdict, not a claim that a paper has been accepted.\n- Review output before publishing it: the Skill supports rigorous work but cannot make an unsupported claim true.\n\n## Contributing\n\nContributions are welcome when they improve portability, source-grounded rigor, HTML accessibility, or deterministic validation. Keep changes runner-agnostic, avoid bundling credentials or private content, and add tests/smoke checks for helper-script changes.\n\n## License\n\n[MIT](LICENSE).\n"}