Microsim Matcher

MicroSim Matcher

Overview

This skill analyzes diagram, chart, or simulation specifications and recommends the most appropriate MicroSim generator skill(s) to use. It evaluates the specification against the capabilities of all 9 available MicroSim generators and returns a ranked list with match scores (0-100) and detailed reasoning.

Purpose

When creating educational MicroSims, choosing the right generator is critical for success. This skill automates the matching process by:

1. Analyzing the characteristics of the desired visualization 2. Comparing against capabilities of all MicroSim generators 3. Scoring each generator on a 0-100 scale 4. Providing ranked recommendations with clear reasoning

This helps users quickly identify the best tool for their needs without manually comparing all generator options.

When to Use This Skill

Invoke this skill when:

• User has a diagram or visualization specification and needs to know which generator to use
• User describes a desired MicroSim but hasn't specified a generator
• User asks "Which MicroSim generator should I use for...?"
• User needs to compare multiple generator options
• You need to recommend the best generator for a given specification

Available MicroSim Generators

The skill evaluates matches against these 9 generators:

1. microsim-p5 - General p5.js simulations and custom animations 2. chartjs-generator - Standard statistical charts (bar, line, pie, etc.) 3. math-function-plotter-plotly - Mathematical function plots with Plotly.js 4. mermaid-generator - Flowcharts, diagrams, and workflows 5. vis-network - Network graphs with nodes and edges 6. timeline-generator - Chronological timelines with events 7. map-generator - Geographic visualizations with Leaflet.js 8. venn-diagram-generator - Set relationship diagrams (2-4 sets) 9. bubble-chart-generator - Priority matrices and multi-dimensional comparisons

Detailed capabilities for each generator are documented in references/matching-criteria.md.

Workflow

Follow these 7 steps to match a specification to the best MicroSim generator(s):

Step 0: Check for Reference File Updates (Version Check)

IMPORTANT: Before analyzing the specification, verify that the local matching-criteria.md file is up-to-date with the latest version on GitHub. An outdated reference file will lead to poor recommendations.

Version Check Process:

1. Get local file timestamp:

   stat -f "%Sm" -t "%Y-%m-%d %H:%M:%S" skills/microsim-matcher/references/matching-criteria.md
   # On Linux: stat -c "%y" skills/microsim-matcher/references/matching-criteria.md

2. Check GitHub version using the GitHub API:

   curl -s https://api.github.com/repos/dmccreary/claude-skills/commits?path=skills/microsim-matcher/references/matching-criteria.md&page=1&per_page=1 | grep -o '"date": "[^"]*"' | head -1

3. Compare timestamps:

• If GitHub version is newer → WARNING: Reference file may be outdated
• If local version is current → Proceed with confidence

Automated Check (Optional):

A Python script is available in skills/microsim-matcher/scripts/check-version.py to automate this check.

If Reference File is Outdated:

Display a prominent warning to the user:

⚠️  WARNING: Reference File May Be Outdated

Your local matching-criteria.md file was last modified on [LOCAL_DATE].
The GitHub repository has a newer version from [GITHUB_DATE].

This may result in:
- Missing information about new MicroSim generators
- Outdated scoring guidelines
- Incorrect recommendations

Recommended actions:
1. Update your local copy:
   git pull origin main

2. Or download the latest version:
   https://github.com/dmccreary/claude-skills/blob/main/skills/microsim-matcher/references/matching-criteria.md

3. Or continue with potentially outdated information (not recommended)

Continue anyway? [Proceed if user confirms]

When to Skip Version Check:

• No internet connection available
• User explicitly requests to skip (with understanding of risks)
• Working in an isolated/offline environment

Version Check Frequency:

• Always check when skill is invoked
• Cache result for 24 hours to avoid repeated API calls
• Re-check if more than 24 hours since last check

Step 1: Read and Parse the Diagram Specification

Read the specification file provided by the user. The specification may be in various formats:

• Plain text description
• Structured markdown
• JSON/YAML data
• Requirements list
• User conversation describing the need

Extract the following information:

• Visual type: Chart, diagram, plot, map, timeline, network, simulation, animation
• Data type: Numerical, categorical, temporal, geographic, relational, mathematical, structural
• Data source: What kind of data will be visualized (events, functions, nodes/edges, coordinates, sets, etc.)
• Interactivity needs: Static, hover tooltips, click actions, drag, sliders, real-time updates
• Explicit mentions: Does the spec mention specific tools (p5.js, Plotly, Mermaid, etc.)?
• Domain/context: Educational subject area (math, history, science, CS, business, etc.)

Step 2: Extract Key Characteristics

Analyze the specification and identify:

Primary Characteristics:

1. Temporal: Does it involve dates, chronological events, or time-based sequences?

• Keywords: "timeline", "chronological", "dates", "events", "history", "schedule"

2. Geographic: Does it involve locations, coordinates, or maps?

• Keywords: "map", "location", "coordinates", "latitude", "longitude", "geographic"

3. Mathematical: Does it involve mathematical functions or equations?

• Keywords: "function", "f(x)", "equation", "plot", "calculus", "trigonometric"

4. Network/Graph: Does it involve nodes, edges, or network relationships?

• Keywords: "network", "graph", "nodes", "edges", "connections", "dependencies"

5. Process/Flow: Does it show workflows, processes, or state transitions?

• Keywords: "flowchart", "workflow", "process", "state machine", "sequence diagram"

6. Set-based: Does it compare sets with overlaps and intersections?

• Keywords: "venn", "sets", "overlap", "intersection", "categories"

7. Statistical/Data: Does it visualize numerical or categorical data as charts?

• Keywords: "chart", "bar", "line", "pie", "statistics", "data", "compare"

