Educational Packs Development Guide

src/knowledge/packs/
  your-subject/
    .skillmeta
    VISION.md
    modules.yaml
    activities.json
    assessment.yaml
    resources.yaml
    README.md

1. What Are Knowledge Packs?

A knowledge pack is a structured bundle of educational content organized around a learning domain. Where individual skills teach Claude how to perform specific tasks, knowledge packs teach learners how to understand specific subjects. They are the curriculum delivery format for the entire gsd-skill-creator educational system.

Think of a knowledge pack the way you would think of a course binder. It contains everything needed to teach a subject: the syllabus (modules), the lesson plans (activities), the rubrics (assessments), the textbook references (resources), and the learning objectives that tie everything together. The difference is that this binder is machine-readable, version-controllable, and adaptive — it can adjust its content delivery based on how each learner is progressing.

Every knowledge pack contains these components:

• Skills that teach specific concepts — Each skill within a pack encapsulates one teachable unit. A skill might explain how generic type parameters work, walk through a circuit analysis technique, or demonstrate a historical research method. Skills follow the standard SKILL.md format with YAML frontmatter and Markdown body.
• Agents that guide learning interactions — Packs can include agent definitions that act as tutors, assessors, or lab supervisors. A tutor agent guides learners through material at their pace. An assessor agent evaluates work products against rubric criteria. A lab supervisor agent enforces safety constraints during hands-on exercises.
• Reference materials graded by difficulty — Resources are organized into three depth levels: practical (how to use it), reference (how it works), and mathematical (formal analysis). This 3-level depth model means the same pack can serve a high school student exploring a topic for the first time and a graduate student seeking formal rigor.
• Assessment criteria and verification gates — Each module defines what mastery looks like through measurable learning outcomes. Assessment methods are tagged as formative (check understanding during learning) or summative (evaluate mastery at boundaries). Verification gates prevent advancement until competency is demonstrated.
• Progressive disclosure from beginner through advanced — Grade levels span from Foundation (PreK) through College (16+), with estimated learning hours for each band. The grade router (src/knowledge/grade-router.ts) selects appropriate content depth based on the learner's level, so a single pack serves multiple audiences without separate versions.

The system currently ships with 35 foundational knowledge packs organized into three tiers: 15 Core Academic packs (mathematics, science, language, etc.), 10 Applied and Practical packs (coding, data science, writing, etc.), and 10 Specialized packs (astronomy, philosophy, music, etc.). These packs demonstrate the format in production and serve as templates for your own curriculum.

2. Knowledge Pack Architecture

The knowledge system is implemented across five interconnected components in src/knowledge/. Understanding how they fit together helps you design packs that take full advantage of the adaptive features.

2.1 Knowledge Pack Format (v1.28)

The foundation is the KnowledgePackSchema defined in src/knowledge/types.ts. This Zod schema defines every field that a .skillmeta YAML file can contain. It is the single source of truth for pack data shapes — every other module imports from here.

The schema covers:

• Identity and lifecycle — pack_id, pack_name, version, status (alpha/beta/stable/deprecated), classification (core_academic/applied/specialized)
• Structure — modules array with learning outcomes, topics, grade levels, time estimates, and prerequisite modules
• Dependencies — prerequisite_packs, enables, dependencies, and related_packs for graph construction
• Assessment — assessment_methods with type (formative/summative), name, and frequency
• Accessibility — Screen reader compatibility, keyboard navigation, high contrast, captions, alt text
• Standards alignment — Framework references (Common Core, NCTM, etc.) with version and alignment mappings
• Quality assurance — Peer review status, learner testing, bias audit, accessibility audit completion flags
• GSD integration — Dashboard display settings, activity scaffolding toggle, adaptive pacing, prompt cache keys

The skillmeta-parser.ts module parses .skillmeta YAML files using js-yaml's safe loader (preventing arbitrary code execution) and validates the result against the Zod schema. Parse errors return human-readable messages with field paths, so you know exactly which line needs fixing.

2.2 Knowledge Patterns (v1.28)

The learning-pattern-detector.ts module analyzes streams of learner observations to identify successful learning approaches. It detects four pattern types:

• Sequence patterns — Consistent ordering of module completions across multiple learners. If learners who complete Module 2 before Module 3 consistently score higher on the Module 3 assessment, that is a sequence pattern worth codifying.
• Timing patterns — Correlations between time investment and outcomes. If spending more time on early modules correlates with higher assessment scores later, the system detects this and can suggest pacing adjustments.
• Scoring patterns — Rubric level progression within packs. The detector tracks how learners move through rubric levels (beginning, developing, proficient, advanced) and surfaces patterns in that progression.
• Engagement patterns — Correlations between activity completion rates and assessment outcomes. If completing all optional activities correlates with significantly higher assessment scores, that is actionable information for curriculum design.

Each detected pattern includes a confidence score (0.0 to 1.0), the number of evidence observations supporting it, and the pack IDs where it was observed. Patterns that cross a confidence threshold become suggestions for skill-creator's bounded learning pipeline.

2.3 Knowledge Adaptation (v1.29)

The pathway-adapter.ts module personalizes module and activity ordering based on individual learner observation history. It implements two core adaptation behaviors:

• Reinforcement for struggling learners — When a learner's assessment score falls below the struggle threshold (default: 50), the adapter inserts additional reinforcement activities for that module before allowing progression. These activities are drawn from the activity scaffolder's generated exercises, capped at 3 per module to prevent frustration loops.
• Acceleration for excelling learners — When assessment scores exceed the excel threshold (default: 90), the adapter marks modules for potential skipping and reorders the remaining pathway to prioritize more challenging content.

Every adaptation decision is fully traceable. The AdaptedPathway object records the original module order, the adapted order, every adaptation decision with its reason and confidence level, and the observation IDs that served as evidence. This traceability is critical for teachers — you can always see why the system changed a learner's path and override it if the reasoning does not match your pedagogical judgment.

2.4 Knowledge Scaffolding (v1.29)

The activity-scaffolder.ts module converts detected learning patterns into concrete PackActivity objects that can be inserted into existing activity chains. When the pattern detector finds that a particular exercise sequence leads to better outcomes, the scaffolder generates new activities that reinforce that sequence.

