Case Study Generator

Overview

This skill automates the creation of case study entries for the intelligent textbooks case studies page. Given a GitHub repository URL, it extracts project information, generates or processes a thumbnail image compressed to ~70KB, and creates a properly formatted markdown entry for docs/case-studies/index.md.

Workflow

Step 1: Gather Repository Information

Extract the following from the GitHub repository:

1. Repository URL - The full GitHub URL provided by the user
2. Repository name - Extract from URL (e.g., dmccreary/geometry-course)
3. GitHub Pages URL - Derive from repo: https://{username}.github.io/{repo-name}
4. Project title - Check for a clear title in README.md or use repo name
5. Description - Extract from README.md (first paragraph or project description)
6. Metrics — read the canonical metrics file FIRST, do not re-count:

   • Preferred source: docs/learning-graph/book-metrics.json (produced by the book-metrics tool, validated against book-metrics.schema.json). Its metrics object is the single source of truth shared with the README and LinkedIn skills, so the case-study card shows identical numbers:

     # After cloning the repo for analysis:
     python3 -c "import json; m=json.load(open('docs/learning-graph/book-metrics.json'))['metrics']; \
     

print(m['concepts'], m['chapters'], m['microsims'], m['glossaryTerms'], m['faqs'], m['words'])" ```

 Available keys: `concepts`, `chapters`, `microsims`, `stories`,
 `glossaryTerms`, `faqs`, `quizQuestions`, `references`, `diagrams`,
 `equations`, `words`, `links`, `equivalentPages`, `developmentStage`.

• Fallback only if book-metrics.json is absent (older repos that have not run the metrics tool):
  • Concept count: find docs -name learning-graph.csv | wc -l and subtract 1 for header
  • Chapter count: Count directories in docs/chapters/
  • Glossary term count: number of level 4 headers in docs/glossary.md
  • FAQ count: Count level 3 or level 4 headers in docs/faq.md
  • File count: find docs -type f -name "*.md" | wc -l
  • Word count: find docs -type f -name "*.md" -exec cat {} \; | wc -w
  • MicroSim count: Count directories in docs/sims/

7. docs/learning-graph/book-metadata.json (or the older metadata.json) may also contain useful identity metadata: title, author, date, and license.

Use the gh CLI or direct GitHub API to fetch repository information:

# Get repo description
gh repo view {owner}/{repo} --json description

# Clone repo temporarily for analysis
gh repo clone {owner}/{repo} /tmp/{repo} -- --depth 1

Step 2: Obtain or Generate Thumbnail Image

Check for existing thumbnail options in priority order:

1. Existing social card image - Check docs/img/ for social-card.png or similar
2. README banner image - Parse README.md for header images
3. Custom image provided by user - User may specify an image path
4. Generate with AI - If no image exists, suggest generating one with an AI image tool

Place the source image in docs/case-studies/img/ with a filename matching the repo name:

• Use kebab-case: geometry-course.jpg, deep-learning-course.jpg

Step 3: Compress Thumbnail Image

Compress the thumbnail to approximately 70KB for fast page loading.

For Initial Compression

Run the thumbnail compression script:

python3 src/compress-thumbnails.py docs/case-studies/img 70

This script:

• Targets 70KB file size
• Maintains minimum 400px width
• Preserves aspect ratio
• Creates .backup files for safety

For PNG to JPEG Conversion (if needed)

If PNG compression cannot achieve 70KB target, convert to JPEG:

python3 src/convert-png-to-jpg.py docs/case-studies/img 70

This script:

• Converts PNG to JPEG format
• Fills transparent areas with white background
• Achieves better compression for photographic images
• Removes original PNG after successful conversion

Manual Single-Image Compression

For compressing a single new image without affecting others:

from PIL import Image, ImageOps

def compress_single_image(input_path, output_path, target_kb=70, min_width=400):
    """Compress a single image to target size."""
    img = Image.open(input_path)
    img = ImageOps.exif_transpose(img)

    # Convert to RGB for JPEG
    if img.mode in ('RGBA', 'LA', 'P'):
        background = Image.new('RGB', img.size, (255, 255, 255))
        if img.mode == 'P':
            img = img.convert('RGBA')
        if img.mode in ('RGBA', 'LA'):
            background.paste(img, mask=img.split()[-1])
            img = background
    elif img.mode != 'RGB':
        img = img.convert('RGB')

    # Calculate resize factor
    orig_w, orig_h = img.size
    min_factor = min_width / orig_w if orig_w > min_width else 1.0

    for factor in [0.5, 0.4, 0.35, 0.3, 0.25, 0.2, 0.15]:
        if factor < min_factor:
            continue
        new_w = int(orig_w * factor)
        new_h = int(orig_h * factor)
        resized = img.resize((new_w, new_h), Image.Resampling.LANCZOS)

        for quality in [85, 80, 75, 70, 65, 60]:
            resized.save(output_path, "JPEG", quality=quality, optimize=True)
            if os.path.getsize(output_path) / 1024 <= target_kb:
                return True
    return False

Step 4: Update index.md Image References

After converting PNG to JPEG, update docs/case-studies/index.md to use the new .jpg extension:

# Before
![Project Name](./img/project-name.png)

# After
![Project Name](./img/project-name.jpg)

Step 5: Generate Case Study Entry

Create the markdown entry using the format in references/entry-format.md.

Entry Format

- **[Project Title](https://username.github.io/repo-name)**

    ![Alt Text](./img/repo-name.jpg)

    Brief 1-2 sentence description of the project, its purpose, and target audience.

    · XX Concepts · XX Chapters · XX MicroSims · XX Stories · XX Quizzes · XXK Words · XXX Glossary Terms · XX FAQs · XX Appendices
    · <span class="completion completion-4" title="Almost Complete (4/5)"></span>
    · [:octicons-mark-github-16: Repository](https://github.com/username/repo-name) 

Entry Guidelines

See references/entry-format.md for examples of different entry styles, including entries with and without glossary terms, and with varying levels of detail in the description and metrics.

Step 6: Insert Entry in Alphabetical Order

Insert the new entry into docs/case-studies/index.md in alphabetical order by project title. The entries are inside a <div class="grid cards grid-3-col" markdown> block.

Step 7: Verify and Clean Up

1. Verify image displays correctly: Run mkdocs serve and check the case studies page
2. Check image file size: Confirm thumbnail is under 70KB
3. Remove backup files (after verification):

   rm docs/case-studies/img/*.backup
   

4. Clean up temporary clone (if created):

   rm -rf /tmp/{repo-name}
   

Example Usage

Local Filesystem Example:

User request: "Add a case study for ../xapi-course"

Remote GitHub Repository Example:

User request: "Add a case study for https://github.com/dmccreary/systems-thinking"

Process:

1. For lone repo, extract: title="Systems Thinking in the Age of AI", description from README
2. Find existing image or generate thumbnail
3. Compress to docs/case-studies/img/systems-thinking.jpg (~31KB)
4. Generate entry:
5. Insert new entry alphabetically into docs/case-studies/index.md:
6. Suggest to the user that they verify the entry with the following URL with mkdocs serve running:

http://127.0.0.1:8000/intelligent-textbooks/case-studies/

Resources

Compression Scripts

The following scripts are located in the project's src/ directory:

• src/compress-thumbnails.py - Compresses images to target KB size with configurable minimum width
• src/convert-png-to-jpg.py - Converts PNG files to JPEG format for better compression

Reference Files

• references/entry-format.md - Template and examples for case study entries