Forem: wyatt fruit

How I Built a Claude Code Skill with URL Deep Linking

wyatt fruit — Sat, 11 Apr 2026 09:59:27 +0000

The Problem

I run a free puzzle generator site (JigsawMake.com) with 30+ tools — word search, crossword, bingo, sudoku, jigsaw. Teachers and event organizers kept asking the same question:

"Which puzzles should I use for my classroom / party / team event, and how do I set them up?"

I realized I could build a Claude Code skill that answers this automatically — not just with recommendations, but with pre-configured links that open the generator with everything already filled in.

The key insight: URL parameters turn a recommendation into a one-click solution.

What We're Building

A skill called puzzle-activity-planner that:

Takes an event description (e.g., "45-minute science class about ocean animals, 25 students")
Generates a structured activity plan with timing and materials
Outputs generator links with URL parameters pre-filled — the user clicks and gets a ready-to-print puzzle

Here's what the output looks like:

Word Search: https://jigsawmake.com/word-search-maker?title=Ocean%20Animals&words=DOLPHIN,OCTOPUS,SEAHORSE,WHALE&gridSize=12
Crossword:   https://jigsawmake.com/crossword-puzzle-maker?title=Ocean%20Animals&clues=DOLPHIN:Smart%20marine%20mammal|OCTOPUS:Has%20eight%20arms
Bingo:       https://jigsawmake.com/bingo-card-generator?title=Ocean%20Bingo&items=Dolphin,Octopus,Seahorse&cardCount=25

The AI generates the content (words, clues, items) and bakes it right into the URL.

Step 1: Add URL Parameter Support to Your Web App

Before building the skill, your web app needs to accept URL parameters. Here's the pattern I used in React (Next.js):

// In your generator component's mount useEffect
useEffect(() => {
  if (typeof window === 'undefined') return;
  const params = new URLSearchParams(window.location.search);

  const urlTitle = params.get('title');
  const urlWords = params.get('words');
  const urlGridSize = params.get('gridSize');

  if (urlTitle) setTitle(decodeURIComponent(urlTitle));

  if (urlGridSize) {
    const size = parseInt(urlGridSize, 10);
    if (size >= 5 && size <= 30) setGridSize(size);
  }

  if (urlWords) {
    const words = decodeURIComponent(urlWords)
      .split(',')
      .map(w => w.trim().toUpperCase())
      .filter(w => w.length > 0);
    if (words.length > 0) {
      setWordList(words);
      setWordListText(words.join('\n'));
      // Trigger puzzle generation
      pendingGenerateRef.current = true;
    }
  }
}, []);

Key points:

Always validate and bound numeric values (grid size, counts)
Use decodeURIComponent() for text values
Only accept known enum values for string options (e.g., difficulty must be "easy", "medium", or "hard")
Invalid parameters should be silently ignored, not crash the page

For crossword puzzles, I used a pipe-separated format for word:clue pairs:

?clues=DOLPHIN:Smart%20marine%20mammal|OCTOPUS:Has%20eight%20arms

This keeps the URL readable while supporting structured data.

Step 2: Create the SKILL.md

A Claude Code skill is just a markdown file with YAML frontmatter. Create SKILL.md:

---
name: puzzle-activity-planner
description: "Plan puzzle-based activities for classrooms, parties, and events."
  Use when someone says "plan a puzzle activity" or "classroom puzzle session".
---

The description field is critical — Claude reads it to decide when to activate the skill.

Step 3: Document URL Parameters in the Skill

This is where the magic happens. Instead of just linking to your tools, teach the AI your URL parameter schema so it can construct pre-filled links:

## URL Parameters

### Word Search
| Param | Values | Default |
|-------|--------|---------|
| `title` | URL-encoded text | "Word Search Puzzle" |
| `words` | Comma-separated | default list |
| `gridSize` | 5-30 | 15 |
| `diagonal` | true/false | true |
| `backward` | true/false | false |

### Crossword
| Param | Values | Default |
|-------|--------|---------|
| `title` | URL-encoded text | "Crossword Puzzle" |
| `difficulty` | easy, medium, hard | medium |
| `clues` | WORD:clue pairs separated by \| | default clues |

Then add a behavior rule:

## Rules
- Always use URL parameters in generator links with pre-filled content
- Generate word-clue pairs yourself and embed them in the URL

This tells Claude: "You are the AI — generate the content and put it in the URL. Don't make the user do it."

Step 4: Test It

Install the skill:

mkdir -p ~/.claude/skills/puzzle-activity-planner
cp SKILL.md ~/.claude/skills/puzzle-activity-planner/

Then in Claude Code:

/puzzle-activity-planner Plan a 30-minute puzzle activity for a 4th grade 
science class about ocean animals, 25 students

Claude generates a complete plan with pre-configured links. The teacher clicks, gets a ready-to-print puzzle.

The URL Deep Linking Pattern

This pattern works for any web tool, not just puzzles:

Add URL parameter support to your web app's form/generator
Document the parameter schema in your SKILL.md
Tell the AI to generate content and embed it in the URL
User gets one-click links instead of manual configuration

The key is that the AI generates domain-specific content (vocabulary words, trivia clues, bingo items) and encodes it directly into the URL. The web app just reads the parameters and renders.

What I Learned

URL parameters are an underused interface. Most web tools accept them but don't document or promote them. By teaching an AI your URL schema, you turn a static link into a personalized, ready-to-use tool.

Skills are surprisingly simple. A SKILL.md file is just instructions + a parameter reference table. No API, no auth, no backend. The skill I built is ~200 lines of markdown.

The AI is the content engine. For crosswords, the AI generates word-clue pairs. For word searches, it picks theme-appropriate vocabulary. For bingo, it creates themed items. All embedded in the URL. The web app doesn't need its own AI — the skill handles content generation.

Try It

The skill is open source:

# Install with npx skills
npx skills add fruitwyatt/puzzle-activity-planner

# Or clone directly
git clone https://github.com/fruitwyatt/puzzle-activity-planner \
  ~/.claude/skills/puzzle-activity-planner

GitHub: fruitwyatt/puzzle-activity-planner

The generators are all free at JigsawMake.com — no signup, no watermarks, runs entirely in the browser.

I Built a Free Puzzle Generator That Supports 8 Languages — Here's What I Learned

wyatt fruit — Fri, 10 Apr 2026 09:19:35 +0000

Last year I started building PuzzleGenio — a free online puzzle maker for crosswords, word searches, sudoku, jigsaw puzzles, and more. What began as
a simple weekend project turned into a platform with 20+ tools supporting 8 languages.

Here's what I learned along the way.

## Why Puzzles?

Teachers, parents, and event planners constantly search for "free crossword maker" or "printable word search generator." The existing tools are either paywalled, riddled with
ads, or stuck in 2005 UI. I saw a gap.

The core idea: one URL = one tool = one keyword. Each puzzle maker is a standalone page that works as both a functional tool AND an SEO landing page. Users generate their
puzzle, customize it, and download a print-ready PDF — all on the same page, no signup required.

## Tech Stack

Next.js 15 (App Router) with TypeScript
next-intl for i18n (8 locales: en, zh, de, es, fr, pt, it, id)
Client-side generation — puzzles are generated in the browser, no server load
PDF export — vector-based PDFs using jsPDF, so prints look crisp at any size
Tailwind CSS — responsive design that works on mobile and desktop

## The i18n Challenge

Supporting 8 languages isn't just about translating strings. Here's what actually matters:

1. Localized keyword research, not literal translation

"Word Search" in German isn't "Wort Suche" — German users search for "Buchstabenrätsel" or "Suchsel." I researched Google Autocomplete and competitor sites for each language
to find what real users actually type.

2. Native language puzzle content

A Spanish user generating a crossword expects Spanish words in the puzzle, not English ones. So I built a locale-aware word list system that generates puzzles with native
vocabulary for each supported language.

3. SEO metadata per locale

Every page has localized meta titles and descriptions, hreflang tags, and JSON-LD structured data (FAQPage, HowTo, WebApplication) — all using translated strings, never
hardcoded English.

## What Worked for SEO

A few things that moved the needle:

One keyword = one page. Instead of one generic "puzzle maker" page, I have dedicated pages for crossword-puzzle-maker, printable-crossword-puzzles, word-search-for-kids, large-print-word-search, etc. Each targets a specific long-tail keyword.
Subdirectory i18n (/es/crossword-puzzle-maker, /de/sudoku-puzzle-maker) instead of query params or cookies. Google treats each as a separate indexable page.
Schema markup on every tool page — FAQPage schema gets you those expandable FAQ snippets in search results.
Fast load times — puzzle generation happens client-side, so the server just delivers static HTML. No spinners, no "generating..." wait screens.

## Lessons Learned

Start with fewer languages, do them well. I initially translated everything with AI and shipped it. The German and Spanish translations had embarrassing errors (wrong
grammatical cases, invented words). Now I research each language individually and verify with native speakers.

PDF export quality matters more than you think. My first version used canvas-based screenshots for PDFs. They looked blurry when printed. Switching to vector-based PDF
generation (drawing shapes and text directly) made the output print-perfect and reduced file sizes.

Don't over-engineer early. I spent too long on a fancy puzzle-sharing system before realizing 90% of users just want to download a PDF and print it. Build for the dominant
use case first.

## Numbers So Far

The /es/ and /de/ pages are now getting real organic traffic. Some long-tail keywords are ranking on page 1 within weeks — that's the power of low-competition keywords +
quality localized content.

## Try It Out

If you need puzzles for your classroom, party, or just for fun:

Everything is free, no signup required. Available in English, Chinese, German, Spanish, French, Portuguese, Italian, and Indonesian.

I'd love to hear your feedback — especially if you're a teacher or parent who uses puzzle tools regularly. What features would make your life easier?

Why Your App's Photos Look Weird: A Developer's Guide to Moiré Patterns

wyatt fruit — Fri, 10 Apr 2026 09:14:42 +0000

You've probably seen it before — strange rainbow-colored waves rippling across a photo of a computer screen, or weird grid-like artifacts in a scanned document. That's called a moiré pattern, and if you're building any application that handles images, it's something you'll inevitably run into.

What Exactly Is a Moiré Pattern?

Moiré patterns occur when two repetitive patterns overlap at slightly different angles or scales. Think of it like this:

Pattern A:  | | | | | | | | | |
Pattern B:   | | | | | | | | | |
Result:     |||  |  |||  |  |||    ← interference pattern

In the physical world, this happens constantly:

Screen photography: Your phone camera's pixel grid interferes with the monitor's pixel grid → rainbow waves
Scanning printed material: The scanner's sampling grid clashes with the halftone dot pattern → wavy artifacts
Fabric photography: The camera sensor grid interacts with the weave pattern → visual noise
Video recording: Shooting someone wearing a striped shirt on camera → shimmering patterns

Why Developers Should Care

If you're building any of these, moiré will bite you:

1. Image Upload Platforms

Users upload photos of screens, scanned documents, and product images all the time. Moiré degrades image quality and makes OCR unreliable.

// Your OCR pipeline might fail on moiré-affected scans
const result = await tesseract.recognize(scannedImage);
// result.confidence: 45% 😬 — moiré confused the character recognition

2. E-commerce Product Photos

Photographing textured fabrics, mesh materials, or screens? Moiré makes products look defective. This directly impacts conversion rates.

3. Screen Capture & Recording Tools

Building a screen recording app? If users capture one screen with another device, moiré is guaranteed. Even screenshot tools can produce moiré when downscaling.

4. Document Scanning Apps

Any app that digitizes printed materials needs to handle the halftone-to-pixel conversion problem. Without descreening, your scanned PDFs look amateur.

The Math Behind Moiré

For the curious, moiré is an aliasing artifact — a fundamental concept in signal processing.

When you sample a signal (an image) at a rate lower than twice its highest frequency, you get aliasing. This is the Nyquist-Shannon sampling theorem in action:

f_moiré = |f₁ - f₂|

Where:
  f₁ = frequency of pattern 1 (e.g., screen pixel pitch)
  f₂ = frequency of pattern 2 (e.g., camera sensor pitch)

When f₁ and f₂ are close but not identical, you get a low-frequency interference pattern — that's your moiré.

This is the same principle behind:

Audio aliasing in digital music
The "wagon wheel effect" in video
Temporal aliasing in animation frame rates

How to Fix Moiré: The Technical Approaches

Approach 1: Gaussian Blur (The Brute Force Way)

import cv2
import numpy as np

