--- name: diagram-reports-generator description: Generates a status report of all diagrams and MicroSims across an intelligent textbook's chapters, including difficulty, Bloom's level, and UI complexity. Use to audit visualization coverage before a content review. model: haiku license: title: diagram-reports-generator canonical_url: https://skilld.dev/gh/dmccreary/ibook-skills/diagram-reports-generator last_updated: 2026-09-22T04:17:17.000Z --- > Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt) > **Skill from skilld.dev.** Follow the user's requested action. > If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it. > Otherwise, follow the instructions below for this session. You do not need to install anything. > > Supporting files, fetch one when the Skill refers to it: [scripts/diagram-report.py](https://skilld.dev/api/skills-raw/dmccreary/ibook-skills/diagram-reports-generator/scripts/diagram-report.py). > > If the user asked to install this Skill, run `npx skilld install dmccreary/ibook-skills/diagram-reports-generator`. Install writes the Skill files into the project, so every session loads them. > > ## Fork workflow > > A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation. > 1. Check `./skills/diagram-reports-generator`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target. > 2. Read [source metadata](https://skilld.dev/api/v1/skills/dmccreary/ibook-skills/diagram-reports-generator) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit. > 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call: > > ```sh > git init --quiet "$temporary_dir" > git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit" > git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD > ``` > > Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop. > 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/diagram-reports-generator`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md. > Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical. > 5. In the project root, run `skilld install ./skills/diagram-reports-generator --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/diagram-reports-generator --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure. > 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks. # Diagram Reports Generator ## Overview This skill automatically generates comprehensive reports of all diagrams and MicroSims in the geometry course by analyzing chapter markdown files. It creates two report files: a table view for quick reference and a detailed view organized by chapter. ## When to Use This Skill Use this skill when: - Working with the geometry-course intelligent textbook project - Needing to audit all diagrams and MicroSims across chapters - Tracking implementation status of visual elements - Analyzing complexity and Bloom's Taxonomy distribution - Updating documentation after adding new diagrams or MicroSims - Generating reports for instructors or content creators ## Workflow ### Step 1: Install the Diagram Report Generator Script If the project does not already have the diagram report generator script, install it from the skill's bundled resources: 1. Check if `src/diagram-reports/diagram-report.py` exists in the project 2. If it doesn't exist: - Create the directory: `mkdir -p src/diagram-reports` - Copy the script from this skill's `scripts/diagram-report.py` to `src/diagram-reports/diagram-report.py` 3. If it already exists, verify it's up to date (optionally show the user a diff if there are differences) Example installation: ```bash # Create directory if needed mkdir -p src/diagram-reports # Copy script from skill (use Read tool to get script content, then Write tool to create file) # The script is located in this skill's scripts/diagram-report.py ``` ### Step 2: Verify Project Structure Before running the report generator, verify the project structure: 1. Confirm the current working directory is the geometry-course root (or any intelligent textbook project) 2. Verify `docs/chapters/` contains chapter directories (format: `01-chapter-name`, `02-chapter-name`, etc.) 3. Ensure `docs/learning-graph/` directory exists for output ### Step 3: Run the Report Generator Execute the Python script to generate the reports: ```bash python src/diagram-reports/diagram-report.py ``` The script will: - Scan all chapter directories in `docs/chapters/` - Parse each chapter's `index.md` file - Extract diagram and MicroSim specifications from `
` blocks with "#### Diagram:" headers - Analyze each element for: - Type (diagram or MicroSim) - Status (implementation status if specified) - Bloom's Taxonomy levels - UI element count - Estimated difficulty (Easy, Medium, Hard, Very Hard) - Learning objectives ### Step 4: Verify Generated Reports After running the script, verify two files were created in `docs/learning-graph/`: 1. **diagram-table.md** - A sortable table view with columns: - Chapter number - Element title (with links to chapter sections) - Status - Type (Diagram/MicroSim) - Bloom's Taxonomy levels - UI elements count - Difficulty rating 2. **diagram-details.md** - A detailed view organized by chapter with: - Chapter-level summaries - Full element descriptions - Learning objectives - Linked titles to source chapter sections ### Step 5: Review Navigation Configuration The generated reports should already be linked in the MkDocs navigation. Verify the `mkdocs.yml` file contains these entries under the "Learning Graph" section: ```yaml - Learning Graph: - Diagrams Table: learning-graph/diagram-table.md - Diagrams Details: learning-graph/diagram-details.md ``` If these entries are missing, add them to the navigation structure. ### Step 6: Preview the Reports To view the generated reports: 1. Run `mkdocs serve` to start the local development server 2. Navigate to the "Learning Graph" section 3. Click on "Diagrams Table" or "Diagrams Details" 4. Verify all diagrams and MicroSims are properly listed with accurate information ## Understanding Report Output ### Difficulty Estimation The script estimates difficulty based on: - **Element Type**: MicroSims start with higher base difficulty - **UI Complexity**: Number of sliders, buttons, dropdowns, and other controls - **Features**: Animation, rotation, 3D/isometric views, real-time calculations - **Canvas Size**: Larger canvases increase complexity Difficulty levels: - **Easy**: Static diagrams or simple visualizations - **Medium**: Basic interactivity with 1-3 UI elements - **Hard**: Moderate interactivity with 4-6 UI elements or complex features - **Very Hard**: High interactivity with many UI elements or advanced features ### Bloom's Taxonomy Detection The script automatically detects Bloom's Taxonomy levels mentioned in specifications: - Remembering - Understanding - Applying - Analyzing - Evaluating - Creating ## Troubleshooting ### No Elements Found If the report shows zero elements: - Verify chapter markdown files contain `#### Diagram:` headers followed by `
` blocks - Check that `
` blocks include specification content - Run with verbose flag: `python src/diagram-reports/diagram-report.py --verbose` ### Missing Information If elements are missing type, status, or other fields: - Review the `
` block format in chapter files - Ensure specifications include `**Type:**`, `**Status:**`, and `**Learning Objective:**` fields - The script will infer type from content if not explicitly specified ### Broken Links in Reports If chapter links don't work: - Verify chapter directory naming follows the pattern: `##-descriptive-name` - Check that MkDocs anchor generation matches the script's anchor creation logic - Test links by navigating in the served site ## Advanced Usage ### Custom Output Location Specify a different output directory: ```bash python src/diagram-reports/diagram-report.py --output-dir /path/to/output ``` ### Generate CSV Format For spreadsheet analysis: ```bash python src/diagram-reports/diagram-report.py --format csv ``` ### Generate HTML Format For standalone HTML reports: ```bash python src/diagram-reports/diagram-report.py --format html ``` ### Verbose Output for Debugging Enable detailed logging: ```bash python src/diagram-reports/diagram-report.py --verbose ``` ## Integration with Intelligent Textbook Workflow This skill integrates with the broader intelligent textbook creation workflow: 1. **After content creation**: Run this skill after generating or updating chapter content 2. **Before review sessions**: Generate reports to identify gaps or inconsistencies 3. **During planning**: Use difficulty distribution to balance implementation effort 4. **For documentation**: Include reports in instructor guides or project documentation ## Bundled Resources ### scripts/diagram-report.py This skill includes the complete Python script for generating diagram and MicroSim reports. The script will be installed into the user's project at `src/diagram-reports/diagram-report.py` when the skill is first used. The script: - Analyzes all chapter markdown files in `docs/chapters/` - Extracts diagram and MicroSim specifications from `
` blocks - Calculates difficulty estimates based on UI complexity and features - Detects Bloom's Taxonomy levels from specification text - Generates both table and detailed report formats - Supports multiple output formats (markdown, CSV, HTML)