Each scaffolded activity includes:

• A generated activity conforming to the PackActivitySchema (ID, name, module reference, grade range, duration, materials, learning objectives)
• An insertion point indicating where it belongs in the activity chain
• A rationale explaining why this activity was generated and which pattern inspired it

The scaffolder is configurable: you can set the ID prefix for generated activities (default: scaff), the maximum activities to generate per pattern (default: 2), and the default duration in minutes (default: 20). This ensures generated activities stay bounded and do not overwhelm the original curriculum with machine-generated content.

2.5 Knowledge Promotion (v1.29)

The approach-promoter.ts module converts high-confidence learning patterns into reusable skill definitions that enter the skill library. This is the bridge between the knowledge system and skill-creator's core learning loop: patterns detected in educational contexts become skills that improve future educational delivery.

A promoted approach includes a skill name, an activation-friendly description, trigger conditions (when the skill should activate), action steps (what the skill does), and traceability back to the originating pattern. Promotion only occurs above a configurable confidence threshold, and — consistent with skill-creator's bounded learning guardrails — all promotions require explicit user confirmation before they take effect.

3. Creating Your First Knowledge Pack

This section walks through creating a complete knowledge pack from scratch. The example builds a pack for teaching TypeScript Generics — a subject with clear progression from simple concepts to advanced type-level programming. Adapt the pattern to your own domain.

Step 1: Choose a Domain and Define Learning Objectives

Before writing any configuration files, answer these questions in plain language:

• What subject am I teaching? — TypeScript Generics
• Who is my audience? — Intermediate TypeScript developers who understand basic types but have not used generics
• What will learners know or be able to do after completing this pack?

For TypeScript Generics, the learning objectives might be:

1. Write functions and classes that use generic type parameters
2. Apply constraints to narrow generic types
3. Use mapped types to transform object types programmatically
4. Write conditional types for type-level branching
5. Apply built-in utility types and create custom ones
6. Implement recursive types for tree-like data structures
7. Use template literal types for string manipulation at the type level

These objectives naturally group into three tiers: beginner (1-3), intermediate (4-5), and advanced (6-7). That tier structure becomes the backbone of your pack.

Step 2: Create the Pack Directory

Create a directory for your pack under the knowledge packs location:

mkdir -p src/knowledge/packs/typescript-generics

Step 3: Write the Vision Document

The VISION.md file captures the educational intent behind your pack. It is read by the vision-parser.ts module and used by agents to understand the pack's purpose. Write it as you would write a course proposal:

# TypeScript Generics — Vision Document

## Purpose
Teach TypeScript developers how to write and reason about generic types,
progressing from basic type parameters through advanced type-level
programming. Generics are the gateway to TypeScript's type system power,
and most intermediate developers avoid them due to confusing error messages
and unclear mental models. This pack addresses both problems directly.

## Audience
Intermediate TypeScript developers who:
- Can write typed functions and interfaces
- Understand union and intersection types
- Have encountered generic syntax (Array<T>) but cannot write their own

## Prerequisites
- Working TypeScript development environment
- Familiarity with TypeScript basic types (string, number, boolean, object)
- Understanding of interfaces and type aliases

## Learning Philosophy
Start with the "why" before the "how". Every generic concept is introduced
through a concrete problem that cannot be solved well without generics,
then the solution is shown, then the underlying type theory is explained
for those who want depth. This mirrors the 3-level depth model:
practical first, reference second, mathematical third.

Step 4: Write the Pack Configuration

The .skillmeta file is the central metadata definition for your pack. It uses YAML and must validate against the KnowledgePackSchema. Here is a complete example:

pack_id: TS-GEN-101
pack_name: TypeScript Generics
version: "1.0.0"
status: alpha
classification: applied
learning_domain: programming/typescript
description: >
  Learn TypeScript generics from basic type parameters to advanced
  conditional types. Covers generic functions, classes, constraints,
  mapped types, conditional types, utility types, recursive types,
  template literal types, and type-level programming patterns.
short_description: TypeScript generics from basics to advanced type-level programming
contributors:
  - name: Your Name
    role: author
copyright: "2026 Your Organization"

# Dependency graph
prerequisite_packs:
  - CODE-101
dependencies: []
enables: []
recommended_prior_knowledge:
  - TypeScript basic types
  - Interfaces and type aliases
  - Union and intersection types

# Grade levels (adapted for professional education)
grade_levels:
  - label: Beginner
    grades: ["beginner"]
    estimated_hours: [4, 6]
  - label: Intermediate
    grades: ["intermediate"]
    estimated_hours: [6, 8]
  - label: Advanced
    grades: ["advanced"]
    estimated_hours: [8, 12]