8. Priority/Matrix: Does it show 2D priority or decision matrix?

• Keywords: "priority", "impact vs effort", "matrix", "quadrant", "bubble"

9. Custom/Unique: Does it require custom animations or unique visualizations?

• Keywords: "animation", "simulation", "custom", "interactive", "p5.js"

Secondary Characteristics:

• Complexity level: Simple (1-10 items) vs. Complex (100+ items)
• Interactivity requirements: Passive viewing vs. Active manipulation
• Educational features: Lesson plans, assessments, tooltips with definitions
• Responsiveness needs: Desktop only vs. Mobile-friendly required

Step 3: Load MicroSim Generator Capabilities

Read the matching criteria from references/matching-criteria.md. This file contains:

• Detailed profiles for all 9 generators
• Primary use cases and strengths
• Data type requirements
• Interactivity capabilities
• Trigger words and phrases
• Scoring guidelines (when to score high vs. low)
• Limitations and caveats

Load additional details if needed:

• Review /docs/skill-descriptions/microsims/index.md for overview
• Read detailed skill descriptions in /docs/skill-descriptions/microsims/[generator-name].md
• Check full workflows in /skills/[generator-name]/SKILL.md

Step 4: Score Each MicroSim Generator

For each of the 9 generators, assign a match score from 0-100 using this scale:

Scoring Scale:

• 90-100: Perfect match - Primary use case for this generator
• 70-89: Strong match - Well-suited, minor limitations
• 50-69: Moderate match - Could work but not optimal
• 30-49: Weak match - Significant limitations or workarounds needed
• 0-29: Poor match - Not recommended, use different generator

Scoring Methodology:

For each generator, evaluate:

1. Data Type Match (40 points max)

• Does the specification's data type align with what the generator expects?
• Perfect match: 40 points
• Partial match: 20-35 points
• Poor match: 0-15 points

2. Interactivity Match (25 points max)

• Do the interactivity requirements match the generator's capabilities?
• Perfect match: 25 points
• Partial match: 10-20 points
• Poor match: 0-5 points

3. Visual Style Match (25 points max)

• Does the desired visual output align with the generator's strengths?
• Perfect match: 25 points
• Partial match: 10-20 points
• Poor match: 0-5 points

4. Trigger Word Bonus (10 points max)

• Specification contains strong trigger words for this generator: +10 points
• Specification contains weak trigger words: +5 points
• No trigger words: 0 points

Example Scoring:

Specification: "Timeline showing product development milestones from 2020-2025"

timeline-generator scoring:

• Data Type Match: 40/40 (temporal data with dates - perfect match)
• Interactivity Match: 25/25 (needs zoom/pan/click - perfect match)
• Visual Style Match: 25/25 (timeline visual - perfect match)
• Trigger Words: +10 (contains "timeline" and "milestones")
• Total: 100/100

chartjs-generator scoring:

• Data Type Match: 15/40 (temporal data, but chartjs not optimized for timelines)
• Interactivity Match: 10/25 (basic interactivity, lacks timeline-specific features)
• Visual Style Match: 10/25 (could show as line chart, but not ideal)
• Trigger Words: 0 (no chart-related words)
• Total: 35/100

Step 5: Rank Generators by Score

Sort the 9 generators from highest to lowest score.

Ranking Guidelines:

• Include top 3-5 generators minimum in the output
• Always include at least one generator with score ≥ 70 if possible
• Show a range of scores to help user understand alternatives
• Include lower scores (30-50 range) to show what NOT to use
• Omit scores below 30 unless specifically relevant

If no generator scores above 70, this may indicate:

• Specification is unclear or incomplete
• Specification requires multiple MicroSims
• Specification needs custom development outside existing generators

Step 6: Format Output with Reasoning

Present the results as a numbered list with the following format for each generator:

## MicroSim Generator Recommendations

[Brief summary of specification analysis]

### Ranked Results:

1. **[generator-name]** (Score: [0-100]/100)

   **Reasoning:** [2-4 sentences explaining why this score was assigned. Include:
   - What matches well (data type, interactivity, visual style)
   - Specific features that align with requirements
   - Any limitations or caveats
   - Why this is better/worse than alternatives]

   **Key Features:** [Bullet list of relevant features for this use case]

   **Skill Location:** `skills/[generator-name]/SKILL.md`

2. **[generator-name]** (Score: [0-100]/100)
   [Same format as above]

[Continue for top 3-5 generators]

Output Quality Requirements:

1. Clear reasoning: Each score should be justified with specific features 2. Honest assessment: Don't oversell poor matches 3. Practical guidance: Help user make an informed decision 4. Alternative suggestions: If top choice has limitations, note alternatives 5. Skill locations: Always include path to the full skill file

Example Output:

## MicroSim Generator Recommendations

Your specification describes a "network diagram showing prerequisite relationships between course concepts." This is clearly a network/graph visualization with nodes (concepts) and edges (prerequisites).

### Ranked Results:

1. **vis-network** (Score: 95/100)

   **Reasoning:** This is the primary use case for vis-network. The specification describes nodes (concepts) and edges (prerequisite relationships), which is exactly what vis-network is designed for. The skill supports physics-based layouts that automatically position related concepts, interactive dragging to explore the network, and click events to show concept details. The only minor limitation is that very large networks (500+ concepts) may require performance optimization.

   **Key Features:**
   - Physics-based automatic layout
   - Interactive drag, click, zoom, pan
   - Group/cluster support for organizing concepts by topic
   - Hover tooltips for concept definitions
   - Learning graph JSON format support

   **Skill Location:** `skills/vis-network/SKILL.md`

