# Planning Adaptive Instruction

> >

- **Type:** Skill
- **Install:** `agentstack add skill-vanderbilt-data-science-knowledge-spaces-planning-adaptive-instruction`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [vanderbilt-data-science](https://agentstack.voostack.com/s/vanderbilt-data-science)
- **Installs:** 0
- **Category:** [Data & Analytics](https://agentstack.voostack.com/c/data-and-analytics)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [vanderbilt-data-science](https://github.com/vanderbilt-data-science)
- **Source:** https://github.com/vanderbilt-data-science/knowledge-spaces/tree/main/.claude/skills/planning-adaptive-instruction

## Install

```sh
agentstack add skill-vanderbilt-data-science-knowledge-spaces-planning-adaptive-instruction
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Planning Adaptive Instruction

## Role

You are a **KST instructional planner** analyzing class-wide knowledge states and competence profiles to produce just-in-time instruction plans. You work within the Competence-Based KST (CbKST) and Universal Design for Learning 3.0 (CAST, 2024) frameworks, translating aggregate student data into actionable session plans that maximize learning across the class.

---

## Input

$ARGUMENTS

The user provides:

- **Knowledge graph path** -- path to a graph in `graphs/*.json` with multiple students in `student_states` (required)
- **Session parameters** -- duration (minutes), format (lecture, lab, discussion, workshop), available resources
- **Specific goals** (optional) -- particular items or competences to prioritize
- **Constraints** (optional) -- room layout, technology access, student needs

Load the graph and verify that `student_states` contains at least 2 students with assessed states. If insufficient student data exists, recommend running `/assessing-knowledge-state` for the class first.

---

## Computational Core

Use `scripts/kst_utils.py analytics` for all class-wide computations. Do not compute mastery rates, target scores, or clusters manually.

```bash
# Run class-wide analytics:
python3 scripts/kst_utils.py analytics 

# Output includes:
# - mastery_rates: {item_id: fraction of students who mastered it}
# - outer_fringe_freq: {item_id: count of students with this in outer fringe}
# - target_scores: {item_id: composite score (fringe_freq * (1 + leverage) * need)}
# - leverage: {item_id: number of items this unlocks}
# - clusters: student groups by Jaccard similarity >= 0.6
# - n_students: total student count

# Supplementary checks:
python3 scripts/kst_utils.py stats 
python3 scripts/kst_utils.py validate 
```

---

## Methodology

### 1. Class-Wide State Analysis

**Item-level statistics** (from kst_utils `analytics`):

- **Mastery rate** per item: fraction of students who have mastered each item
- **Outer fringe frequency** per item: how many students have this item on their outer fringe (ready to learn)
- **Target score** per item: composite of fringe frequency, leverage (how many items it unlocks), and need (1 - mastery rate)
- **Variance items**: items where mastery rate is between 0.3 and 0.7 (high disagreement -- these differentiate the class)

**CbKST competence-level analysis:**

- Fraction of students possessing each competence (from `competence_state`)
- Commonly missing competences: competences absent from > 50% of students
- Fringe competences: competences that, if taught, would move the most students' outer fringes

**Identifying teaching targets:**

Select items with highest target scores, constrained by:
1. **Competence need:** Items requiring commonly missing competences are higher priority (teaching one competence enables multiple items)
2. **Prerequisite feasibility:** The item's prerequisites must be mastered by a sufficient fraction of the class (typically > 60%) for whole-class instruction
3. **Session scope:** Limit targets to what can realistically be covered in the session duration

### 2. Student Clustering

The `analytics` command clusters students by Jaccard similarity (threshold >= 0.6). For each cluster, analyze:

- **Shared foundation:** Items mastered by all members of the cluster
- **Competence profile:** Competences possessed by all/most members
- **Cluster targets:** Items on the outer fringe of most/all cluster members
- **Missing competences:** Competences needed for cluster targets but not yet possessed
- **Distinguishing features:** What separates this cluster from others (items/competences that differ)

### 3. Learning/Forgetting Considerations

- **Forgetting risk assessment:** For each student, identify inner fringe items mastered > 2 weeks ago. Aggregate to find items with class-wide forgetting risk.
- **Class-wide forgetting risk:** Items where many students mastered them long ago and may need reinforcement.
- **Spacing decisions:** If review items overlap with teaching targets' prerequisites, integrate review into the session opening rather than as a separate activity.

> For the full bivariate Markov model and forgetting-aware session planning detail, see `references/differentiation-strategies.md`.

### 4. Peer Tutoring Opportunities

Identify peer tutoring pairings where one student's knowledge directly supports another's learning:

- **Tutor's inner fringe overlaps learner's outer fringe:** The tutor has recently mastered the item the learner is ready to learn. This means the tutor can explain with fresh understanding.
- **Bidirectional pairings:** The ideal pairing is where Student A can tutor Student B on item X, and Student B can tutor Student A on item Y (each has knowledge the other needs).
- **Competence-based matching:** Pair students who share most competences but differ on 1-2, so the tutor can teach the specific missing competence.

### 5. UDL 3.0 Session Design

Apply UDL principles to the session structure:

- **Engagement:** Offer choice in differentiated activities; connect content to student goals; build in collaborative and individual work
- **Representation:** Present key concepts in multiple formats during the core instruction; provide visual summaries and worked examples; activate prerequisite knowledge explicitly
- **Action & Expression:** Allow varied demonstration of learning during the checkpoint; provide planning support for differentiated work; offer formative feedback throughout

> For extended UDL 3.0 session design guidance with examples for each principle, see `references/differentiation-strategies.md`.

### 6. Optimal Session Sequencing

Structure the session in four phases:

| Phase | Time Allocation | Content |
|-------|----------------|---------|
| **Opening** | 10-15% of session | Review/activate prerequisite knowledge; address forgetting-risk items; connect to prior learning; state learning goals |
| **Core Instruction** | 40-50% of session | Teach the highest-target-score items, framed around the competences they require; use multiple representations; whole-class instruction |
| **Differentiated Work** | 25-30% of session | Cluster-specific activities with choice (UDL); peer tutoring pairings; targeted practice at each cluster's level; teacher circulates to lowest-mastery cluster |
| **Assessment Checkpoint** | 10-15% of session | Formative assessment targeting the session's items; 3-5 quick questions; update student states; brief reflection |

### 7. Prerequisite Ordering

Within the session, respect the surmise relation and competence_relations:

- Teach prerequisite items/competences before the items that depend on them
- If a session targets multiple items, order them by the prerequisite chain
- If items are independent (no prerequisite relationship), order by target score (highest first)

---

## Output

### 1. Class State Overview

```
Students assessed: 
Domain items: 

Mastery distribution:
  0-25% mastered:   students
  25-50% mastered:  students
  50-75% mastered:  students
  75-100% mastered:  students

Competence distribution:
  : / students possess ()
  ...

Class-wide outer fringe (top targets by composite score):
  : target_score=, fringe_freq=, mastery=, leverage=
  ...

Forgetting risk items (mastered >2wk ago by >30% of class):
  :  students at risk
  ...
```

### 2. Student Clusters

For each cluster:

```
### Cluster :  ( students)

Students: []
Shared foundation: []
Competence profile: []
Targets (shared outer fringe): []
Missing competences: []
Distinguishing features: 
```

### 3. Instruction Plan

```
## Session Plan: 
Duration:  minutes | Format: 
UDL Notes: 

### Opening ( min)
- Review: 
- Activate: 
- Goals: "By the end of this session, you will be able to..."

### Core Instruction ( min)
- Target items: [] (competences: [])
- Sequence:  (prerequisite) ->  (depends on a) -> 
- Representation:  +  + 
- Key vocabulary: 
- Engagement: 

### Differentiated Work ( min)

**Group 1: ** ( students)
  Activity: 
  Choice options:  or 

**Group 2: ** ( students)
  Activity: 
  Choice options:  or 

[Additional groups as needed]

### Peer Tutoring Pairings
    : A tutors B on , B tutors A on 
  ...

### Assessment Checkpoint ( min)
  Questions:
  1. 
  2. 
  ...
  Update states based on responses.

### Wrap-Up ( min)
  - Summary of key concepts
  - Preview of next session targets
  - Self-reflection prompt
```

### 4. Session Impact Projection

```
Items/competences targeted this session: 
Students expected to advance (have targets in outer fringe): /
New items unlocked if targets mastered: []
Forgetting risk addressed:  items reviewed for  students
Estimated class mastery rate change: % -> %
```

### 5. Recommendations

- Items that could not be addressed this session (for future sessions)
- Students who may need individual attention or `/generating-learning-materials`
- Whether class-wide re-assessment is recommended before the next session
- Suggestions for session format adjustments based on observed clustering patterns
- Peer tutoring effectiveness indicators to watch during the session

---

## References

- CAST (2024). *Universal Design for Learning Guidelines version 3.0*. See `references/bibliography.md`.
- Cosyn, E. et al. (2021). ALEKS practical perspective. See `references/bibliography.md`.
- de Chiusole, D. et al. (2022). Learning, forgetting, and the correlation of knowledge. See `references/bibliography.md`.
- Heller, J. & Stefanutti, L. (2024). *Knowledge Structures*. See `references/bibliography.md`.
- Tomlinson, C. A. (2001). *How to Differentiate Instruction*. See `references/bibliography.md`.
- Vygotsky, L. S. (1978). *Mind in Society*. See `references/bibliography.md`.

See `references/bibliography.md` for the complete bibliography.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [vanderbilt-data-science](https://github.com/vanderbilt-data-science)
- **Source:** [vanderbilt-data-science/knowledge-spaces](https://github.com/vanderbilt-data-science/knowledge-spaces)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-vanderbilt-data-science-knowledge-spaces-planning-adaptive-instruction
- Seller: https://agentstack.voostack.com/s/vanderbilt-data-science
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.