npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

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.

Readme

🎓 teach-skills (teach-skills)


🌟 Why teach-skills?

Traditional LLM tutoring fails because of three fatal flaws:

  1. Parametric Amnesia: Knowledge resets between chat turns. There is no durable filesystem trace of your learning.
  2. Hallucination & Outdated Syntax: Models cite obsolete blog posts or invent fake APIs instead of canonical specifications.
  3. 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_SLOW mode (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):

  1. 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/.
  2. 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.
  3. 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).
  4. 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 & Locking

Agent 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!