teach-skills
v1.0.0
Published
Adaptive Cognitive Mentorship & First-Principles Teaching MCP Server. Distilled from Matt Pocock's /teach, supercharged with Source Credibility Scoring, Production Edge-Case Traps, and Ebbinghaus Spaced Repetition.
Maintainers
Readme
🎓 teach-skills (teach-skills)
🌟 Why teach-skills?
Traditional LLM tutoring fails because of three fatal flaws:
- Parametric Amnesia: Knowledge resets between chat turns. There is no durable filesystem trace of your learning.
- Hallucination & Outdated Syntax: Models cite obsolete blog posts or invent fake APIs instead of canonical specifications.
- Cognitive Fatigue & Superficiality: Learners either get overwhelmed with walls of text (Cognitive Overload) or breeze through happy-path code without ever encountering sneaky production bugs (Concurrency race conditions, memory leaks, shallow copy mutations).
teach-skills transforms any MCP-compatible AI agent (Claude Desktop, Cursor, Antigravity, Windsurf, Roo Code, Goose) into a Principal Engineer & Autonomous Socratic Tutor.
# Run immediately via npx without manual installation
npx -y teach-skills🏗️ 1. Architecture & Workflow Diagram
flowchart TD
User([User Prompt: /teach Topic]) --> CheckWorkspace[1. teach_init_workspace]
subgraph Storage [Persistent Disk Workspace]
CheckWorkspace --> Mission[MISSION.md]
CheckWorkspace --> Resources[RESOURCES.md]
CheckWorkspace --> Profile[LEARNER_PROFILE.json]
CheckWorkspace --> Vault[HIDDEN_CASE_VAULT.json]
CheckWorkspace --> Lessons[lessons/*.html]
CheckWorkspace --> Records[learning-records/*.md]
end
subgraph Module2 [Module 2: Source Verifier]
CheckWorkspace --> VerifySource[2. teach_verify_source]
VerifySource --> SpecCheck{Domain Check}
SpecCheck -->|Tier 1: Canonical 90-100| ScoreTier1[Specs: IETF, W3C, Language Spec]
SpecCheck -->|Tier 2: High-Authority 75-89| ScoreTier2[BigTech Eng Blogs]
SpecCheck -->|Tier 3: Standard 50-74| ScoreTier3[Curated Tech Articles]
SpecCheck -->|Tier 4: Untrusted < 50| BlockSource[Blocked / Discarded]
ScoreTier1 & ScoreTier2 & ScoreTier3 --> GenBadge[Generate Markdown Credibility Badge]
end
subgraph Module1 [Module 1: Teach Core]
GenBadge --> GenLesson[3. teach_create_lesson]
GenLesson --> DeliverHTML[Interactive HTML in lessons/]
end
subgraph Module3 [Module 3: Hidden Case Trainer]
DeliverHTML --> GenTrap[4. teach_record_hidden_case]
GenTrap --> PresentTrap[Challenge: Present Production Edge-Case]
PresentTrap --> UserAnswer{User Solves Trap}
end
subgraph Module4 [Module 4: Cognitive Pacer]
UserAnswer --> PacerEval[5. teach_analyze_cognitive_load]
PacerEval --> LatencyCheck{Latency > 60s OR Error Streak >= 2?}
LatencyCheck -->|Yes: Overloaded| MicroMode[Mode: MICRO_LEARNING_SLOW]
LatencyCheck -->|No & Fast < 20s| AccelMode[Mode: ACCELERATED_CHALLENGE]
LatencyCheck -->|Balanced| NormalMode[Mode: BALANCED ZPD]
PacerEval --> SM2Schedule[Ebbinghaus Spaced Repetition 1d-3d-7d-21d]
end
SM2Schedule --> LogRecord[6. teach_log_learning_record]
LogRecord --> NextTurn([Ready for Next Lesson])🏛️ 2. Entity Relationship Diagram (ERD)
erDiagram
LEARNER_PROFILE ||--o{ LATENCY_SAMPLE : tracks
LEARNER_PROFILE ||--o{ SPACED_REPETITION_ITEM : schedules
WORKSPACE ||--|| MISSION : defines
WORKSPACE ||--o{ RESOURCE_ITEM : verifies
WORKSPACE ||--o{ LESSON : stores
WORKSPACE ||--o{ HIDDEN_CASE_ITEM : vaults
WORKSPACE ||--o{ LEARNING_RECORD : logs
LEARNER_PROFILE {
string userId
string topic
enum targetRole "Principal | Master"
float averageResponseLatencySeconds
int consecutiveErrorsCount
boolean isCognitiveOverloaded
enum recommendedPacing "MICRO_LEARNING_SLOW | BALANCED | ACCELERATED_CHALLENGE"
}
LATENCY_SAMPLE {
datetime timestamp
float latencySeconds
boolean isCorrect
string notes
}
SPACED_REPETITION_ITEM {
string id
string topicOrTrapId
string title
int repetitionLevel "0 (1d) | 1 (3d) | 2 (7d) | 3 (21d) | 4 (Mastered)"
int intervalDays
date lastReviewedAt
date nextReviewDate
}
RESOURCE_ITEM {
string url
string title
string domain
enum tier "Tier 1: Canonical | Tier 2: High-Authority | Tier 3: Standard | Tier 4: Untrusted"
int credibilityScore "0 - 100"
string architecturalNotes
date verifiedAt
}
HIDDEN_CASE_ITEM {
string id
string topic
string title
string underlyingMechanism
string amateurMistake
string principalSolution
int encounteredCount
int failedCount
boolean mastered
date lastTestedDate
}
LEARNING_RECORD {
string recordId
string topic
string title
string coreInsight
string amateurVsPrincipalDiff
string underlyingMechanism
datetime recordedAt
}📑 3. TypeScript Schema Definitions
export type TargetRole = "Principal" | "Master";
export type RecommendedPacing =
| "MICRO_LEARNING_SLOW"
| "BALANCED"
| "ACCELERATED_CHALLENGE";
export type ResourceTier =
| "Tier 1: Canonical"
| "Tier 2: High-Authority"
| "Tier 3: Standard"
| "Tier 4: Untrusted";
export interface LearnerProfile {
userId: string;
topic: string;
targetRole: TargetRole;
createdAt: string;
updatedAt: string;
cognitiveMetrics: {
averageResponseLatencySeconds: number;
consecutiveErrorsCount: number;
isCognitiveOverloaded: boolean;
recommendedPacing: RecommendedPacing;
recentSamples: Array<{
timestamp: string;
latencySeconds: number;
isCorrect: boolean;
notes?: string;
}>;
};
spacedRepetitionQueue: Array<{
id: string;
topicOrTrapId: string;
title: string;
repetitionLevel: number;
intervalDays: number;
lastReviewedAt: string;
nextReviewDate: string; // YYYY-MM-DD
}>;
}
export interface HiddenCaseItem {
id: string;
topic: string;
title: string;
underlyingMechanism: string; // e.g. Race condition, Memory leak, Heap shared mutation
amateurMistake: string;
principalSolution: string;
encounteredCount: number;
failedCount: number;
mastered: boolean;
lastTestedDate: string;
}🚀 Quickstart & MCP Client Setup
1. Claude Desktop
Add to claude_desktop_config.json:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"teach-skills": {
"command": "npx",
"args": ["-y", "teach-skills"]
}
}
}2. Cursor IDE
Add to .cursor/mcp.json or Global Cursor Settings:
{
"mcpServers": {
"teach-skills": {
"command": "npx",
"args": ["-y", "teach-skills"]
}
}
}3. Google Antigravity
Add to ~/.gemini/antigravity/mcp/teach-skills.json or workspace configuration:
{
"mcpServers": {
"teach-skills": {
"command": "npx",
"args": ["-y", "teach-skills"]
}
}
}4. Windsurf / Codeium
Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"teach-skills": {
"command": "npx",
"args": ["-y", "teach-skills"]
}
}
}5. VS Code (Roo Code / Cline)
In Roo Code or Cline MCP Settings:
{
"mcpServers": {
"teach-skills": {
"command": "npx",
"args": ["-y", "teach-skills"],
"disabled": false,
"autoApprove": []
}
}
}🛠️ MCP Tool Reference (8 Powerful Tools)
| Tool Name | Parameters | Purpose |
| :--- | :--- | :--- |
| teach_init_workspace | topic, targetRole?, workspacePath?, scopeIn?, scopeOut? | Initializes MISSION.md, RESOURCES.md, LEARNER_PROFILE.json, HIDDEN_CASE_VAULT.json, lessons/, and learning-records/ on disk. |
| teach_verify_source | url, title, subject, architecturalNotes?, manualScoreOverride? | Evaluates URL against the Tier 1-4 Matrix (0-100), outputs formatted credibility badge, and updates RESOURCES.md. |
| teach_create_lesson | lessonNumber, slug, title, coreFirstPrinciple, htmlContent | Generates a self-contained, responsive, dark-mode HTML lesson into ./lessons/. |
| teach_record_hidden_case | trapId, title, underlyingMechanism, amateurMistake, principalSolution, userFailed | Vaults sneaky production bugs, tracking fail streaks, encounter counts, and mastery status. |
| teach_get_hidden_cases | filter? ("all" | "failed" | "unmastered") | Queries traps to quiz the learner or conduct reviews. |
| teach_analyze_cognitive_load | responseLatencySeconds, isAnswerCorrect, topicOrTrapId?, itemTitle? | Tracks cognitive latency, detects burnout/overload, switches to Micro-learning mode, and calculates SM-2 spaced repetition dates. |
| teach_log_learning_record | recordId, topic, title, coreInsight, amateurVsPrincipalDiff, underlyingMechanism | Creates an ADR-style breakthrough record in ./learning-records/. |
| teach_get_workspace_summary | workspacePath? | Returns a consolidated health dashboard of the learner's journey. |
🧩 The 4 Core Pedagogical Modules
1. 🎓 Teach Core (teach)
- Stateful Learning Workspace: All learning is persisted in a local directory (
learning-workspace/) rather than fragile LLM context tokens. - Zone of Proximal Development (ZPD): Dynamically adjusts challenge difficulty so you're always stretched just enough without feeling overwhelmed.
- Permanent Artifacts: Generates standalone HTML lessons with First-Principles diagrams you can keep forever.
2. 🛡️ Source Verifier (source-verifier)
Filters out hallucinations and superficial tutorials through the Tiered Credibility Matrix:
- Tier 1: Canonical (90 - 100): Official language specifications, RFCs, MDN, ISO/IEEE, W3C (
ietf.org,w3.org,kotlinlang.org,python.org,rust-lang.org). - Tier 2: High-Authority (75 - 89): Big Tech engineering blogs, seminal textbooks (
netflixtechblog.com,cloud.google.com/blog,martinfowler.com). - Tier 3: Standard (50 - 74): Curated tech tutorials (Baeldung, LogRocket, DigitalOcean).
- Tier 4: Untrusted (< 50): Unverified forums, copycat spam sites (Strictly Blocked).
3. 🕳️ Hidden Case Trainer (hidden-case-trainer)
Software bugs in production don't come from syntax errors—they come from implicit assumptions:
- Concurrency & Deadlocks (Double-checked locking, race conditions)
- Memory Leaks & Retained Heap References
- Shallow Copy vs Deep Copy Mutation
- Boundary Traps & Off-by-one errors
Maintains HIDDEN_CASE_VAULT.json to systematically re-test your weak spots.
4. 🧠 Cognitive Pacer (cognitive-pacer)
Prevents cognitive exhaustion through dynamic pacing:
- Fast (< 20s) & Correct: Pushes deeper architectural challenges (
ACCELERATED_CHALLENGE). - Delayed (> 60s) or 2 Consecutive Mistakes: Detects Cognitive Overload. Immediately downshifts to
MICRO_LEARNING_SLOWmode (visual physical metaphors, 2-button multiple-choice questions). - Ebbinghaus Spaced Repetition: Automates interval review cycles (Day 1 ➔ Day 3 ➔ Day 7 ➔ Day 21).
🇻🇳 Hướng Dẫn Chi Tiết Bằng Tiếng Việt (Vietnamese Guide)
Triết lý hoạt động
teach-skills là hệ thống MCP Server đầu tiên biến AI thành một Huấn Luyện Viên Cá Nhân (Cognitive AI Tutor) dựa trên phương pháp của Matt Pocock (AI Hero):
- Lưu trữ trạng thái thực trên đĩa (Stateful Workspace): Không sợ AI bị quên kiến thức khi chuyển tab hay mở chat mới. Mọi tiến trình được lưu vào thư mục
learning-workspace/. - Nguyên lý đầu tiên (First-Principles): Luôn bắt đầu từ tầng vật lý, RAM, OS primitives, bộ nhớ Heap/Stack trước khi học cú pháp.
- Rèn luyện bẫy ẩn thực chiến (Hidden Cases): Huấn luyện phản xạ với các lỗi sản phẩm tinh vi nhất (Race condition, Deadlock, Memory Leak, Shallow Copy).
- Chống quá tải nhận thức (Cognitive Overload Protection): Tự động đo độ trễ suy nghĩ của bạn để giảm tải kịp thời, kết hợp thuật toán lặp lại cách quãng Ebbinghaus (Spaced Repetition).
Cách sử dụng ngay:
Trong giao diện Claude Desktop, Cursor, Antigravity hoặc Roo Code:
/teach Kotlin Memory Model
/teach Rust Concurrency & Lifetimes
/teach PostgreSQL Indexing & LockingAgent sẽ tự động gọi các tool MCP để tạo bài học, kiểm định tài liệu gốc, thử thách phản xạ và lưu trữ nhật ký học tập cho bạn.
👥 Contributing & Community
Contributions, bug reports, and suggestions are welcome!
- GitHub: https://github.com/nhatan2003nticoud/teach-skills
- License: MIT License. Free for personal and commercial usage.