# Modules
modules:
  - id: generic-basics
    name: Generic Basics
    description: Introduction to generic type parameters in functions and classes
    learning_outcomes:
      - "Write a generic identity function"
      - "Apply generics to class definitions"
      - "Understand type inference with generics"
    topics:
      - Type parameters
      - Generic functions
      - Generic classes
      - Type inference
    grade_levels: ["beginner"]
    time_estimates:
      foundation: 2
    prerequisite_modules: []
    activities:
      count: 3
      examples:
        - "Convert a non-generic function to generic"
        - "Build a generic Stack class"
        - "Type inference puzzle exercises"

  - id: generic-constraints
    name: Generic Constraints
    description: Narrowing generic types with extends clauses and keyof
    learning_outcomes:
      - "Apply extends constraints to generic parameters"
      - "Use keyof with generics for property access"
      - "Combine multiple constraints"
    topics:
      - extends keyword
      - keyof operator
      - Multiple constraints
      - Default type parameters
    grade_levels: ["beginner"]
    time_estimates:
      foundation: 2
    prerequisite_modules: ["generic-basics"]
    activities:
      count: 3
      examples:
        - "Write a getProperty function with keyof constraint"
        - "Create a merge function with object constraints"
        - "Design a factory function with constructor constraints"

  - id: mapped-types
    name: Mapped Types
    description: Transforming object types programmatically using mapped type syntax
    learning_outcomes:
      - "Write custom mapped types"
      - "Use key remapping with as clauses"
      - "Apply template literal types in mapped types"
    topics:
      - Mapped type syntax
      - Key remapping
      - Modifiers (readonly, optional)
      - Template literal types in mappings
    grade_levels: ["intermediate"]
    time_estimates:
      foundation: 3
    prerequisite_modules: ["generic-constraints"]
    activities:
      count: 4
      examples:
        - "Implement Partial, Required, and Readonly from scratch"
        - "Build a DeepReadonly utility type"
        - "Create a type that renames object keys"
        - "Write an API response transformer type"

  - id: conditional-types
    name: Conditional Types
    description: Type-level branching using the extends ternary pattern
    learning_outcomes:
      - "Write conditional types with extends and infer"
      - "Use distributive conditional types over unions"
      - "Extract and exclude types from unions"
    topics:
      - Conditional type syntax
      - infer keyword
      - Distributive behavior
      - Built-in Extract and Exclude
    grade_levels: ["intermediate"]
    time_estimates:
      foundation: 3
    prerequisite_modules: ["mapped-types"]
    activities:
      count: 3
      examples:
        - "Implement Extract and Exclude from scratch"
        - "Write a ReturnType utility type"
        - "Build a type that flattens nested promises"

  - id: utility-types
    name: Utility Types
    description: Mastering built-in utility types and creating custom ones
    learning_outcomes:
      - "Use all built-in utility types correctly"
      - "Compose utility types for complex transformations"
      - "Create domain-specific utility types"
    topics:
      - Built-in utility types catalog
      - Composition patterns
      - Domain-specific utilities
    grade_levels: ["intermediate"]
    time_estimates:
      foundation: 2
    prerequisite_modules: ["conditional-types"]

  - id: recursive-types
    name: Recursive Types
    description: Self-referential type definitions for tree structures and deep operations
    learning_outcomes:
      - "Write recursive type definitions"
      - "Implement DeepPartial and DeepReadonly"
      - "Type-check tree-like data structures"
    topics:
      - Recursive type aliases
      - Depth limits
      - JSON type definition
      - Tree and graph types
    grade_levels: ["advanced"]
    time_estimates:
      foundation: 3
    prerequisite_modules: ["utility-types"]
    activities:
      count: 3
      examples:
        - "Implement a JSON type from scratch"
        - "Build DeepPartial with recursive mapped types"
        - "Type a file system tree structure"

  - id: template-literal-types
    name: Template Literal Types
    description: String manipulation and pattern matching at the type level
    learning_outcomes:
      - "Write template literal type patterns"
      - "Extract substrings from string literal types"
      - "Build type-safe event emitter interfaces"
    topics:
      - Template literal syntax
      - String type manipulation
      - Pattern matching with infer
      - Event emitter patterns
    grade_levels: ["advanced"]
    time_estimates:
      foundation: 3
    prerequisite_modules: ["conditional-types"]
    activities:
      count: 3
      examples:
        - "Build a type-safe CSS class name builder"
        - "Create a route parameter extractor type"
        - "Design a type-safe event emitter"

# Assessment
assessment_methods:
  - type: formative
    name: Module checkpoint exercises
    frequency: End of each module
  - type: formative
    name: Type error diagnosis challenges
    frequency: Throughout each module
  - type: summative
    name: Tier advancement assessment
    frequency: End of each tier (beginner, intermediate, advanced)
  - type: summative
    name: Capstone project type review
    frequency: End of pack

learning_outcomes:
  - code: TS-GEN-LO1
    description: Write generic functions and classes with type parameters
    levels: ["beginner"]
  - code: TS-GEN-LO2
    description: Apply constraints and utility types effectively
    levels: ["intermediate"]
  - code: TS-GEN-LO3
    description: Design complex type-level programs using conditional and recursive types
    levels: ["advanced"]

# Accessibility
accessibility:
  screen_reader_compatible: true
  keyboard_navigable: true
  alt_text_provided: true

# Standards
standards_alignment: []

# Tools
tools_required:
  - name: TypeScript Compiler
    description: tsc 5.0 or later
tools_optional:
  - name: TypeScript Playground
    url: https://www.typescriptlang.org/play
    description: Browser-based TypeScript experimentation

interactive_elements:
  - type: exercise
    name: Type challenge puzzles
  - type: simulator
    name: Type inference visualizer

translations:
  available:
    - language_code: en
      name: English
      complete: true
  planned: []

tags:
  - typescript
  - generics
  - type-system
  - programming
  - intermediate
  - advanced

resources: []
related_packs:
  - id: CODE-101
    relationship: prerequisite

gsd_integration:
  skill_creator_enabled: true
  activity_scaffolding: true
  adaptive_pacing: true

files:
  vision_document: VISION.md
  modules_definition: modules.yaml
  activities: activities.json
  assessment: assessment.yaml
  resources: resources.yaml

changelog:
  - version: "1.0.0"
    date: "2026-02-24"
    changes:
      - Initial pack creation

qa:
  peer_reviewed: false
  tested_with_learners: false
  bias_audit_completed: false
  accessibility_audit_completed: false

difficulty:
  conceptual_demand: moderate to high
  technical_demand: moderate
  prerequisites_required: intermediate TypeScript knowledge

content_flags: []
community: {}
maintenance:
  review_frequency: quarterly
metrics: {}

Step 5: Define the Module Structure

The modules.yaml file provides detailed module definitions, cross-module competencies, and progression pathways. It is parsed by the module-loader.ts module and used by the pathway adapter for learning path generation.

pack_id: TS-GEN-101
pack_name: TypeScript Generics

modules:
  - id: generic-basics
    name: Generic Basics
    description: Introduction to generic type parameters in functions and classes
    learning_outcomes:
      - "Write a generic identity function"
      - "Apply generics to class definitions"
      - "Understand type inference with generics"
    topics:
      - Type parameters
      - Generic functions
      - Generic classes
      - Type inference
    grade_levels: ["beginner"]
    time_estimates:
      foundation: 2
    prerequisite_modules: []

  # ... (remaining modules mirror the .skillmeta definitions)

