Skip to content

README.md

Latest commit

 

History

History
254 lines (191 loc) · 8.67 KB

README.md

File metadata and controls

254 lines (191 loc) · 8.67 KB

tech-skill-builder

A Claude Code plugin for creating and delivering hands-on technical courses.

Built on proven pedagogical frameworks:

  • 4C/ID Model — whole-task learning with progressive complexity
  • Bloom's Revised Taxonomy — cognitive level progression (Remember → Create)
  • Spiral Curriculum — revisit concepts at increasing depth
  • Vygotsky's ZPD + Scaffolding — guided support that fades as skills grow
  • Kolb's Experiential Learning — learn by doing, reflect, conceptualize, experiment
  • Dreyfus Model — calibrate guidance from novice to expert

What It Does

Three skills that work together:

Course Creator

Generate structured, hands-on technical courses from a topic + reference materials.

  • Interactive interview or spec file to define scope, audience, and depth
  • Ingests URLs, local repos, GitHub repos, and documentation as source material
  • Produces a full course: concept lessons, code-along exercises, and progressive challenges
  • Spiral progression: Foundation → Practice → Mastery loops of increasing complexity

Guide Creator

Build large-scale technical reference guides (like the 100x Engineer Guide series) using the diverge-converge method with parallel agents.

  • Brainstorm curriculum with fractal spiral structure
  • Dispatch 8-12 parallel agents to write 60+ chapters simultaneously
  • Converge to weave cross-references and ensure consistency
  • Refine with targeted agents, then final polish pass
  • Produces complete guides: 50-80k+ lines across multiple Parts and Phases

Tech Tutor

Interactive tutoring that brings course content to life.

  • Mode-switching: adaptive (concepts), Socratic (challenges), direct (on request), supportive (when struggling)
  • Skip-ahead support: each module has an "In This Episode" summary for self-assessment
  • Conversational enrichment of authored course material

Installation

Prerequisites

Install from marketplace (recommended)

Add this repo as a marketplace source, then install the plugin:

# 1. Add the marketplace
/plugin marketplace add cemergin/tech-skill-builder

# 2. Install the plugin
/plugin install tech-skill-builder@tech-skill-builder

Or from the CLI:

claude plugin marketplace add cemergin/tech-skill-builder
claude plugin install tech-skill-builder@tech-skill-builder

Installation scopes

By default, the plugin installs to user scope (available across all projects). You can choose a different scope:

  • User (default): available everywhere, stored in ~/.claude/settings.json
  • Project: shared with teammates via .claude/settings.json in the repo
  • Local: just for you in this repo, gitignored
# Install for your whole team on a specific project
claude plugin install tech-skill-builder@tech-skill-builder --scope project

Updating

/plugin marketplace update tech-skill-builder
/plugin install tech-skill-builder@tech-skill-builder

Install for local development

Clone the repo and load it directly with --plugin-dir:

git clone https://github.com/cemergin/tech-skill-builder.git
claude --plugin-dir ./tech-skill-builder

This is useful for testing changes before committing. Restart Claude Code to pick up edits.

Team configuration

Add the marketplace to your project's .claude/settings.json so teammates are prompted to install it automatically:

{
  "extraKnownMarketplaces": {
    "tech-skill-builder": {
      "source": {
        "source": "github",
        "repo": "cemergin/tech-skill-builder"
      }
    }
  },
  "enabledPlugins": {
    "tech-skill-builder@tech-skill-builder": true
  }
}

Verify installation

After installing, confirm the plugin loaded:

/plugin

Go to the Installed tab — you should see tech-skill-builder. The skills and commands should now be available.

Usage

Creating a Guide

# Build a comprehensive guide using parallel agents
/tech-skill-builder:create-guide "100x AI Engineer Guide"

The skill will:

  1. Brainstorm the curriculum structure with spiral progression
  2. Scaffold the directory and initialize git
  3. Dispatch 8-12 parallel agents to write all chapters
  4. Converge to weave cross-references and consistency
  5. Refine and polish with targeted passes

Creating a Course

# Start the interactive course creator (command)
/tech-skill-builder:create-course Terraform for our platform team

# Or provide a spec file
/tech-skill-builder:create-course ./courses/terraform-101/course-spec.yaml

The skill will:

  1. Interview you (or read your spec) to understand scope, audience, and depth
  2. Generate a course outline with spiral progression
  3. Research your provided URLs, repos, and docs
  4. Write each module with lessons, exercises, and challenges
  5. Present for your review

Learning from a Course

# Start an interactive tutoring session (command)
/tech-skill-builder:learn ./courses/terraform-101

The tutor will:

  1. Assess your current level
  2. Suggest an entry point (or let you choose)
  3. Walk you through lessons, exercises, and challenges
  4. Adapt its teaching style to your needs

Course Output Structure

courses/<course-name>/
  course.yaml                  # metadata, prerequisites, spiral progression map
  01-<module-name>/
    episode.md                 # "In This Episode" — summary, key concepts, prerequisites
    lesson.md                  # Foundation: concept explanation with examples
    exercise.md                # Practice: step-by-step code-along
    challenge.md               # Mastery: open-ended problem with hints
    starter/                   # starter code files
    solution/                  # reference solutions
  02-<module-name>/
    ...
  capstone/                    # optional: ties all loops together
    brief.md
    starter/
    solution/

Plugin Structure

tech-skill-builder/
  .claude-plugin/
    plugin.json                         # plugin manifest
    marketplace.json                    # marketplace catalog
  skills/
    course-creator/                     # course authoring skill (model-invoked)
      SKILL.md
      references/                       # pedagogical framework, output format, etc.
    guide-creator/                      # mega-guide authoring skill (model-invoked)
      SKILL.md                          # diverge-converge workflow for parallel chapter writing
    tech-tutor/                         # interactive tutoring skill (model-invoked)
      SKILL.md
      references/                       # tutoring modes, assessment rubric, etc.
  agents/
    chapter-writer.md                   # writes individual guide chapters (parallel dispatch)
    course-researcher.md                # fetches URLs, repos, web search
    module-writer.md                    # writes individual course modules
  commands/
    create-course.md                    # /create-course user-invocable command
    create-guide.md                     # /create-guide user-invocable command
    learn.md                            # /learn user-invocable command

Target Audience

Built for diverse technical teams:

  • Engineers (onboarding to new tools, frameworks, or codebases)
  • Data scientists (learning infrastructure, SQL, new libraries)
  • Designers (learning APIs, design systems tooling)
  • PMs & analysts (learning SQL, CLI tools, data pipelines)
  • Anyone building technical skills through hands-on practice

Pedagogical Approach

Each module follows a micro-progression:

  1. Foundation (Remember/Understand) — read the concept, see examples
  2. Practice (Apply/Analyze) — code-along with guided steps
  3. Mastery (Evaluate/Create) — solve a challenge independently

Modules are grouped into spiral loops — each loop revisits the domain at a higher complexity level. Early modules have more scaffolding; later modules remove guardrails.

Voice & Tone

All generated content uses "The Nerdy Friend" voice — imagine a colleague who genuinely lights up when talking about this topic. They use analogies, acknowledge when something is confusing, crack jokes about the absurdity of tech, but never make you feel dumb.

Design Document

See docs/plans/2026-03-09-tech-skill-builder-design.md for the full design with pedagogical research, architecture decisions, and voice specification.

Contributing

PRs welcome! If you'd like to improve the pedagogical framework, add new tutoring modes, or enhance the course output format, check the reference docs in skills/*/references/ for context.

Test your changes locally with:

claude --plugin-dir ./tech-skill-builder

License

MIT