2. **mermaid-generator** (Score: 70/100)

   **Reasoning:** Mermaid supports flowcharts and graphs that could represent prerequisite relationships. However, Mermaid diagrams are more static compared to vis-network and don't offer the same level of interactivity (no dragging, less dynamic layout). Mermaid would work well for smaller, simpler prerequisite chains but may become cluttered with many concepts. Use this if you prefer a more static, documentation-style diagram.

   **Key Features:**
   - Text-based diagram specification
   - Clean, professional appearance
   - Good for documentation
   - Multiple diagram types available

   **Skill Location:** `skills/mermaid-generator/SKILL.md`

3. **microsim-p5** (Score: 50/100)

   **Reasoning:** While p5.js could create a custom network visualization, it would require significantly more development effort compared to using vis-network, which is specifically designed for this purpose. Only choose p5.js if you need custom animations, unique visual effects, or interactivity patterns not available in vis-network. For standard network diagrams, vis-network is the better choice.

   **Key Features:**
   - Complete customization flexibility
   - Custom animations possible
   - Unique interaction patterns

   **Skill Location:** `skills/microsim-p5/SKILL.md`

4. **chartjs-generator** (Score: 25/100)

   **Reasoning:** Not recommended. ChartJS is designed for statistical charts (bar, line, pie), not network diagrams. There's no way to represent nodes and edges in standard chart types. Use vis-network or mermaid-generator instead.

   **Skill Location:** `skills/chartjs-generator/SKILL.md`

### Recommendation:

Use **vis-network** (Score: 95/100) for your prerequisite relationship diagram. It's specifically designed for this use case and will provide the best user experience with minimal development effort.

Scoring Reference

Quick reference for common specification types:

Best Practices

Be Specific in Reasoning

Good reasoning:

"The specification describes plotting y = sin(x) over the domain [-2π, 2π], which is exactly what math-function-plotter-plotly is designed for. The skill provides interactive sliders to explore points on the curve, hover tooltips showing coordinates, and responsive design. Score: 98/100."

Poor reasoning:

"This looks like a math thing, so use the math plotter. Score: 90/100."

Address Limitations Honestly

Good honesty:

"While chartjs-generator could show temporal data as a line chart (Score: 40/100), it lacks the specialized timeline features (zoom to date ranges, event details panels, category filtering) that make timeline-generator the better choice (Score: 95/100)."

Poor honesty:

"ChartJS can do anything with data, use it. Score: 85/100."

Consider the User's Context

• Educational use: Emphasize lesson plans, tooltips, accessibility
• Technical documentation: Note text-based specs (Mermaid) vs. data-driven (vis-network)
• Student projects: Consider ease of customization and learning curve
• Professional use: Emphasize polish, standard libraries, maintainability

Provide Actionable Guidance

End with a clear recommendation:

Good:

"Recommendation: Use timeline-generator (95/100) for your product roadmap. It's specifically designed for temporal data and will give you the best results with minimal effort."

Less useful:

"These are your scores. Pick one."

Handling Edge Cases

Multiple Visualizations Needed

If the specification requires multiple types of visualizations:

Your specification describes both a timeline of events AND a network graph of relationships. This requires two separate MicroSims:

1. **For the timeline portion:** timeline-generator (Score: 95/100)
2. **For the network portion:** vis-network (Score: 95/100)

Consider creating two separate MicroSims and linking between them in your textbook.

Unclear or Incomplete Specification

If you can't determine a clear match:

The specification is somewhat unclear about the desired visual format. Based on the available information:

**If the focus is on [interpretation A]:**
- Recommended: [generator A] (Score: 80/100)

**If the focus is on [interpretation B]:**
- Recommended: [generator B] (Score: 85/100)

Please clarify: [specific questions to ask]

No Good Match (All Scores Below 70)

If no generator scores above 70:

After analyzing your specification, none of the existing MicroSim generators are an ideal match. Here are your options:

1. **Modify requirements** to fit an existing generator:
   - [suggestion] could work if [modification]

2. **Create custom MicroSim** with microsim-p5:
   - Full flexibility but requires more development
   - Estimated complexity: [assessment]

3. **Split into multiple MicroSims**:
   - Use [generator 1] for [aspect 1]
   - Use [generator 2] for [aspect 2]

Would you like help refining the specification or exploring custom development?

Ambiguous Terminology

"Graph" can mean network graph OR chart. Clarify:

The term "graph" is ambiguous. Please clarify:

- **If you mean a network graph** (nodes and edges): Use vis-network (Score: 95/100)
- **If you mean a chart/plot** (data points): Use chartjs-generator (Score: 90/100) or math-function-plotter-plotly (Score: 90/100)

Common Mistakes to Avoid

1. Don't score everything 50: Show clear winners and losers 2. Don't ignore trigger words: They're strong signals of intent 3. Don't recommend deprecated/unmaintained tools: Note cautions (e.g., venn.js library) 4. Don't skip the reasoning: Scores without explanation aren't helpful 5. Don't forget educational context: MicroSims are for learning, not just visualization 6. Don't overlook existing data: Check if glossary exists for Venn diagram definitions

References

• Matching Criteria: skills/microsim-matcher/references/matching-criteria.md
• Version Check Script: skills/microsim-matcher/scripts/check-version.py
• GitHub Repository: https://github.com/dmccreary/claude-skills
• Reference File on GitHub: https://github.com/dmccreary/claude-skills/blob/main/skills/microsim-matcher/references/matching-criteria.md
• MicroSim Overview: /docs/skill-descriptions/microsims/index.md
• Individual Skill Descriptions: /docs/skill-descriptions/microsims/[generator-name].md
• Full Skill Workflows: /skills/[generator-name]/SKILL.md

Version Check Script Usage

The check-version.py script provides automated version checking:

Basic check (with output):

python skills/microsim-matcher/scripts/check-version.py