cross_module_competencies:
  - name: Type Error Diagnosis
    description: >
      Ability to read and interpret TypeScript generic error messages,
      identify the source of type mismatches, and propose fixes
    assessed_in:
      - generic-constraints
      - conditional-types
      - recursive-types

  - name: Type Composition
    description: >
      Ability to combine multiple generic patterns (mapped types,
      conditional types, template literals) into cohesive type definitions
    assessed_in:
      - utility-types
      - recursive-types
      - template-literal-types

progression_pathways:
  - name: Standard Linear
    description: Complete all modules in prerequisite order
    rationale: >
      Best for learners new to generics who need each concept
      to build on the previous one

  - name: Applied Focus
    description: >
      Basics -> Constraints -> Utility Types -> Mapped Types,
      skipping deep theory
    rationale: >
      For developers who need practical generic skills quickly
      and can return to theory later

  - name: Type Theory Deep Dive
    description: >
      Basics -> Constraints -> Conditional Types -> Recursive Types ->
      Template Literal Types -> Mapped Types -> Utility Types
    rationale: >
      For learners interested in type-level programming who want
      to understand the theoretical foundations first

parallel_patterns: []

skill_creator_integration:
  observation_points:
    - "Module completion time vs assessment score"
    - "Activity attempt count before passing"
    - "Type error frequency per module"
  pattern_detection:
    - "Sequence: which module order produces best assessment outcomes"
    - "Timing: time-on-task correlation with later module performance"
  skill_promotion:
    - "Promote effective error diagnosis approaches to skill library"

Step 6: Create Activities

The activities.json file defines concrete learning activities for each module. Each activity has a grade range, duration, materials list, and learning objectives. Activities are loaded by the activity-loader.ts module and presented by tutor agents during learning sessions.

[
  {
    "id": "gen-basics-identity",
    "name": "Convert a Non-Generic Function to Generic",
    "module_id": "generic-basics",
    "grade_range": ["beginner"],
    "duration_minutes": 15,
    "description": "Start with a function that only works with strings. Refactor it step by step to work with any type using a generic parameter. Observe how TypeScript infers the type argument at each call site.",
    "materials": ["TypeScript playground or local project", "Sample non-generic functions file"],
    "learning_objectives": [
      "Identify when a function needs to be generic",
      "Add a type parameter to a function signature",
      "Understand type argument inference"
    ],
    "variations": [
      "Advanced: Convert a class with multiple methods",
      "Pair exercise: One student writes the generic, partner writes test cases"
    ]
  },
  {
    "id": "gen-basics-stack",
    "name": "Build a Generic Stack Class",
    "module_id": "generic-basics",
    "grade_range": ["beginner"],
    "duration_minutes": 20,
    "description": "Implement a Stack<T> data structure with push, pop, peek, and isEmpty methods. Write tests that use the stack with different types to verify type safety.",
    "materials": ["TypeScript project with test runner"],
    "learning_objectives": [
      "Apply generics to class definitions",
      "Write type-safe data structure methods",
      "Test generic classes with multiple type arguments"
    ]
  },
  {
    "id": "gen-constraints-getprop",
    "name": "Write a getProperty Function with keyof",
    "module_id": "generic-constraints",
    "grade_range": ["beginner"],
    "duration_minutes": 15,
    "description": "Write a function that safely accesses a property from an object using keyof constraints. The function should reject invalid property names at compile time.",
    "materials": ["TypeScript playground"],
    "learning_objectives": [
      "Use extends with keyof for property constraints",
      "Understand the relationship between keyof and generic parameters"
    ]
  }
]

Step 7: Build Assessment Criteria

The assessment.yaml file defines rubrics and scoring criteria. It is parsed by the assessment-loader.ts module. Assessments come in two types: formative (in-progress checks) and summative (mastery evaluations at tier boundaries).

pack_id: TS-GEN-101
assessments:
  - id: beginner-tier-assessment
    type: summative
    name: Beginner Tier Completion
    description: Verify mastery of generic basics and constraints
    modules_assessed:
      - generic-basics
      - generic-constraints
    rubric_levels:
      - level: beginning
        score_range: [0, 49]
        description: >
          Cannot write generic functions without significant assistance.
          Struggles with basic type parameter syntax.
      - level: developing
        score_range: [50, 69]
        description: >
          Can write simple generic functions but makes errors with
          constraints. Needs prompting for keyof and extends patterns.
      - level: proficient
        score_range: [70, 89]
        description: >
          Writes generic functions and classes with appropriate constraints.
          Can diagnose basic type errors independently.
      - level: advanced
        score_range: [90, 100]
        description: >
          Writes clean, idiomatic generics. Explains type inference behavior
          to others. Creates reusable generic abstractions.
    required_score: 70
    verification_tasks:
      - "Write a generic function with at least two type parameters"
      - "Apply a constraint using extends and keyof"
      - "Explain why a given generic type error occurs"

  - id: intermediate-tier-assessment
    type: summative
    name: Intermediate Tier Completion
    modules_assessed:
      - mapped-types
      - conditional-types
      - utility-types
    required_score: 75
    rubric_levels:
      - level: beginning
        score_range: [0, 49]
        description: Cannot write mapped or conditional types without copying examples
      - level: developing
        score_range: [50, 74]
        description: Can modify existing mapped/conditional types but struggles to create new ones
      - level: proficient
        score_range: [75, 89]
        description: Creates custom mapped and conditional types for practical use cases
      - level: advanced
        score_range: [90, 100]
        description: Composes complex type transformations fluently and can explain distributive behavior
    verification_tasks:
      - "Implement Partial from scratch using mapped type syntax"
      - "Write a conditional type that extracts function return types"
      - "Create a custom utility type for a real-world use case"

  - id: advanced-tier-assessment
    type: summative
    name: Advanced Tier Completion
    modules_assessed:
      - recursive-types
      - template-literal-types
    required_score: 80
    rubric_levels:
      - level: beginning
        score_range: [0, 49]
        description: Cannot reason about recursive or template literal type structures
      - level: developing
        score_range: [50, 79]
        description: Understands the concept but makes errors in recursive depth or template pattern matching
      - level: proficient
        score_range: [80, 89]
        description: Writes recursive types and template literal types for practical scenarios
      - level: advanced
        score_range: [90, 100]
        description: Designs type-level programs that combine recursive, conditional, and template literal types
    verification_tasks:
      - "Implement a DeepPartial type using recursion"
      - "Write a template literal type that parses route parameters"
      - "Build a type-safe event system combining all advanced patterns"

