dmccreary/claude-skills/logs

Session Log: Create Map Generator Skill

Date: 2025-01-16

Session Duration: ~45 minutes

Objective: Create a new Claude AI skill called map-generator that generates interactive Leaflet.js maps for intelligent textbooks, optimized for iframe embedding in narrow MkDocs pages.

Session Overview

This session involved creating a complete skill package for generating interactive geographic maps using the Leaflet JavaScript library. The skill follows established patterns from similar visualization skills (chartjs-generator, timeline-generator, mermaid-generator) and includes comprehensive templates and documentation.

Planning Phase

Initial Request

User requested creation of a map-generator skill using the skill-creator skill. Requirements:

• Use Leaflet JavaScript library
• Take geographic region name as input
• Display maps in iframes with minimal padding/margins
• Optimize for narrow MkDocs pages (navbar left, TOC right)
• Prompt users for additional information (layers, borders, markers)

Research Phase

Used Task tool with Plan subagent to investigate:

1. Skill Creation Process: Discovered no skill-creator skill exists; skills are created manually following existing patterns
2. Similar Skills Analyzed:

• chartjs-generator (Chart.js visualizations)
• timeline-generator (vis-timeline visualizations)
• mermaid-generator (Mermaid diagrams)
• microsim-p5 (p5.js simulations)

1. Key Findings:

• All skills follow consistent directory structure
• YAML frontmatter required in SKILL.md
• Template files stored in assets/ subdirectory
• Minimal margins critical for iframe embedding (margin: 0; padding: 0;)
• MicroSims stored in docs/sims/[name]/
• Common styling: aliceblue background, minimal spacing

Plan Approval

Presented comprehensive plan to user covering:

• 7 files to create (SKILL.md + 6 template files)
• 10-step workflow for map generation
• Key design decisions (minimal margins, user prompts, CDN version)
• Testing approach

User approved plan and execution began.

Execution Phase

Files Created

1. skills/map-generator/SKILL.md

Created: Main skill definition file

Content:

• YAML frontmatter with name and description
• 10-step workflow:

1. Gather map requirements
2. Create directory structure
3. Create map-data.json (optional)
4. Create main.html
5. Create style.css
6. Create script.js
7. Create index.md
8. Create metadata.json
9. Update mkdocs.yml navigation
10. Test and validate