Quiet mode (exit code only):

python skills/microsim-matcher/scripts/check-version.py --quiet
echo $?  # 0=up-to-date, 1=outdated, 2=error

Auto-update mode (downloads latest if outdated):

python skills/microsim-matcher/scripts/check-version.py --update

Exit codes:

• 0 - Local file is up-to-date
• 1 - GitHub version is newer (outdated)
• 2 - Error occurred (network, file not found, etc.)

Integration with CI/CD:

# In a pre-commit hook or CI pipeline
if python skills/microsim-matcher/scripts/check-version.py --quiet; then
    echo "✅ Reference file is up-to-date"
else
    echo "⚠️  Reference file is outdated - consider updating"
fi

Skill Maintenance

When New MicroSim Generators Are Added

When new MicroSim generators are added to the repository:

1. Update `references/matching-criteria.md` with the new generator profile:

• Add a new numbered section for the generator
• Include primary use cases and strengths
• Document data types and interactivity capabilities
• List trigger words and scoring guidelines
• Note any limitations or caveats

2. Update this SKILL.md file:

• Add generator to "Available MicroSim Generators" list
• Update generator count (currently 9)
• Add examples of when to recommend the new generator
• Update scoring reference table

3. Test matching:

• Create test specifications that should trigger the new generator
• Verify scoring logic produces expected results
• Ensure reasoning is clear and accurate

4. Commit changes:

• Commit updated files to GitHub
• GitHub API will automatically track the new timestamp
• Users will be notified on next version check

When Existing Generators Are Updated

When existing generators gain new features or capabilities:

1. Update matching criteria for that generator in references/matching-criteria.md 2. Revise scoring guidelines if new features significantly change match quality 3. Update examples to showcase new capabilities 4. Test edge cases where new features might change recommendations

Keeping Reference Files Current

For Repository Maintainers:

After making changes to matching-criteria.md:

# 1. Make your changes
vim skills/microsim-matcher/references/matching-criteria.md

# 2. Commit and push
git add skills/microsim-matcher/references/matching-criteria.md
git commit -m "Update matching criteria: [description of changes]"
git push origin main

# GitHub will automatically update the file timestamp
# Users will be notified via version check on next use

For Skill Users:

Check for updates regularly:

# Option 1: Run version check manually
python skills/microsim-matcher/scripts/check-version.py

# Option 2: Auto-update if outdated
python skills/microsim-matcher/scripts/check-version.py --update

# Option 3: Pull latest from GitHub
git pull origin main

Recommended Update Schedule:

• Before starting a new project: Always check for updates
• Monthly: Run version check even if not actively using
• After seeing announcement of new generators: Immediately update

Version History Best Practices

To help users understand changes:

1. Document changes in commit messages:

   git commit -m "Add support for new scatter-plot-generator (10th generator)"

2. Include change summary at the top of matching-criteria.md:

   ## Recent Updates

   - 2025-11-17: Added math-function-plotter-plotly (9th generator)
   - 2025-11-10: Updated vis-network scoring for large graphs
   - 2025-11-01: Initial release with 8 generators

3. Tag major updates in GitHub:

   git tag -a v1.1 -m "Added 10th generator, updated scoring"
   git push origin v1.1

MicroSim Matcher Skill

Intelligently matches diagram specifications to the most appropriate MicroSim generator skill.

Overview

The microsim-matcher skill analyzes diagram, chart, or simulation specifications and returns a ranked list of recommended MicroSim generator skills with match scores (0-100) and detailed reasoning. This helps users quickly identify the best tool for creating educational visualizations.

Features

• 9 MicroSim Generators Supported: Evaluates all available generators in the repository
• Intelligent Scoring: 0-100 scale based on data type, interactivity, visual style, and trigger words
• Detailed Reasoning: Each recommendation includes clear explanation of score
• Version Checking: Automatically detects if reference files are outdated
• Auto-Update: Optional script flag to download latest matching criteria

Quick Start

Basic Usage

# Invoke the skill through Claude Code
# Provide a diagram specification file or description

Version Check

Before using the skill, check if your reference files are up-to-date:

# Check version
python scripts/check-version.py

# Auto-update if outdated
python scripts/check-version.py --update

File Structure

microsim-matcher/
├── SKILL.md                     # Main skill workflow (7 steps)
├── README.md                    # This file
├── references/
│   └── matching-criteria.md    # Detailed generator profiles (650+ lines)
└── scripts/
    └── check-version.py        # Version checking utility

Supported MicroSim Generators

The skill evaluates matches against these 9 generators:

1. microsim-p5 - Custom animations, simulations (p5.js) 2. chartjs-generator - Statistical charts (bar, line, pie, etc.) 3. math-function-plotter-plotly - Mathematical function plots 4. mermaid-generator - Flowcharts, diagrams, workflows 5. vis-network - Network graphs (nodes/edges) 6. timeline-generator - Chronological timelines 7. map-generator - Geographic visualizations (Leaflet.js) 8. venn-diagram-generator - Set relationships (2-4 sets) 9. bubble-chart-generator - Priority matrices

Scoring Methodology

Each generator receives a score from 0-100 based on:

Score Interpretation:

• 90-100: Perfect match - Primary use case
• 70-89: Strong match - Well-suited
• 50-69: Moderate match - Could work but not optimal
• 30-49: Weak match - Significant limitations
• 0-29: Poor match - Not recommended

Example Output

MicroSim Generator Recommendations:

1. timeline-generator (Score: 98/100)
   Reason: Perfect match for chronological events with specific dates.
   Features zoom, filtering, event details - all requested features.

2. chartjs-generator (Score: 35/100)
   Reason: Could show as line chart but lacks timeline-specific
   features (zoom to dates, event panels, chronological navigation).