Step 8: Validate and Test

Run the content validator to check your pack's structural integrity:

npx skill-creator validate-pack src/knowledge/packs/typescript-generics/

The validator (src/knowledge/content-validator.ts) checks that all referenced files exist, that module IDs are consistent between .skillmeta and modules.yaml, that prerequisite references resolve to actual modules, and that activities reference valid module IDs. It returns a PackValidationReport with per-file status and any issues found.

To test with a sample learner session, install the pack into a test project and interact with Claude:

# Copy pack to a test project
cp -r src/knowledge/packs/typescript-generics/ test-project/.claude/skills/typescript-generics/

# Start a learning session
# Ask Claude: "I want to learn TypeScript generics. Where should I start?"

Claude will read the pack's vision document, module structure, and grade routing to deliver the first module's content at the appropriate depth. Iterate on your pack based on how the learning session flows.

4. Curriculum Design Patterns

The knowledge pack format supports several proven curriculum design patterns. Choose the pattern that best matches your teaching philosophy and subject matter. You can combine patterns within a single pack using the progression pathways feature.

4.1 Spiral Curriculum

In a spiral curriculum, learners revisit the same concepts at increasing depth across multiple passes. The first pass introduces vocabulary and basic mechanics. The second pass applies those concepts to real problems. The third pass explores edge cases and formal properties.

To implement a spiral curriculum in a knowledge pack:

• Structure modules so each tier revisits core concepts at greater depth
• Use the 3-level depth model (practical, reference, mathematical) within each module
• Set prerequisite modules so each spiral pass requires completing the previous pass on the same topic
• Use cross-module competencies to track how understanding deepens across passes

The TypeScript Generics pack above implicitly uses this pattern: "generic-basics" introduces type parameters, "generic-constraints" revisits them with narrowing, and "conditional-types" revisits narrowing again with type-level branching.

4.2 Problem-Based Learning

In problem-based learning, each module starts with a real problem that cannot be solved well without the concept being taught. The learner encounters the problem, attempts a solution with existing knowledge, discovers the limitation, and then learns the new concept as the solution.

To implement this pattern:

• Write each module's first activity as a "motivating problem" — a task that exposes the need for the new concept
• Structure activities in the order: encounter problem, attempt naive solution, learn concept, apply concept to solve problem, extend to new problems
• Use the activity variations field to provide alternative problems for different backgrounds
• Set formative assessments after the problem-solving phase, not after the explanation phase

4.3 Mastery-Based Progression

Mastery-based progression gates advancement on demonstrated competency rather than time spent. Learners cannot move to the next tier until they pass the current tier's summative assessment at the required score threshold.

The knowledge pack format supports this natively through:

• Assessment required_score fields — Set minimum scores for tier advancement (e.g., 70 for beginner, 75 for intermediate, 80 for advanced)
• Pathway adaptation — The PathwayAdapter automatically inserts reinforcement activities for learners below the struggle threshold
• Verification tasks — Concrete tasks that must be demonstrated before progression
• Grade routing — The grade-router.ts module selects content at the appropriate depth based on current tier

This is the recommended default pattern for professional education packs. The TypeScript Generics assessment configuration above implements mastery-based progression with escalating thresholds (70, 75, 80) across the three tiers.

4.4 Peer Teaching

In a peer teaching model, advanced learners help beginners as part of their own learning process. Teaching a concept solidifies understanding and reveals gaps that passive study misses.

To implement peer teaching with knowledge packs:

• Create a "tutor" agent role with router topology — the agent routes questions from beginner learners to advanced learners before answering itself
• Include "explain to a peer" activities in advanced modules — these require the learner to articulate concepts in their own words
• Use the observation hooks to track when advanced learners help beginners, creating engagement patterns that the pattern detector can surface
• Set up a team-based deployment where multiple learners share the same project, enabling cross-learner observation streams

4.5 Lab-Based Learning

Lab-based learning focuses on hands-on experimentation with guided safety constraints. This pattern is exemplified by the Electronics education model (Section 5), where 77 lab templates provide structured experimentation environments with a Safety Warden ensuring learners do not encounter dangerous configurations.

To implement lab-based learning:

• Structure each module around one or more lab exercises rather than lectures
• Define safety constraints and boundary conditions in the pack metadata (use content_flags for safety warnings)
• Create a lab supervisor agent that monitors learner actions and intervenes when safety boundaries are approached
• Use the 3 Safety Warden modes as a model: annotate (add warnings but allow action), gate (require confirmation before risky actions), redirect (substitute a safer alternative automatically)
• Include pre-lab and post-lab assessment activities to bracket the experiential learning with reflection

5. The Electronics Education Model

The electronics subsystem is the most complete educational pack implementation in gsd-skill-creator. Study it as the reference implementation for your own packs. It demonstrates every feature of the knowledge pack format at production scale, with over 10,700 tests proving the educational content.

5.1 Scale and Scope

The electronics education system covers:

• 15 modules progressing from basic circuit theory through industrial applications — Ohm's Law, Kirchhoff's Laws, AC analysis, semiconductor physics, digital logic, microcontrollers, signal processing, power systems, PCB design, PLC programming, and solar engineering
• 77 interactive labs with progressive difficulty — each lab has a defined prerequisite chain, safety requirements, equipment list, procedure steps, and expected outcomes
• 5 specialized simulation engines — DSP (Digital Signal Processing), GPIO (General Purpose Input/Output), PLC (Programmable Logic Controller), Solar (photovoltaic system sizing), and PCB (printed circuit board layout)
• Safety Warden with 3 operating modes — annotate (passive warnings), gate (require confirmation for dangerous operations), and redirect (automatically substitute safer alternatives)

5.2 What Teachers Can Learn From It

The electronics model demonstrates several patterns worth adopting in your own packs:

• Progressive module prerequisites — Each module explicitly declares which previous modules must be completed. The dependency resolver (src/knowledge/dependency-resolver.ts) uses these to construct a valid learning sequence and detect circular dependencies.
• Lab safety as first-class concern — The Safety Warden is not an afterthought bolted onto the education system. It is integrated into every lab template. For subjects with safety considerations (chemistry, shop work, electrical work, outdoor activities), design safety into your pack structure from the beginning.
• Simulation before hardware — The 5 specialized engines let learners experiment with circuit configurations, signal processing algorithms, and control logic in software before touching physical components. If your domain has a simulation-first pathway, build simulation activities that precede hands-on work.
• Assessment tied to observable outcomes — Electronics assessments do not ask "Do you understand Ohm's Law?" They ask "Calculate the current through this circuit and verify with the simulator." Every assessment has a verification task that produces an observable, checkable result. Model your assessments on this pattern.
• The 3-level depth model in practice — A lab on RC circuits exists at three levels: practical (build the circuit, measure the time constant), reference (derive the time constant formula, explain the exponential decay curve), and mathematical (solve the differential equation, prove the relationship between component values and time constant). Your pack should provide content at all three levels even if most learners stay at practical.

5.3 The Apollo Guidance Computer Curriculum

The Electronics and AGC Education system extends the electronics model with an 11-chapter curriculum built around the Apollo Guidance Computer Block II simulator. This curriculum teaches computer architecture through historically authentic technology — learners execute the same 38-instruction set that guided Apollo 11 to the Moon.

The AGC curriculum is notable as a reference implementation because it demonstrates:

