| name | learning-tech |
|---|---|
| description | Use when the user asks for systematic technical understanding of a technology, algorithm, framework, paper, long technical conversation, or engineering system. Do not use for debugging, deployment, code review, simple API lookup, pure summarization, or prose editing unless the user explicitly wants a learning artifact. |
Build systematic technical understanding for the user. The output is a pure Markdown engineering learning report or explanation, not a news summary, marketing overview, slide deck, PDF, or casual article rewrite.
The primary high-value scenario is turning a long technical conversation into a durable learning report. In that case, the conversation is not raw text to summarize; it is evidence of the user's learning path, blockers, wrong mental models, corrections, and final understanding.
Do not use this skill when the goal is action, repair, or light lookup rather than systematic understanding:
- Direct deployment, installation, environment setup, or command execution.
- Debugging an error, fixing broken code, or diagnosing runtime behavior.
- Code review, security review, refactoring, or implementation planning.
- Simple API usage lookup, syntax examples, or one-off factual answers.
- Pure article editing, copy polishing, or style rewriting without technical learning design.
- Summarizing a paper, webpage, video, or document when the user only wants a digest.
- News, market, funding, social response, company background, or biography research.
If the request is mixed, use this skill only for the learning artifact portion and route operational work to the more specific skill or tool.
When a request is out of scope, make the routing decision internally and answer the user's actual request directly. Do not mention that this skill was triggered, not triggered, routed out, or considered out of scope in the final user-facing artifact.
Organize concepts into one coherent knowledge system. Never mirror the order of a paper, webpage, repository, transcript, or source material unless that order also matches the learner's dependency path. Choose chapter structure by logical prerequisites, mechanism construction, and engineering consequences.
Do not list concepts as isolated facts. Each concept should serve one of three roles:
| Role | Meaning |
|---|---|
| Prerequisite | Needed before the core mechanism makes sense |
| Mechanism component | Part of how the target system works |
| Engineering consequence | Why the mechanism matters in practice |
When the user provides a prior conversation, notes, screenshots, a report draft, or other local material, inspect it before deciding structure. Extract the learning contract: user background, repeated blockers, misconceptions, concepts already mastered, source materials, desired output shape, and any report the user already approved.
Use references/conversation-to-learning-contract.md for long-dialogue distillation and for converting repeated questions into a coherent report spine.
Anchor the topic in a precise positioning statement: what it is, what problem it solves, where it sits in the system, and which nearby ideas it is often confused with.
Use references/grill-and-user-model.md to infer the user's background and prerequisite gaps before writing.
If a prerequisite blocks the core mechanism, explain it before the section that needs it. Do not hide blocking prerequisites in an appendix or later reading list.
Explain from first principles. For important concepts, preserve the four-layer teaching pattern when useful:
| Layer | Question |
|---|---|
| Intuition | What mental model helps without distorting the idea? |
| Technical | How does it work under the hood? |
| Engineering | Why does it matter in a real system? |
| Misconception | What wrong model would derail understanding? |
Use one recurring example when it reduces cognitive load. Adapt the example to the topic. For mechanisms with meaningful intermediate states, include a trace that shows initial state, inputs, internal state, decision rule, failure path, and engineering consequence.
Verify current technical claims against primary sources where possible: official repos, papers, model cards, official docs, release notes, and implementation code. Use provider blogs and community posts only as supporting context.
Keep provenance discipline internal by default. The final report should use cautious wording and normal references, not visible credibility grades or source-confidence tiers, unless the user explicitly asks for an audit-style source table.
Use references/source-provenance.md for source tracing rules.
Grill is not only a beginning-of-task gate. Ask the user whenever uncertainty affects the task goal, report depth, scope, analogy style, prerequisite coverage, or final output quality.
Use one focused question at a time, with a recommended default. If the request already gives enough context, proceed without asking.
Use references/grill-and-user-model.md for continuous grill rules, prerequisite mapping, and personalized analogy choices.
Deliver a pure Markdown artifact organized around the reader's cognitive path, not paper section order, webpage order, repository order, or transcript order. Prefer precise prose, process-oriented examples, source-grounded claims, and section focus statements when they help orientation.
Before final delivery, run the internal novice pass from references/report-quality.md. Never expose novice-pass notes in the final report.
Read only the needed reference file:
| Need | Reference |
|---|---|
| Long conversation, approved prior report, user blocker extraction, report spine from learning path | references/conversation-to-learning-contract.md |
| User background, prerequisite gaps, continuous grill, analogy preference | references/grill-and-user-model.md |
| Report quality, process examples, embedded surprise points, section focus, style, pure Markdown | references/report-quality.md |
| Internal source provenance, verification pressure, reference handling | references/source-provenance.md |
This skill must remain usable in OpenCode, Claude Code, and Codex. Tool names differ, so follow capabilities rather than hardcoded tool names. Do not write instructions that require one platform's proprietary tool to exist.
| Capability | Use the active platform's equivalent |
|---|---|
| Search external sources | Web search, docs search, librarian/research subagent, or MCP documentation tools |
| Fetch source material | Web fetch, browser fetch, repository read, PDF/document extraction, or official docs tooling |
| Inspect local material | File read, grep/search, directory listing, or structural code search |
| Compare implementation patterns | Explore/codebase subagent or direct grep/read when the scope is small |
| Grill/alignment | Ask one normal chat question at a time, or use a question/grilling tool if available |
| Verify saved artifacts | File metadata, Markdown/JSON parsing, link/source checks, or user-visible output review |
| Run skill evals | Any available subagent runner, CLI harness, scripted comparison, or manual before/after review |
Do not fail because a named tool is unavailable. Substitute the closest available capability and keep the same learning workflow.
For cross-platform skill writing:
- Name capabilities, not tools: say "inspect local material" instead of "use Read".
- Treat subagents, MCP tools, browser tools, and web fetchers as optional accelerators.
- Keep reference paths relative to this skill directory so OpenCode, Claude Code, and Codex can resolve them after installation.
- Avoid platform-specific output formats, hidden state, or UI assumptions.
- No HTML, DOCX, PDF, slides, image assets, or interactive artifacts unless explicitly requested.
- No internal workflow, routing, skill-trigger, novice-pass, or self-audit notes in the final artifact.
- No social impact, funding, personnel bios, media reception, or business gossip.
- No unsupported performance rankings or benchmark claims without model, hardware, context, sampling, and baseline conditions.
- No empty hype words: revolutionary, game-changing, disruptive, groundbreaking.
- No defaulting to "simple trick" explanations. Explain the engineering difficulty honestly.