3. microsim-p5 (Score: 45/100)
   Reason: Custom development possible but timeline-generator
   provides all features out-of-the-box.

Recommendation: Use timeline-generator (98/100)

Version Checking

Why Version Checking Matters

The matching-criteria.md file contains scoring guidelines for all generators. When new generators are added or existing ones are updated, this file changes. Using outdated criteria can lead to:

• Missing recommendations for new generators
• Incorrect scoring for updated generators
• Poor recommendations overall

How Version Checking Works

The check-version.py script:

1. Gets local file modification timestamp 2. Queries GitHub API for latest commit date 3. Compares timestamps 4. Warns if GitHub version is newer

Version Check Commands

# Basic check (shows output)
python scripts/check-version.py

# Quiet mode (exit code only)
python scripts/check-version.py --quiet
echo $?  # 0=up-to-date, 1=outdated, 2=error

# Auto-update mode
python scripts/check-version.py --update

GitHub API Reference

The script uses this GitHub API endpoint:

https://api.github.com/repos/dmccreary/claude-skills/commits?path=skills/microsim-matcher/references/matching-criteria.md&page=1&per_page=1

Latest reference file:

https://github.com/dmccreary/claude-skills/blob/main/skills/microsim-matcher/references/matching-criteria.md

Workflow Steps

The skill follows a 7-step process:

1. Step 0: Check for reference file updates (version check) 2. Step 1: Read and parse diagram specification 3. Step 2: Extract key characteristics (data type, interactivity, visual style) 4. Step 3: Load MicroSim generator capabilities 5. Step 4: Score each generator (0-100) 6. Step 5: Rank by score (highest first) 7. Step 6: Format output with reasoning

Maintenance

Keeping Files Up-to-Date

For users:

# Check for updates before starting new project
python scripts/check-version.py

# Or pull latest from GitHub
git pull origin main

For maintainers:

When adding new generators: 1. Update references/matching-criteria.md with new generator profile 2. Update SKILL.md generator list (update count from 9) 3. Add to "Recent Updates" section in matching-criteria.md 4. Commit and push to GitHub 5. Users will be notified via version check

Recent Updates

See references/matching-criteria.md for detailed update history.

Troubleshooting

Version Check Fails

Error: "Network error"

• Check internet connection
• GitHub API may be down (try again later)
• Firewall blocking API access

Error: "Local file not found"

• Run from repository root: python skills/microsim-matcher/scripts/check-version.py
• Or navigate to skill directory first

Poor Recommendations

Generator scores seem wrong:

• Check if reference file is outdated (python scripts/check-version.py)
• Update to latest: python scripts/check-version.py --update
• Review specification - may be unclear or ambiguous

Multiple generators score high:

• This is normal for some specifications
• Review reasoning to understand trade-offs
• Consider splitting into multiple MicroSims

Contributing

To add support for a new MicroSim generator:

1. Add generator profile to references/matching-criteria.md:

• Primary use cases
• Data types
• Interactivity level
• Trigger words
• Scoring guidelines (when to score high/low)
• Strengths and limitations

2. Update SKILL.md:

• Add to "Available MicroSim Generators" list
• Update generator count
• Add example recommendations

3. Add to "Recent Updates" section with date

4. Test with sample specifications

5. Submit PR to repository

License

Same license as the claude-skills repository.

References

• Main Skill: SKILL.md
• Matching Criteria: references/matching-criteria.md
• Version Check: scripts/check-version.py
• GitHub Repository: https://github.com/dmccreary/claude-skills
• MicroSim Overview: /docs/skill-descriptions/microsims/index.md

Support

For issues or questions:

• Check GitHub repository issues
• Review MicroSim generator documentation
• Run version check to ensure up-to-date files

MicroSim Generator Matching Criteria

This reference document provides detailed matching criteria for all available MicroSim generator skills. Use this to score and rank which generator best matches a given diagram specification.

Recent Updates

Version Check: This file is version-controlled on GitHub. Use scripts/check-version.py to verify you have the latest version.

• 2025-11-17: Initial release with 9 MicroSim generators
• Added: microsim-p5, chartjs-generator, math-function-plotter-plotly
• Added: mermaid-generator, vis-network, timeline-generator
• Added: map-generator, venn-diagram-generator, bubble-chart-generator
• Included comprehensive scoring guidelines for each generator
• Added decision tree and matching strategy sections

Scoring Scale

• 90-100: Perfect match - Primary use case for this generator
• 70-89: Strong match - Well-suited, minor limitations
• 50-69: Moderate match - Could work but not optimal
• 30-49: Weak match - Significant limitations or workarounds needed
• 0-29: Poor match - Not recommended, use different generator

General Matching Factors

When scoring, consider:

1. Data Type Match: Does the specification's data structure align with what the generator expects? 2. Interactivity Requirements: Does the needed interactivity match the generator's capabilities? 3. Visual Style: Does the desired visual output match the generator's strengths? 4. Complexity: Is the specification within the generator's complexity range? 5. Trigger Words: Does the specification contain keywords strongly associated with this generator?

MicroSim Generator Profiles

1. microsim-p5

Skill Location: skills/microsim-p5/SKILL.md

Primary Use Cases:

• Custom animations and simulations
• Interactive educational visualizations
• Physics simulations
• Generative art and creative coding
• Unique visualizations not served by standard libraries

Data Types:

• Any data type (most flexible)
• Real-time/dynamic data
• Procedural/algorithmic visualizations

Interactivity Level:

• Very High
• Sliders, buttons, mouse tracking
• Real-time parameter changes
• Custom interaction models

Trigger Words/Phrases:

• "animation", "simulation", "interactive"
• "custom visualization", "p5.js", "creative"
• "physics", "movement", "bouncing", "particles"
• "generative", "procedural", "algorithmic"

Scoring Guidelines:

• Score 90-100 if: Specification requires custom animations, physics simulations, unique interactions not available in standard libraries, real-time updates, or mentions p5.js
• Score 70-89 if: Needs high interactivity with custom controls, visual effects, or creative visual style
• Score 50-69 if: Standard visualization with some custom styling needs
• Score 30-49 if: Could be done with p5 but standard library would be simpler
• Score 0-29 if: Pure data visualization better served by specialized libraries (charts, plots, diagrams)

Strengths:

• Complete flexibility and customization
• Complex animations and physics
• Real-time interactivity
• Creative visual effects

Limitations:

• Requires more development time
• Not optimized for standard charts/diagrams
• Steeper learning curve for users

---

2. chartjs-generator

Skill Location: skills/chartjs-generator/SKILL.md

Primary Use Cases:

• Standard statistical charts
• Data comparison visualizations
• Business intelligence dashboards
• Survey results and analytics

Data Types:

• Numerical data (continuous or discrete)
• Categorical data
• Time-series data (for line charts)
• Percentage/proportion data

Chart Types Supported: 1. Bar charts (vertical/horizontal) 2. Line charts 3. Pie charts 4. Doughnut charts 5. Radar charts 6. Polar area charts 7. Scatter plots 8. Bubble charts (also has dedicated bubble-chart-generator)

Interactivity Level:

• Medium
• Hover tooltips
• Legend toggling
• Responsive resizing

Trigger Words/Phrases:

• "chart", "bar chart", "line chart", "pie chart"
• "graph", "plot data", "visualize data"
• "compare", "statistics", "percentages"
• "dashboard", "analytics", "metrics"

Scoring Guidelines:

• Score 90-100 if: Specification explicitly requests one of the supported chart types with numerical/categorical data
• Score 70-89 if: Data visualization needs that closely align with standard chart types
• Score 50-69 if: Could be represented as a chart but might benefit from more specialized tools
• Score 30-49 if: Chart representation possible but not optimal (e.g., timeline data, network data)
• Score 0-29 if: Non-chart visualization (diagrams, maps, networks, mathematical functions)

Strengths:

• Well-established library
• Clean, professional appearance
• Fast implementation
• Wide variety of chart types

Limitations:

• Limited to standard chart types
• Less suitable for custom visualizations
• Not designed for diagrams or workflows

---

3. math-function-plotter-plotly

Skill Location: skills/math-function-plotter-plotly/SKILL.md

Primary Use Cases:

• Mathematical function plots
• Calculus visualizations
• Physics equations and wave functions
• Engineering transfer functions
• Scientific function analysis

Data Types:

• Mathematical expressions (f(x) = ...)
• Continuous functions
• Parametric equations
• Numerical function data

Function Categories:

• Trigonometric (sin, cos, tan)
• Polynomial (quadratic, cubic, etc.)
• Exponential and logarithmic
• Physics/engineering functions
• Custom mathematical expressions

Interactivity Level:

• High
• Interactive sliders to move points along curves
• Hover tooltips showing coordinates
• Zoom and pan
• PNG export

Trigger Words/Phrases:

• "function", "plot", "f(x)", "equation"
• "graph", "mathematical", "calculus"
• "sine", "cosine", "polynomial", "exponential"
• "plotly", "interactive function"
• "domain", "range", "continuous"

Scoring Guidelines:

• Score 90-100 if: Specification describes plotting a mathematical function with domain/range, mentions f(x) notation, or requests function exploration with sliders
• Score 70-89 if: Scientific/physics plot that can be expressed as a function
• Score 50-69 if: Numerical data that could be approximated as a function
• Score 30-49 if: Plot needs but not specifically functions (discrete data, categorical)
• Score 0-29 if: Non-plot visualizations (diagrams, charts, timelines, networks)

Strengths:

• Powerful Plotly.js library
• Smooth continuous curves (500+ points)
• Interactive exploration with sliders
• Educational lesson plans included
• Professional mathematical notation

Limitations:

• Focused on functions, not discrete data points
• Not suitable for diagrams or structural visualizations
• Requires function expression in JavaScript Math format

---

4. mermaid-generator

Skill Location: skills/mermaid-generator/SKILL.md

Primary Use Cases:

• Flowcharts and process diagrams
• State machines and state diagrams
• Sequence diagrams (interactions over time)
• Entity-relationship diagrams
• Class diagrams (UML)
• User journey maps

Data Types:

• Structural/hierarchical relationships
• Sequential processes
• State transitions
• Entity relationships
• Workflow steps

Diagram Types Supported: 1. Flowchart/Graph - Decision trees, workflows 2. State Diagram - State machines, lifecycle 3. Sequence Diagram - Interactions, API calls 4. ER Diagram - Database schemas 5. Class Diagram - Object-oriented design 6. User Journey - UX flows 7. Block Diagram - System components

Interactivity Level:

• Low to Medium
• Primarily static diagrams
• Some hover effects
• Limited interactivity compared to other generators

Trigger Words/Phrases:

• "flowchart", "flow chart", "diagram"
• "workflow", "process", "procedure"
• "state machine", "state diagram"
• "sequence diagram", "interaction"
• "ER diagram", "entity relationship"
• "class diagram", "UML"
• "decision tree", "logic flow"

Scoring Guidelines:

• Score 90-100 if: Specification describes flowcharts, state machines, sequence diagrams, or other standard diagram types supported by Mermaid
• Score 70-89 if: Process or structural visualization that fits Mermaid's diagram types
• Score 50-69 if: Could be represented as a diagram but might need customization
• Score 30-49 if: Diagram needs but with heavy interactivity requirements
• Score 0-29 if: Data-driven visualizations (charts, plots, timelines) or highly interactive needs