def remove_moire_blur(image, kernel_size=5):
    """
    Simple but destructive — removes moiré by 
    low-pass filtering, but also kills detail.
    """
    return cv2.GaussianBlur(image, (kernel_size, kernel_size), 0)

Pros: Simple, fast

Cons: Destroys image detail. It's like fixing a headache with a sledgehammer.

Approach 2: Frequency Domain Filtering

def remove_moire_frequency(image):
    """
    Smarter approach: find moiré peaks in frequency 
    domain and notch them out.
    """
    # Convert to frequency domain
    f_transform = np.fft.fft2(image)
    f_shift = np.fft.fftshift(f_transform)

    # Create notch filter to remove moiré frequencies
    # (frequencies identified by spectral analysis)
    magnitude = np.abs(f_shift)

    # Find and suppress anomalous frequency peaks
    threshold = np.mean(magnitude) + 3 * np.std(magnitude)
    mask = magnitude < threshold

    # Apply filter and reconstruct
    filtered = f_shift * mask
    return np.abs(np.fft.ifft2(np.fft.ifftshift(filtered)))

Pros: Preserves more detail

Cons: Requires manual tuning per image, doesn't generalize well.

Approach 3: AI/Deep Learning (The Modern Way)

Modern neural networks can learn to separate moiré patterns from actual image content. This is where the field has moved — models trained on paired moiré/clean image datasets can selectively remove the interference while preserving detail.

The key architectures used:

U-Net variants — encoder-decoder with skip connections
Multi-scale approaches — process at different resolutions to catch moiré at various frequencies
GAN-based methods — adversarial training for more realistic restoration

For most developers, implementing this from scratch isn't practical. Tools like Moire Removal use AI models specifically trained for this, so you can integrate moiré removal into your workflow without building the ML pipeline yourself.

Practical Tips for Your Application

If you're dealing with moiré in your product, here's a decision tree:

Is moiré in your input images?
├── Yes, from screen photos
│   └── Consider: slightly defocus, angle the camera, 
│       or use AI post-processing
├── Yes, from scanned documents  
│   └── Use descreening (most scanner software has this)
│       or try specialized tools like descreening APIs
├── Yes, from fabric/product photos
│   └── Adjust camera distance/angle at capture time
│       or use AI removal in post-processing
└── Yes, from downscaling in your app
    └── Use proper anti-aliasing:
        CSS: image-rendering: auto; (not crisp-edges)
        Canvas: ctx.imageSmoothingEnabled = true;

Quick Win: Prevent Moiré in Canvas Downscaling

function downscaleWithAntiAlias(canvas, targetWidth, targetHeight) {
  // Step-down approach prevents moiré from aggressive downscaling
  const steps = Math.ceil(Math.log2(canvas.width / targetWidth));

  let currentCanvas = canvas;
  for (let i = 0; i < steps; i++) {
    const stepCanvas = document.createElement('canvas');
    stepCanvas.width = currentCanvas.width / 2;
    stepCanvas.height = currentCanvas.height / 2;

    const ctx = stepCanvas.getContext('2d');
    ctx.imageSmoothingEnabled = true;
    ctx.imageSmoothingQuality = 'high';
    ctx.drawImage(currentCanvas, 0, 0, stepCanvas.width, stepCanvas.height);

    currentCanvas = stepCanvas;
  }

  // Final resize to exact target
  const finalCanvas = document.createElement('canvas');
  finalCanvas.width = targetWidth;
  finalCanvas.height = targetHeight;
  const ctx = finalCanvas.getContext('2d');
  ctx.imageSmoothingEnabled = true;
  ctx.drawImage(currentCanvas, 0, 0, targetWidth, targetHeight);

  return finalCanvas;
}

Key Takeaways

Moiré is physics, not a bug — it's aliasing from overlapping patterns
Prevention > Cure — adjust capture conditions when possible
AI removal is now practical — you don't need to implement FFT notch filters from scratch
Think about it in your image pipeline — especially if you handle user-uploaded photos, scans, or screen captures

Resources

Understanding Moiré Patterns — visual explainer
Digital Image Processing — Gonzalez & Woods (Chapter on frequency domain filtering)
Nyquist-Shannon Sampling Theorem — Wikipedia

Have you dealt with moiré in your projects? I'd love to hear your approach in the comments.