Update Training Materials Skill

Audit training materials against the official Claude Code changelog to find stale references, missing feature coverage, and legacy content. Optionally fix all issues in parallel.

Usage

/update-training                          # Scan only (audit report, no changes)
/update-training --fix                    # Scan and fix all issues
/update-training --fix --severity error   # Scan and fix only errors
/update-training --dry-run                # Show what would be fixed without applying
/update-training 2.0.0-2.1.37            # Audit only changes in version range
/update-training --focus docs             # Limit scan to docs/ only
/update-training --focus examples        # Limit scan to examples/ only

Arguments

[version-range]

2.0.0-2.1.37

--fix

--severity <level>

error

warning

info

--dry-run

--focus <area>

docs

examples

all

Default behavior: Scan only — display audit report without modifying files.

--fix

Architecture

Three specialized agents work in phases:

Orchestration Flow

/update-training [version-range] [--fix] [--severity <level>] [--dry-run] [--focus <area>]
       │
       ▼
  1. PARSE: Extract arguments and flags
       │
       ▼
  2. FETCH: Spawn 1x changelog-auditor agent
       │    - Fetches official CHANGELOG.md
       │    - Parses into structured JSON
       │    - Filters by version-range if specified
       │    - Output: {versions[], stale_patterns[], new_features[]}
       │
       ▼
  3. DISCOVER: Glob training files based on --focus flag
       │
       ▼
  4. GROUP: Split files into 10 groups by directory/topic proximity
       │
       ▼
  5. SCAN: Spawn 10x training-scanner agents IN PARALLEL
       │    - Input: assigned file group + parsed changelog
       │    - Output: JSON findings array per agent
       │
       ▼
  6. CONSOLIDATE: Merge and deduplicate all scanner findings
       │
       ├── No --fix → Exit with audit report
       │
       └── --fix →
       │
       ▼
  7. FILTER: Apply --severity filter to findings
       │
       ▼
  8. FIX: Spawn 10x training-fixer agents IN PARALLEL
       │    - If --dry-run: report what would change
       │    - Otherwise: apply targeted edits
       │
       ▼
  9. DISPLAY: Show fix summary with counts

Instructions

Step 1: Parse Arguments

Extract from the user's command:

• version_range

  : positional argument matching pattern

  N.N.N-N.N.N

  (or null for all versions)

• fix_mode

  : true if

  --fix

  is present

• severity_filter

  : value after

  --severity

  (or null to include all severities)

• dry_run

  : true if

  --dry-run

  is present

• focus_area

  : value after

  --focus

  (or

  all

  )

If

--dry-run

fix_mode

Step 2: Fetch and Parse Changelog

Spawn 1 changelog-auditor agent.

Use

subagent_type: "changelog-auditor"

Agent Prompt:

Audit the official Claude Code changelog.

Version range filter: {version_range or "all versions"}

Fetch the changelog from:
https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md

Parse ALL entries and return structured JSON with:
- versions[] - all version entries with their changes
- stale_patterns[] - outdated references with replacements
- new_features[] - significant new features for training coverage
- deprecations[] - deprecated features
- removals[] - removed features
- renames[] - renamed features/paths
- breaking_changes[] - breaking changes

Output the full JSON object as specified in your agent instructions.

Wait for the agent to complete. Extract the parsed changelog JSON from its response.

Step 3: Discover Training Files

Use Glob to find training files based on the

focus_area

all

docs/*.md

examples/**/*.md

docs

docs/*.md

examples

examples/**/*.md

Collect all matching file paths.

Step 4: Split Files into 10 Groups

Split discovered files into exactly 10 groups using directory/topic proximity:

Grouping Algorithm:

1. Sort files by directory then filename to cluster related files
2. Group by directory first: files in the same directory stay together
3. Distribute evenly: aim for roughly equal file counts per group
4. Name each group based on the primary directory/topic of its files

If fewer than 10 files exist, use fewer groups (one file per group minimum).

Group Structure:

{
  "groups": [
    {
      "id": 1,
      "name": "core-docs-01-10",
      "files": ["docs/01-what-is-claude-code.md", "docs/02-installation.md", ...]
    },
    {
      "id": 2,
      "name": "core-docs-11-20",
      "files": ["docs/11-hooks.md", "docs/12-permissions.md", ...]
    }
  ]
}

Step 5: Spawn Parallel Scanner Agents