• How to build a complete multi-chapter curriculum within the knowledge pack format
• How simulation and historical narrative combine to create engaging learning experiences
• How to structure assessment around both technical competency (can you write AGC assembly?) and conceptual understanding (can you explain why ones' complement arithmetic matters?)
• How the 3-level depth model works at curriculum scale — Chapter 1 is practical (run your first program), Chapter 6 is reference (how the executive scheduler works), Chapter 11 is mathematical (formal verification of restart protection)

If you are building a curriculum that combines simulation, history, and progressive technical depth, the AGC curriculum is the model to study. See the AGC Curriculum capability page (CAP-096) for the full specification.

6. Assessment Design

Assessment is where curriculum design meets accountability. The knowledge pack format provides structured support for both formative and summative assessment, with verification gates and portfolio collection. This section explains how to design assessments that accurately measure learning while remaining practical for AI-assisted delivery.

6.1 Formative Assessment

Formative assessments check understanding during the learning process. They are low-stakes, frequent, and designed to give both the learner and the adaptive system information about current comprehension.

In a knowledge pack, formative assessments are defined as assessment methods with type: formative. They trigger the observation hooks (src/knowledge/observation-hooks.ts) that feed data to the pattern detector and pathway adapter. Effective formative assessments share these characteristics:

• Embedded in activities — The assessment happens as part of doing, not as a separate test. A coding activity might include a "predict the type error" step before the learner runs the compiler. The prediction is the assessment.
• Immediate feedback — Learners see results right away. In the TypeScript Generics pack, a type challenge exercise gives instant feedback because the TypeScript compiler itself provides the verdict.
• Drives adaptation — Formative assessment results feed the PathwayAdapter. A score below the struggle threshold triggers reinforcement. A score above the excel threshold triggers acceleration. Without formative data, the adapter has nothing to work with.
• Non-penalizing — Formative assessment scores do not gate progression. They inform pacing. Learners should feel comfortable getting things wrong during formative checks because that is how the system learns where to provide more support.

Design formative assessments as inline questions within your activities. For each activity, include at least one formative check that produces an observable signal (a code output, a prediction that can be verified, a classification task with a correct answer).

6.2 Summative Assessment

Summative assessments evaluate mastery at tier boundaries. They are higher-stakes and serve as the verification gates for progression. In the pack format, summative assessments use type: summative and include rubric levels, required scores, and verification tasks.

Effective summative assessments for knowledge packs:

• Cover the full tier — A tier summative should assess all modules in that tier, not just the last one completed. The modules_assessed array in the assessment definition specifies which modules are evaluated.
• Use rubric levels — Define 4 performance levels (beginning, developing, proficient, advanced) with score ranges and behavioral descriptions. The descriptions must be observable — "can write a generic function" rather than "understands generics."
• Include verification tasks — These are concrete demonstrations of competency. "Write a conditional type that extracts function return types" is a verification task. "Show understanding of conditional types" is not — it is too vague to verify.
• Set appropriate thresholds — The required_score field sets the minimum score for advancing to the next tier. Increase thresholds with tier level (70 for beginner, 75 for intermediate, 80 for advanced) to ensure mastery compounds.

6.3 Verification Gates

Verification gates are automated checks that confirm a learner can demonstrate a specific competency. They are the mechanism that makes mastery-based progression enforceable in an AI-assisted context.

A verification gate works as follows:

1. The learner completes the summative assessment activities
2. The assessor agent (or the tutor agent in assessor mode) evaluates the work against the rubric
3. The result is recorded as an AssessmentResult observation via the observation hooks
4. The pathway adapter checks the result against the required_score
5. If the score meets the threshold, the next tier's modules become available
6. If the score falls short, reinforcement activities are generated by the activity scaffolder

Design verification tasks that are objectively checkable. For programming packs, "code compiles and passes tests" is an excellent verification criterion because it is binary and automated. For conceptual subjects, use "produce a written explanation that includes terms X, Y, and Z" or "correctly classify 8 out of 10 examples."

6.4 Portfolio Assessment

Portfolio assessment collects learner work products across the entire pack. It provides a longitudinal view of learning progression that point-in-time assessments cannot capture.

To implement portfolio assessment in a knowledge pack:

• Designate certain activities as "portfolio activities" — their outputs are preserved rather than discarded after assessment
• Define portfolio review criteria as a summative assessment at the pack level (frequency: "End of pack")
• Use the observation stream to track the sequence and timing of portfolio submissions
• Include a reflection activity at the end where learners review their own portfolio and identify their growth areas

Portfolio assessment is particularly valuable for subjects where learning is cumulative and creative — writing, design, coding projects, and research. The capstone project assessment in the TypeScript Generics pack serves this role: learners build a real type system component that demonstrates competencies accumulated across all three tiers.

6.5 Calibrating Assessment Thresholds

The threshold values in your pack (required scores, struggle/excel thresholds, rubric boundaries) should be treated as initial estimates that you refine based on real learner data. The calibration workflow is:

1. Start with reasonable defaults — Use the thresholds from this guide (70/75/80 for tier advancement, 50 for struggle, 90 for excel)
2. Deploy to a pilot group — Run the pack with a small group of learners and collect observation data
3. Review pattern detector output — The learning pattern detector will surface timing and scoring patterns that indicate whether thresholds are calibrated correctly
4. Adjust based on evidence — If most learners pass the beginner tier easily but struggle at intermediate, the beginner threshold may be too low (not filtering for genuine mastery) or the intermediate content may need additional scaffolding
5. Use the calibration tutorial — The Calibrating Thresholds tutorial provides a step-by-step workflow for this process

Assessment threshold tuning is one of the highest-value activities a curriculum designer can perform. Small adjustments in thresholds can have large effects on learner outcomes because they control when adaptation triggers and when progression is gated.

7. Deploying Packs to Students

A knowledge pack has no educational value until it reaches learners. This section covers the deployment models available and the progress tracking that keeps you informed about how your curriculum is performing.

7.1 Project-Level Deployment

The simplest deployment model places the knowledge pack in a student's project directory. Copy the pack into .claude/skills/ within the student's working project:

# Deploy a pack to a student project
cp -r src/knowledge/packs/typescript-generics/ \
  /path/to/student-project/.claude/skills/typescript-generics/

When the student opens their project with Claude, the skill loading pipeline discovers the pack and makes its content available. The tutor agent reads the pack's vision, modules, and activities to provide structured learning guidance.

Project-level deployment is appropriate when:

• The learning is tied to a specific project context (e.g., learning generics while building a real TypeScript application)
• You want pack content scoped to one project and not visible in other contexts
• Multiple students work on the same project with the same curriculum

7.2 User-Level Deployment

For personal learning that spans multiple projects, deploy packs to the user-level skills directory:

# Deploy a pack for personal learning across all projects
cp -r src/knowledge/packs/typescript-generics/ \
  ~/.claude/skills/typescript-generics/

User-level packs are available in every project the learner opens. This is appropriate for:

• Self-directed learning that is not tied to a specific project
• Reference packs that a learner wants accessible everywhere (e.g., a writing style guide)
• Personal skill development programs

Note: If a pack with the same name exists at both project and user level, the project-level version takes precedence. This allows teachers to deploy a customized version of a pack for a specific course while students retain a general version for other work.

7.3 Team-Based Deployment

For classroom or cohort-based learning, deploy packs through a shared Git repository. All students clone the same repository, which includes the knowledge packs in .claude/skills/:

# Set up a course repository
mkdir typescript-course && cd typescript-course
git init
mkdir -p .claude/skills/
cp -r /path/to/packs/typescript-generics/ .claude/skills/typescript-generics/
git add . && git commit -m "Initial course setup with TypeScript Generics pack"

# Students clone the repository
git clone https://github.com/your-org/typescript-course.git

Team-based deployment enables:

• Consistent curriculum across all students in a cohort
• Version-controlled updates — push pack improvements and students pull them
• Cross-learner observation streams when students push their session data back to the shared repository
• Peer teaching configurations where advanced students' work is visible to the group

7.4 Progress Tracking

Knowledge pack progress is tracked through the observation system. Every module completion, activity attempt, and assessment result generates an observation event via the ObservationEmitter (src/knowledge/observation-hooks.ts). These observations are typed using the schemas in observation-types.ts:

• ActivityCompletion — Records which activity was completed, how long it took, and whether it was successful
• AssessmentResult — Records scores, rubric levels achieved, and verification task outcomes
• TimeSpent — Records time on each module for pacing analysis
• PackLifecycle — Records pack-level events (started, tier completed, pack completed)

For teachers, the most valuable progress signal is the AssessmentResult observation. Query the observation stream for a specific learner and pack to see:

• Which tiers have been completed and at what score
• Which verification tasks passed and which required additional attempts
• How the learner's scores trended over time (beginning, developing, proficient)
• Which modules triggered reinforcement (indicating areas of difficulty)

7.5 Feedback Loops

The most powerful feature of knowledge pack deployment is the feedback loop between student learning and curriculum improvement. Here is how it works:

1. Students learn from the pack, generating observation data
2. The learning pattern detector analyzes observations and surfaces patterns (e.g., "students who complete the constraints module before mapped types score 15% higher on the intermediate assessment")
3. The approach promoter converts high-confidence patterns into skill suggestions
4. You (the teacher) review the suggestions and decide which to apply
5. Applied suggestions improve the pack for future learners

Student corrections are the highest-signal input for this feedback loop. When a learner tells Claude "that explanation was confusing" or "I need a simpler example," those corrections are captured as observations. If the same correction occurs 3 or more times across different learners, the pattern detector flags it as a curriculum improvement candidate. This is the bounded learning system working in educational context — the pack gets better over time, but only with your explicit approval.

8. Integrating with GSD Workflows

If you use GSD (Get Shit Done) for project management, knowledge pack development maps naturally onto GSD's phase-based workflow. This section shows how to use GSD commands to structure your curriculum development process.

8.1 Scaffolding a Learning Project

Use /gsd:new-project to initialize a new curriculum development project. GSD's questioning phase will prompt you for:

• What subject are you building curriculum for?
• Who is the target audience (age, skill level, context)?
• What prior knowledge is assumed?
• What learning outcomes should students achieve?
• What constraints exist (time, technology, safety)?

The answers to these questions become the PROJECT.md and REQUIREMENTS.md that guide the rest of development. They also map directly to the knowledge pack's vision document and .skillmeta metadata — so the GSD questioning phase effectively drafts your pack configuration for you.

8.2 Structuring Learning Milestones

Use /gsd:plan-phase to structure each major piece of curriculum development as a phase. A typical milestone structure for pack development:

Phase	GSD Command	Deliverable
1. Domain Research	/gsd:research-phase 1	Subject matter survey, prerequisite mapping, competitor curriculum analysis
2. Pack Configuration	/gsd:plan-phase 2	.skillmeta, VISION.md, modules.yaml
3. Activity Development	/gsd:execute-phase 3	activities.json with all exercises and variations
4. Assessment Design	/gsd:execute-phase 4	assessment.yaml with rubrics and verification tasks
5. Resource Curation	/gsd:execute-phase 5	resources.yaml with external references
6. Validation	/gsd:verify-work 6	Pack validation report, pilot test results
7. Deployment	/gsd:execute-phase 7	Pack deployed to target audience

8.3 Automated Assessment via Verification

Use /gsd:verify-work to run automated checks on your pack at any stage of development. The verification workflow runs:

• The content validator (content-validator.ts) to check structural integrity
• The prerequisite validator (prerequisite-validator.ts) to verify dependency graph consistency
• The dependency resolver (dependency-resolver.ts) to check for circular dependencies
• A sample learning session to verify that the tutor agent can navigate the pack correctly

This is the educational equivalent of running tests on code — verify early, verify often, and fix issues before deployment.

8.4 Vision-to-Mission for Curriculum Ideas

If you have a curriculum idea but are not ready for full pack development, use /gsd:discuss-phase to explore the idea with Claude before committing to a plan. This is GSD's "vision before plan" pattern applied to curriculum design:

/gsd:discuss-phase 1
"I want to build a knowledge pack for teaching machine learning to
high school students. They have MATH-101 and CODE-101 as prerequisites.
The pack should cover supervised learning, neural networks, and ethical
AI. What should the module structure look like?"

Claude will use the knowledge pack format and existing pack structures as reference to help you think through module organization, prerequisite chains, activity types, and assessment strategies before you start writing YAML files.

Sample Lesson Plan: TypeScript Generics, Module 1

This sample lesson plan shows how the generic-basics module from the TypeScript Generics pack translates into a concrete 2-hour teaching session. Use this as a template when converting your own pack modules into classroom-ready plans.

Time	Activity	Type	Assessment
0:00-0:10	Motivating problem. Present a function that works on strings, numbers, and objects but requires three separate implementations. Ask: "Can we write this once?" Let students attempt a solution using any and discover the type safety loss.	Problem-based introduction	Formative: observe initial approaches
0:10-0:25	Concept introduction. Introduce the <T> syntax. Walk through the identity function example. Show how TypeScript infers the type argument at each call site. Demonstrate compiler errors when the generic is misused.	Direct instruction	Formative: "Predict the type" inline questions
0:25-0:40	Activity: Convert a Non-Generic Function to Generic (gen-basics-identity). Students refactor the motivating problem's function to use a generic type parameter. Verify that all three use cases work with a single implementation.	Guided practice	Formative: code compiles with correct types
0:40-0:50	Concept extension. Generic classes. Show how Array<T> works under the hood. Introduce the idea that classes can also be parameterized.	Direct instruction	Formative: "What type does this return?" questions
0:50-1:10	Activity: Build a Generic Stack Class (gen-basics-stack). Students implement Stack<T> with push, pop, peek, isEmpty. Write tests using the stack with string, number, and custom types.	Independent practice	Formative: all tests pass
1:10-1:20	Concept: type inference. Show how TypeScript infers generic arguments without explicit annotation. Demonstrate cases where inference works and cases where explicit annotation is needed.	Direct instruction	Formative: inference prediction exercise
1:20-1:40	Activity: Type Inference Puzzle Exercises. Students work through 8 type inference puzzles. Each puzzle presents code and asks "What is the inferred type of T?" Students predict, then verify with the compiler.	Puzzle-based practice	Formative: 6 of 8 correct = mastery
1:40-1:55	Module review and reflection. Revisit the motivating problem. Compare the generic solution to the original three implementations. Discuss where generics add value and where they add unnecessary complexity.	Discussion and reflection	Formative: verbal articulation of generic tradeoffs
1:55-2:00	Preview next module. Show a function where you need to constrain the generic type. "What if T must have a .length property?" This is the motivating problem for the Constraints module.	Preview / hook	None

This lesson plan follows the problem-based learning pattern: motivating problem, concept introduction, guided practice, independent practice, reflection. Each activity maps to a defined activity in activities.json, and every formative assessment generates observation data that feeds the pathway adapter. The session ends with a hook into the next module, maintaining learning momentum.

Troubleshooting

Pack validation fails with "modules referenced in activities not found"

Cause: The module_id in one or more activities does not match any module id in the .skillmeta file.

Solution: Ensure every module_id in activities.json exactly matches a module id in the .skillmeta. IDs are case-sensitive. Run npx skill-creator validate-pack to see which specific activities have mismatched references.

Dependency resolver reports circular dependencies

Cause: Two or more modules list each other as prerequisites, creating a cycle that cannot be resolved.

Solution: Review the prerequisite_modules fields in your modules. Draw the dependency graph on paper — each arrow should point in one direction (from prerequisite to dependent). Break the cycle by removing one direction of the dependency or merging the circular modules into a single module.

Pathway adapter generates excessive reinforcement activities

Cause: The struggle threshold (default: 50) may be too high for your subject, causing the adapter to treat normal learning challenges as failures.

Solution: Lower the struggleThreshold in the adapter configuration. For technically demanding subjects where initial low scores are expected, a threshold of 30-40 may be more appropriate. Also check the maxReinforcementActivities setting (default: 3) and reduce it if learners report feeling stuck in reinforcement loops.

Pattern detector reports no patterns despite sufficient observation data

Cause: Either the observation stream is not properly connected, or the minimum evidence count is not being met.

Solution: Verify that the ObservationEmitter is receiving events by checking the session JSONL file. Ensure at least 3 learners have completed the same module sequence — patterns require multiple observations to achieve confidence above the threshold. For pilot deployments with few learners, temporarily lower the minimum evidence count.

Learners see content at the wrong difficulty level

Cause: The grade router selects content based on the grade_levels field in modules and activities. If grade levels are not set correctly, content may be routed to the wrong audience.

Solution: Review the grade_levels arrays in your modules and ensure they match the grade_levels defined at the pack level. For professional education packs, use custom level labels ("beginner", "intermediate", "advanced") rather than K-12 grade designations.

What's Next