• Common map patterns (markers, GeoJSON, layer controls, custom icons)
• Educational considerations (Bloom's taxonomy alignment)
• Accessibility guidelines
• Performance optimization tips
• Troubleshooting guide
• References to Leaflet documentation

Lines: ~400+ lines of comprehensive documentation

2. skills/map-generator/assets/template-iframe-main.html

Created: HTML template for map pages

Key Features:

• HTML5 structure
• Leaflet CDN links (v1.9.4 with SRI integrity checks)
• Map container div with id="map"
• Optional controls section
• Placeholders: {{TITLE}}, {{SUBTITLE}}
• Script reference to script.js

Lines: ~35 lines

3. skills/map-generator/assets/template-iframe-style.css

Created: CSS template with minimal margins for iframe embedding

Critical Requirements:

• body { margin: 0; padding: 0; } - Essential for iframe
• Minimal margins throughout (2-5px max)
• Fixed height for #map container (400px default)
• aliceblue background (repository standard)
• Blue 2px border on container
• Responsive breakpoints (768px, 480px)
• Custom popup styling
• Control button styling

Lines: ~180 lines with comprehensive responsive design

4. skills/map-generator/assets/template-script.js

Created: JavaScript template with Leaflet initialization

Features:

• Map configuration object with placeholders
• Leaflet map initialization
• Tile layer setup (OpenStreetMap default)
• Marker array with popup bindings
• Commented-out optional features:
• Custom marker icons
• GeoJSON layers for borders/regions
• Layer controls (street/satellite/terrain)
• Marker clustering for large datasets
• Custom control buttons
• Fit bounds auto-zoom
• Event listeners

Placeholders: {{CENTER_LAT}}, {{CENTER_LNG}}, {{ZOOM}}, {{TILE_LAYER_URL}}, {{ATTRIBUTION}}, {{MARKERS_JSON}}, {{GEOJSON_DATA}}

Lines: ~150 lines with extensive examples

5. skills/map-generator/assets/template-index.md

Created: Markdown documentation template

Sections:

• Title and overview
• Interactive map (iframe embed at 700px height)
• Fullscreen link
• Features (interactive elements, visual design)
• Map details (coordinates, zoom, marker count)
• Customization guide (adding markers, changing base map, adjusting height, custom icons, GeoJSON)
• Technical details (library version, compatibility, dependencies)
• Educational applications (geography, science, social studies, campus maps)
• Bloom's taxonomy alignment
• Accessibility considerations
• References
• Version history

Lines: ~200+ lines of comprehensive documentation

6. skills/map-generator/assets/template-metadata.json

Created: Dublin Core metadata template

Fields:

• Standard Dublin Core: title, description, subject, creator, date, type, format, language, coverage, rights, audience
• Map-specific: map_type, center_lat, center_lng, zoom_level, marker_count, base_map, has_layers, has_geojson
• Educational: concepts, bloom_taxonomy, difficulty, prerequisites, learning_objectives, tags
• Technical: version, library, library_version

Lines: ~30 lines

Test Map Generation

Created: docs/sims/test-world-cities/

Purpose: Validate the skill workflow and templates

Files Created:

1. main.html - Complete HTML with title "Major World Cities"
2. style.css - Copied from template (no modifications needed)
3. script.js - Working JavaScript with 10 city markers:

• New York City, USA
• London, United Kingdom
• Tokyo, Japan
• Sydney, Australia
• Mexico City, Mexico
• São Paulo, Brazil
• Moscow, Russia
• New Delhi, India
• Cairo, Egypt
• Nairobi, Kenya

1. index.md - Complete documentation with iframe embed
2. metadata.json - Populated with test map data

Configuration:

• Center: 20°N, 0°E (equator)
• Zoom: 2 (world view)
• Markers: 10 cities across 6 continents
• Each marker includes: title, description, Wikipedia link
• Base map: OpenStreetMap

Result: Fully functional test map demonstrating all core features

Key Achievements

1. Complete Skill Package

Created a production-ready skill with:

• Comprehensive workflow documentation
• 6 template files covering all aspects
• Educational framework integration
• Accessibility considerations
• Performance optimization guidance

2. Iframe Optimization

Achieved minimal margins/padding essential for narrow MkDocs pages:

• Body: 0 margin, 0 padding
• Container: 5px padding
• Headings: 2-5px margins
• No bottom margin on controls
• Tested responsive behavior

3. Educational Focus

Integrated educational best practices:

• Bloom's taxonomy alignment (6 cognitive levels)
• ISO 11179 metadata standards
• Dublin Core fields
• Learning objectives and prerequisites
• Multiple use cases documented

4. Comprehensive Templates

Templates support advanced features:

• Simple marker maps
• GeoJSON layers (borders, regions)
• Multiple tile layers (street, satellite, terrain)
• Custom marker icons
• Layer controls
• Marker clustering
• Custom control buttons
• Event handling

5. Successful Test

Generated working test map demonstrating:

• Proper iframe embedding
• Interactive markers with popups
• External links to resources
• Responsive design
• Minimal margins achieved

Technical Specifications

Technologies Used

• Leaflet: 1.9.4 (latest stable)
• CDN: unpkg.com with SRI integrity checks
• Base Map: OpenStreetMap (default)
• Format: HTML5, CSS3, ES6 JavaScript

File Structure

skills/map-generator/
├── SKILL.md                          # Skill definition (400+ lines)
└── assets/
    ├── template-iframe-main.html     # HTML template (35 lines)
    ├── template-iframe-style.css     # CSS template (180 lines)
    ├── template-script.js            # JavaScript template (150 lines)
    ├── template-index.md             # Documentation template (200+ lines)
    └── template-metadata.json        # Metadata template (30 lines)
 
docs/sims/test-world-cities/          # Test map
├── main.html                         # Working HTML
├── style.css                         # Minimal margin CSS
├── script.js                         # 10-city map script
├── index.md                          # Complete documentation
└── metadata.json                     # Test metadata

Design Patterns

1. Template Placeholders: Consistent use of {{PLACEHOLDER}} syntax
2. Minimal Margins: Body 0/0, headings 2-5px, no bottom margins on controls
3. Responsive Design: Three breakpoints (desktop, 768px, 480px)
4. Repository Standards: aliceblue background, blue borders
5. MicroSim Pattern: Files in docs/sims/[name]/, iframe embed in index.md

Challenges and Solutions

Challenge 1: No skill-creator Skill

Issue: User requested using skill-creator, which doesn't exist

Solution:

• Used Task tool with Plan subagent to research existing skills
• Identified patterns from chartjs-generator, timeline-generator, etc.
• Created skill manually following established patterns

Challenge 2: Iframe Optimization

Issue: Maps need to fit in narrow MkDocs pages with navbar and TOC

Solution:

• Set body { margin: 0; padding: 0; } (critical)
• Minimized all margins (2-5px max)
• Used fixed map height (400px default, customizable)
• Tested responsive breakpoints

Challenge 3: Comprehensive Templates

Issue: Need to support various map types (markers, GeoJSON, layers)

Solution:

• Created template-script.js with commented-out optional features
• Documented common patterns in SKILL.md
• Provided examples for each feature type
• Included troubleshooting guide

Educational Value

Bloom's Taxonomy Coverage

Skill documentation explicitly maps to all 6 levels:

1. Remember: Identify locations on a map
2. Understand: Explain geographic relationships
3. Apply: Use maps for problem-solving (routes, distances)
4. Analyze: Compare geographic patterns
5. Evaluate: Assess geographic data quality
6. Create: Design custom maps for specific purposes

Use Cases Documented

• Geography and history (historical sites, exploration routes)
• Science (biodiversity, climate zones, geological formations)
• Social studies (cultural landmarks, population centers)
• Campus and facility maps

Accessibility

• Descriptive text in popups
• Keyboard navigation support
• High-contrast colors
• Text alternatives for visual information

Next Steps

Immediate

1. ✅ Skill created and tested
2. ✅ Test map generated and validated
3. ✅ Session log written

Future Enhancements

1. Install globally: Run scripts/install-claude-skills.sh to make available to all projects
2. Add to mkdocs.yml: Include test map in navigation
3. Create additional examples:

• Campus map with building labels
• Historical events map with timeline
• Choropleth map with data visualization
• Route map with polylines

1. Advanced features:

• Marker clustering example
• Heat map overlay
• Drawing tools (polygons, circles)
• Search/geocoding integration

Documentation Additions

Consider creating in skills/map-generator/references/:

• Leaflet quick reference guide
• Common GeoJSON patterns
• Tile layer provider list
• Map projection explanations
• Performance optimization guide

Metrics