CRITICAL: Spawn all 10 scanner agents in a SINGLE message with 10 Task tool calls.

Use

subagent_type: "training-scanner"

Agent Prompt Template:

Scan training materials in GROUP {N}: {group_name}

ASSIGNED FILES:
{list of file paths, one per line}

CHANGELOG DATA:
{full parsed changelog JSON from Step 2}

Scan each file for:
1. STALE references - outdated patterns from stale_patterns list
2. MISSING coverage - new features from new_features list not covered where relevant
3. LEGACY content - removed/deprecated features still presented as current

Output JSON with findings array as specified in your agent instructions.

Wait for ALL scanner agents to complete. Collect all responses.

Step 6: Consolidate Scanner Results

After all scanner agents complete, merge and deduplicate findings:

1. Collect: Extract the JSON findings from each agent response
2. Concatenate: Merge all findings arrays into one
3. Deduplicate: Remove duplicates by (file, line, description) tuple, keeping highest severity
4. Re-number: Assign sequential IDs per type (STALE-001, STALE-002, etc.)
5. Sort: By severity (error > warning > info), then file path, then line number

Track consolidation stats:

• raw_findings

  : Total findings before dedup

• after_dedup

  : Final deduplicated count

• dedup_rate

  : Percentage reduction

Step 7: Display Audit Report

Display the consolidated results:

Training Materials Audit Report
================================

Scan Summary:
  Files scanned: 45
  Groups: 10
  Scanner agents: 10

Consolidation:
  Raw findings: 80
  After dedup: 35 (56% dedup rate)

Summary:
  Total findings: 35
  Errors: 5
  Warnings: 20
  Info: 10

By Type:
  Stale references: 12
  Missing coverage: 15
  Legacy content: 8

Findings:
---------
[ERROR] STALE-001 (docs/02-installation.md:35)
  References ~/.claude.json which was moved to ~/.claude/settings.json
  Evidence: "Edit your `~/.claude.json` to configure..."
  Fix: Replace `~/.claude.json` with `~/.claude/settings.json`

[ERROR] LEGACY-001 (docs/10-settings.md:42)
  Shows 'claude config' command which was deprecated in v1.0.7
  Evidence: "Run `claude config set theme dark` to change..."
  Fix: Replace with direct settings.json editing instructions

[WARNING] MISSING-001 (docs/05-hooks.md)
  New hook event 'notification' not covered in hooks documentation
  Fix: Add section covering the notification hook event added in v2.1.0
...

If

--fix

If

--fix

Step 8: Filter Findings by Severity

Apply the

--severity

--severity

error

warning

info

Group filtered findings by file, then reassign to the original 10 groups for parallel fixing.

Step 9: Spawn Parallel Fixer Agents

CRITICAL: Spawn all fixer agents in a SINGLE message with multiple Task tool calls.

Only spawn fixer agents for groups that have findings after filtering. Use

subagent_type: "training-fixer"

Agent Prompt Template:

Fix training material issues in GROUP {N}: {group_name}

DRY RUN: {true|false}

FINDINGS TO FIX:
{JSON array of findings for this group's files}

For each finding:
1. Read the file and verify the issue still exists
2. Apply the suggested fix with minimal changes
3. Record the result (applied or skipped with reason)

{If dry run: "DO NOT apply any changes. Only report what would be changed."}

Output JSON with fixes_applied and fixes_skipped arrays as specified in your agent instructions.

Wait for ALL fixer agents to complete. Collect all responses.

Step 10: Display Fix Summary

Fix Summary
===========

{If dry run: "DRY RUN - No changes were applied"}

Applied ({count}):
  STALE-001: Replaced ~/.claude.json with ~/.claude/settings.json in docs/02-installation.md
  LEGACY-001: Updated 'claude config' to settings.json editing in docs/10-settings.md
  ...

Skipped ({count}):
  MISSING-001: No clear section to add notification hook coverage (docs/05-hooks.md)
  ...

Totals:
  Findings processed: 35
  Fixes applied: 28
  Fixes skipped: 7

Error Handling

• If the changelog fetch fails, report the error and stop
• If any scanner agent fails, continue with results from others and note the failure
• If any fixer agent fails, continue with others and report failures
• If an agent returns invalid JSON, skip that agent's output and continue
• If grouping produces fewer than 10 groups (not enough files), use as many groups as there are files
• Always display partial results even if some agents fail