Strengths:

• Wide variety of diagram types
• Clean, professional appearance
• Text-based specification (easy to modify)
• Good for documentation

Limitations:

• Limited interactivity
• Less suitable for data-heavy visualizations
• Shape sizes may not scale responsively
• Not ideal for network graphs with physics

---

5. vis-network

Skill Location: skills/vis-network/SKILL.md

Primary Use Cases:

• Network diagrams (nodes and edges)
• Concept dependency graphs
• Learning graphs showing prerequisite relationships
• Knowledge maps
• Social network visualizations
• System architecture diagrams with connections

Data Types:

• Nodes (entities) and edges (relationships)
• Graph structures
• Hierarchical data that can be graphed
• Network topologies

Interactivity Level:

• Very High
• Physics-based layout
• Drag nodes
• Click for details
• Zoom and pan
• Hover tooltips
• Dynamic clustering

Trigger Words/Phrases:

• "network", "graph", "nodes", "edges"
• "relationships", "connections", "dependencies"
• "concept map", "knowledge graph"
• "prerequisite", "dependency graph"
• "network diagram", "topology"
• "vis-network", "interactive graph"

Scoring Guidelines:

• Score 90-100 if: Specification describes nodes and edges, network relationships, dependency graphs, or concept maps with connections
• Score 70-89 if: Hierarchical or relational data that naturally forms a network structure
• Score 50-69 if: Connected data but could also be shown as a tree or diagram
• Score 30-49 if: Relationships exist but not the primary focus
• Score 0-29 if: Non-network visualizations (charts, plots, timelines, workflows without connections)

Strengths:

• Physics-based automatic layout
• Highly interactive
• Excellent for complex relationships
• Scales well with many nodes
• Group/cluster support

Limitations:

• Can be overwhelming with too many nodes
• Not ideal for strict hierarchies (use Mermaid instead)
• Requires node and edge data structure

---

6. timeline-generator

Skill Location: skills/timeline-generator/SKILL.md

Primary Use Cases:

• Historical timelines
• Project timelines and schedules
• Product roadmaps and release plans
• Course schedules and curricula
• Event chronologies
• Organizational milestones

Data Types:

• Temporal/chronological data
• Events with specific dates
• Date ranges (start and end dates)
• Categorized events (optional groups)

Interactivity Level:

• High
• Zoom in/out on timeline
• Pan left/right
• Click events for detailed information
• Category filtering with buttons
• Hover for tooltips

Trigger Words/Phrases:

• "timeline", "chronological", "chronology"
• "events", "history", "historical"
• "schedule", "calendar", "dates"
• "roadmap", "milestones", "phases"
• "project timeline", "course timeline"
• "sequence of events", "over time"

Scoring Guidelines:

• Score 90-100 if: Specification includes events with specific dates, mentions timeline/chronological order, or describes temporal sequences
• Score 70-89 if: Time-based data that would benefit from timeline visualization
• Score 50-69 if: Sequential data without specific dates (could use other methods)
• Score 30-49 if: Some temporal aspect but not the primary organizing principle
• Score 0-29 if: Non-temporal visualizations (charts, diagrams, networks, plots)

Strengths:

• Specialized for temporal data
• Excellent date handling and formatting
• Zoom and pan for long timelines
• Category filtering
• Event detail panels

Limitations:

• Requires date information
• Not suitable for non-temporal data
• Limited to linear time representation

---

7. map-generator

Skill Location: skills/map-generator/SKILL.md

Primary Use Cases:

• Geographic visualizations
• Location markers and points of interest
• Route visualization
• Regional data (GeoJSON)
• Campus maps, facility maps
• Travel itineraries

Data Types:

• Geographic coordinates (latitude, longitude)
• Location names (geocoded to coordinates)
• GeoJSON data for regions
• Marker data with descriptions
• Multiple map layers

Interactivity Level:

• Very High
• Zoom in/out
• Pan across map
• Click markers for popups
• Toggle layers
• Marker clustering for dense data

Trigger Words/Phrases:

• "map", "geographic", "location"
• "coordinates", "latitude", "longitude"
• "markers", "pins", "points of interest"
• "route", "path", "journey"
• "GeoJSON", "regions", "boundaries"
• "leaflet", "interactive map"

Scoring Guidelines:

• Score 90-100 if: Specification includes geographic coordinates, location names, map regions, or explicitly requests a map visualization
• Score 70-89 if: Location-based data that would benefit from spatial representation
• Score 50-69 if: Some geographic component but could use other representations
• Score 30-49 if: Location mentioned but not central to visualization
• Score 0-29 if: Non-geographic visualizations (charts, timelines, diagrams, plots)

Strengths:

• Full-featured mapping with Leaflet.js
• Multiple basemap options (street, satellite, terrain)
• Layer support for complex visualizations
• Marker customization
• GeoJSON support for regions

Limitations:

• Requires geographic data
• Not suitable for abstract spatial layouts
• May be overkill for simple location lists

---

8. venn-diagram-generator

Skill Location: skills/venn-diagram-generator/SKILL.md

Primary Use Cases:

• Set theory visualizations
• Category overlap comparisons
• Concept relationship diagrams (2-4 sets)
• Educational comparisons
• Feature comparison diagrams

Data Types:

• Sets (2-4 distinct categories)
• Set intersections and overlaps
• Educational definitions for each region
• Proportional or symbolic sizes

Interactivity Level:

• Medium
• Hover tooltips with educational definitions
• Static circular layout
• Definitions from glossary (preferred)

Trigger Words/Phrases:

• "venn", "venn diagram"
• "sets", "set theory", "overlap"
• "intersection", "union"
• "compare", "categories", "groups"
• "commonalities", "differences"
• "2 circles", "3 circles", "4 circles"

Scoring Guidelines:

• Score 90-100 if: Specification explicitly requests Venn diagram or describes 2-4 sets with overlaps and intersections
• Score 70-89 if: Category comparison that would benefit from showing overlaps
• Score 50-69 if: Comparison of categories but overlaps not emphasized
• Score 30-49 if: Multiple categories but no clear overlap relationships
• Score 0-29 if: Not a set comparison (charts, timelines, networks, plots)

Strengths:

• Clear visualization of set relationships
• Educational tooltips with glossary integration
• Simple, clean appearance
• Supports 2-4 sets

Limitations:

• Limited to 2-4 sets
• Proportional sizing can be misleading
• Less suitable for complex relationships (use vis-network instead)
• Library not actively maintained (use with caution)

Special Note: Always check /docs/glossary.md for existing definitions before asking user for set definitions.

---

9. bubble-chart-generator

Skill Location: skills/bubble-chart-generator/SKILL.md

Primary Use Cases:

• Priority matrices (2x2 grids)
• Impact vs Effort analysis
• Risk vs Value assessment
• Portfolio analysis
• Multi-dimensional data comparison (x, y, size)

Data Types:

• Items with 2-3 dimensions
• X-axis value (e.g., Effort, Time, Cost)
• Y-axis value (e.g., Impact, Value, Priority)
• Size dimension (optional, e.g., Resource requirement)
• Quadrant categorization

Interactivity Level:

• Medium
• Hover tooltips
• Quadrant highlighting
• Click for details
• Legend toggling

Trigger Words/Phrases:

• "priority matrix", "prioritization"
• "bubble chart", "bubble plot"
• "impact vs effort", "effort vs impact"
• "risk vs value", "value vs complexity"
• "portfolio", "quadrant", "2x2"
• "multi-dimensional", "scatter with size"

Scoring Guidelines:

• Score 90-100 if: Specification describes priority matrix, impact vs effort, 2x2 quadrant analysis, or bubble chart with 3 dimensions
• Score 70-89 if: Multi-dimensional comparison that would benefit from bubble visualization
• Score 50-69 if: 2D scatter plot without size dimension (could use chartjs instead)
• Score 30-49 if: Comparison data but not naturally 2D or quadrant-based
• Score 0-29 if: Non-comparative visualizations or single-dimension data

Strengths:

• Specialized for priority/portfolio analysis
• Quadrant labeling and highlighting
• Good for decision-making visualizations
• Clean Chart.js implementation

Limitations:

• Very specific use case
• Limited to 2-3 dimensions
• May be overkill for simple scatter plots
• Overlap can make bubbles hard to read with many items

---

Matching Strategy

Step-by-Step Matching Process

1. Extract Key Characteristics

• Data type (temporal, geographic, relational, numerical, categorical, mathematical)
• Visual style (chart, diagram, plot, map, timeline, network)
• Interactivity needs (static, hover, click, drag, sliders, real-time)
• Explicit mentions of tools/libraries

2. Identify Primary Matches

• Look for trigger words specific to each generator
• Match data type to generator specialization
• Consider visual style requirements

3. Score Each Generator

• Use the 0-100 scale defined for each generator above
• Consider multiple factors (data, interaction, visual, trigger words)
• Be honest about limitations

4. Rank by Score

• Sort generators from highest to lowest score
• Include top 3-5 recommendations minimum
• Always include at least one score above 50 if possible

5. Provide Reasoning

• Explain why the score is high/low
• Mention specific features that match or don't match
• Suggest alternatives if score is low
• Note any caveats or considerations

Decision Tree Examples

Has dates/timeline? → YES: timeline-generator (high score) → NO: Continue

Has geographic coordinates? → YES: map-generator (high score) → NO: Continue

Mathematical function f(x)? → YES: math-function-plotter-plotly (high score) → NO: Continue

Nodes and edges? → YES: vis-network (high score) → NO: Continue

Flowchart/process/workflow? → YES: mermaid-generator (high score) → NO: Continue

Sets with overlaps? → YES: venn-diagram-generator (high score) → NO: Continue

Priority matrix / 2x2? → YES: bubble-chart-generator (high score) → NO: Continue

Standard chart type (bar, line, pie)? → YES: chartjs-generator (high score) → NO: Continue

Custom/animated/unique? → YES: microsim-p5 (high score) → NO: Need more information

---

Common Ambiguities and How to Resolve

"Interactive visualization of data"

• Clarify: What type of data? What kind of interaction?
• Consider: chartjs-generator (if standard charts), microsim-p5 (if custom)

"Graph showing..."

• Clarify: "Graph" can mean chart (ChartJS) or network graph (vis-network)
• Look for: Nodes/edges → vis-network; Data points → chartjs or function plot

"Diagram of..."

• Clarify: Structural (Mermaid), Network (vis-network), or Custom (p5)?
• Look for: Process words → Mermaid; Relationship words → vis-network

"Timeline with events"

• Clear choice: timeline-generator (high score)
• Alternative: chartjs line chart (lower score)

"Map of concepts"

• Clarify: Geographic map or concept map?
• Geographic → map-generator
• Conceptual → vis-network or mermaid-generator

---

Quality Assurance

When providing match scores, ensure:

1. At least one score ≥ 70: There should be a good match 2. Diversity in scores: Show range of options (don't score everything 50) 3. Clear reasoning: Explain scores with specific features 4. Honesty about limitations: Don't oversell poor matches 5. Alternative suggestions: If primary match has limitations, mention alternatives 6. Complete ranking: Include all relevant generators (usually 3-5 minimum)