oaustegard avatar

development-tools

Software development utilities: MCP servers, bookmarklets, frameworks, patching, and environment validation.

version
1.2.1
GitHub stars
404

Install

/plugin install development-tools@oaustegard-claude-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add oaustegard/claude-skills.

Contents

Discovered from source

Skills 10

Capturing browser logs

The user runs the page; you read what it did. Agent Log records the page's console output, uncaught errors, unhandled rejections, failed resource loads, CSP violations and fetch/XHR calls into the browser's IndexedDB, shows a red Logging badge while it records, and exports an OTLP/JSON file the user hands back to you. Nothing is uploaded.

Docs, bookmarklet and console snippet: https://austegard.com/web-utilities/agent-log.html

Applicability

Use it when the bug happens in a real browser that you do not control: the user's phone, a GPU-specific failure, a page behind their login, timing that a headless run does not reproduce. If you can run the page yourself in Playwright or a browser tool, do that instead and read the console directly. Agent Log does not see iframes, web workers or service workers, and it does not record request or response bodies.

Procedure

  1. Pick how the user turns it on. Give them exactly one route:

    • A page whose source you can edit: add <script src="https://austegard.com/web-utilities/agent-log.js"></script> to its <head>, ship it, and ask the user to open the page with ?logging=true (or &logging=true when the URL already has a query). Logging stays on in that tab across reloads until they press Stop logging. For a page that should always log, use <script src="…" data-start></script>.
    • Any other page: ask the user to drag the bookmarklet from the docs page to their bookmarks bar, open the page and click it.
    • A page with a strict Content Security Policy (GitHub, many banks and mail clients): the bookmarklet silently fails there. Ask the user to press Copy the full script on the docs page and paste it into the page's devtools console.
    • raw.githubusercontent.com cannot serve the script to a <script> tag (it sends text/plain with nosniff). Use the austegard.com URL, or jsDelivr: https://cdn.jsdelivr.net/gh/oaustegard/oaustegard.github.io@main/web-utilities/agent-log.js.
  2. Instrument with structured console calls where the existing output will not answer your question. Pass an object: its keys become OTLP attributes you can filter on.

    console.log("bot tick", { tic, pos: { x, y }, sector, target: t?.kind, action });
    console.warn("asset retry", { url, attempt, status });
    
    • Start the call with a short fixed label, so --grep and the body find it.
    • Keep the volume low: once a second, or on change, not once per frame. The log keeps only the newest 20,000 records, so a 60 fps log fills it in under six minutes and pushes out the error you wanted.
    • Mark these calls as temporary in a comment and remove them once the bug is fixed.
  3. Watch the elements involved when the bug is about an interaction (a button that does nothing, a field that loses its value, a counter that stops updating). Watched elements get records for clicks, typing (one per pause, with the value; password, email, phone and other personal or credential fields are [hidden]), changes, submits, focus, non-text keys, and changes to their attributes, text and children. Pick one of:

    • Name them yourself: tell the user to open the page with &watch=<url-encoded selector> (repeatable) on a page that includes the script, or to run AgentLog.watch("#checkout", { label: "checkout button" }) in the console.
    • Let the user point: ask them to click the badge, press Watch an element and click the element. The click that picks is not passed to the page. Watches persist per site until removed with × in the panel or AgentLog.unwatch(selector).
  4. Ask the user to reproduce, then export. Tell them: click the Logging badge, press Download (or Copy and paste the JSON), and attach the file. The export holds every page load on that site since the log was last cleared; ask them to press Clear before reproducing when old runs would get in the way. Tell them, in one sentence, that the log has stayed in their browser until now and that sending it to you sends it to your provider, so they should look it over and cut anything private before attaching it.

  5. Read the export with the reader below. Save it as read_agent_log.py and run it with the export's path.

    python3 read_agent_log.py agent-log.json --pages          # page loads: url, start, records, errors
    python3 read_agent_log.py agent-log.json --min warn       # warnings and errors first
    python3 read_agent_log.py agent-log.json --event console --grep "bot tick" --tail 50
    python3 read_agent_log.py agent-log.json --event http --attr http.response.status_code=404
    python3 read_agent_log.py agent-log.json --event dom --attr watch.label="checkout button"   # one watched element
    python3 read_agent_log.py agent-log.json --load 2 --jsonl > load2.jsonl   # flat rows for pandas or jq
    

    Read errors before anything else, then the records just before the first error in the same page load. Times are UTC.

  6. Verify the capture before diagnosing. --pages must list the page load the user reproduced in, with a URL and a record count above one. If it does not, see the failure modes, fix the capture and ask for another run, rather than reasoning from an empty log.

  7. Report from the records. Quote the timestamp, eventName and attributes you are relying on, so the user can find the same lines in the panel.

The reader

#!/usr/bin/env python3
"""Flatten an Agent Log export (OTLP/JSON logs) into one line per record, with filters."""
import argparse, json, sys
from datetime import datetime, timezone

SEV = {"trace": 1, "debug": 5, "info": 9, "warn": 13, "error": 17, "fatal": 21}

def value(v):
    if not v: return None
    if "stringValue" in v: return v["stringValue"]
    if "intValue" in v: return int(v["intValue"])
    if "doubleValue" in v: return v["doubleValue"]
    if "boolValue" in v: return v["boolValue"]
    if "arrayValue" in v: return [value(x) for x in v["arrayValue"].get("values", [])]
    if "kvlistValue" in v: return attrs(v["kvlistValue"].get("values"))
    return v.get("bytesValue")

def attrs(lst): return {a["key"]: value(a.get("value")) for a in lst or []}

def loads(doc):
    for n, rl in enumerate(doc.get("resourceLogs", [])):
        res = attrs(rl.get("resource", {}).get("attributes"))
        recs = []
        for sl in rl.get("scopeLogs", []):
            for r in sl.get("logRecords", []):
                ns = int(r.get("timeUnixNano") or 0)
                recs.append({"load": n, "time": datetime.fromtimestamp(ns / 1e9, timezone.utc).isoformat(timespec="milliseconds"),
                             "sev": r.get("severityText", ""), "sevn": r.get("severityNumber", 0), "event": r.get("eventName", ""),
                             "body": value(r.get("body")), "attrs": attrs(r.get("attributes"))})
        yield n, res, sorted(recs, key=lambda x: x["time"])

def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("file", nargs="?", default="-", help="the export; - reads stdin")
    ap.add_argument("--pages", action="store_true", help="list the page loads and stop")
    ap.add_argument("--min", choices=list(SEV), help="minimum severity")
    ap.add_argument("--event", action="append", default=[], help="eventName prefix, e.g. console, http.fetch, error (repeatable)")
    ap.add_argument("--grep", help="case-insensitive text in the body or attributes")
    ap.add_argument("--attr", action="append", default=[], help="key=value, compared as text (repeatable)")
    ap.add_argument("--load", type=int, help="only this page load, numbered as --pages shows")
    ap.add_argument("--tail", type=int, help="only the last N matching records")
    ap.add_argument("--jsonl", action="store_true", help="one JSON object per record")
    a = ap.parse_args()
    doc = json.load(sys.stdin if a.file == "-" else open(a.file, encoding="utf-8"))
    if a.pages:
        for n, res, recs in loads(doc):
            errs = sum(r["sevn"] >= 17 for r in recs)
            print(f"[{n}] {res.get('agentlog.started_at', '?')}  {len(recs)} records, {errs} errors  {res.get('url.full', '?')}  ({res.get('user_agent.original', '')[:60]})")
        return
    out = []
    for n, res, recs in loads(doc):
        if a.load is not None and n != a.load: continue
        for r in recs:
            if a.min and r["sevn"] < SEV[a.min]: continue
            if a.event and not any(r["event"].startswith(e) for e in a.event): continue
            text = f"{r['body']} {json.dumps(r['attrs'], default=str)}"
            if a.grep and a.grep.lower() not in text.lower(): continue
            if any(str(r["attrs"].get(k)) != v for k, v in (x.split("=", 1) for x in a.attr)): continue
            out.append(r)
    for r in out[-a.tail:] if a.tail else out:
        if a.jsonl: print(json.dumps({k: v for k, v in r.items() if k != "sevn"}, default=str))
        else: print(f"[{r['load']}] {r['time'][11:23]} {r['sev']:5} {r['event']:16} {r['body']}" + (f"  {json.dumps(r['attrs'], default=str)}" if r["attrs"] else ""))

if __name__ == "__main__":
    main()

Without Python, jq reads the same file: jq -c '.resourceLogs[].scopeLogs[].logRecords[] | select(.severityNumber >= 13) | [.eventName, .body.stringValue]' agent-log.json.

Export format

An OTLP/JSON ExportLogsServiceRequest. Each page load is one resourceLogs entry; its resource attributes are service.name (the host), session.id, url.full, page.title, user_agent.original, browser.language, browser.viewport, agentlog.started_by and agentlog.started_at. Each log record has timeUnixNano (a string of nanoseconds), severityNumber, severityText, eventName, body.stringValue and attributes, where integers are strings in intValue.

eventNameattributes
console.log .info .debug .warn .error .trace .assertthe logged object's keys; exception.* for an Error argument; arg0, arg1… for arrays, maps and DOM nodes
error.uncaughtexception.type, exception.message, exception.stacktrace, code.filepath, code.lineno
error.rejectionexception.*, or reason for a non-Error
error.resourceurl.full, html.element
csp.violationcsp.directive, csp.blocked_uri
http.fetch, http.xhrhttp.request.method, url.full, http.response.status_code, duration_ms, error.type on failure; with agentlog.source: resource-timing there is no method, and agentlog.before_start marks a request made before logging started
dom.click .dblclick .input .change .submit .focus .blur .keydownwatch.selector, watch.label, dom.target, dom.watched (when the event hit a descendant), dom.text, pointer.x/.y, dom.value, dom.checked, key, key.modifiers
dom.mutationwatch.selector, dom.text (the element's text after the change), dom.added, dom.removed, dom.changes (attribute and text changes with old and new values)
dom.watchwatch.selector, watch.matches: a watch was added or removed, or now matches a different number of elements (0 means the element is gone)
page.navigation, page.visibility, agentlog.start, agentlog.stopurl.full, navigation.type, page.visibility

Failure modes

  • No badge appears. The script did not load. On a strict-CSP page the console shows a Content-Security-Policy error naming austegard.com; switch the user to the full-script paste. On your own page, check that the tag is present and the URL has logging=true.
  • The log starts after the bug. The bookmarklet and console routes start recording when clicked, so console output and errors during page load are missing (requests from page load are included, marked agentlog.before_start). An app that kept its own reference to console.log at startup also bypasses the capture when it starts late. Use a page that includes the script and reload it with ?logging=true.
  • The export is empty or from another page. The log is stored per site: it must be exported from a page on the same origin as the one that was logged.
  • The interesting records are gone. More than 20,000 records pushed them out. Reduce the logging rate, or have the page call AgentLog.start({ max: 100000 }).
  • Private data in the export. URLs are redacted (credential-named query parameters such as auth_token or x-api-key, the same pairs in #fragments, and fragments that are one long token), and password, email, phone and other personal fields are [hidden] in watched-element records. Console arguments, the text of watched elements and ordinary field values are recorded as given. Do not log tokens or personal data, and tell the user to review the file before sharing it anywhere else.

Check Tools - Development Environment Validator

Reports which development tools are installed and at what version, grouped by ecosystem. Default behavior reports every tool without failing validation — suited to diverse PaaS/container environments where only a subset of ecosystems is expected to be present.

When to use

  • Verifying a container or environment has the tools a task needs
  • Troubleshooting a build failure that might be a missing dependency
  • Documenting system requirements
  • Onboarding: confirming a dev environment is ready

Running it

# Fast check with exit code (0 = all required core tools present)
bash assets/check-tools.sh

# Development tools only
bash assets/environment-diagnostic.sh tools

# System info: hardware, mounts, processes
bash assets/environment-diagnostic.sh system

# Complete diagnostic (tools + system + package inventories), written to a file
bash assets/environment-diagnostic.sh full /path/to/report.txt

check-tools.sh exits non-zero only when a required core tool (python3, pip, node, npm, java, gcc, git, curl, awk, grep, gzip, tar, make, sed) is missing. Every other tool is reported (✅ found / ⚠️ optional and missing) but does not fail the run.

Required vs. optional, by ecosystem

EcosystemRequiredOptional
Pythonpython3, pippython, uv, poetry, black, mypy, pytest, ruff
Node.jsnode, npmnvm, yarn, pnpm, eslint, prettier, chromedriver
Javajavamvn, gradle
Go—go
Rust—rustc, cargo
C/C++gccclang, cmake, ninja, conan
Utilitiesgit, curl, awk, sed, grep, gzip, tar, makejq, rg, tmux, yq, vim, nano

Full per-tool version-check commands and installation notes live in references/tool-categories.md.

Files

  • assets/check-tools.sh — fast validation script (exit codes, quick checks)
  • assets/environment-diagnostic.sh — comprehensive diagnostic with tools / system / full modes
  • references/tool-categories.md — detailed per-tool breakdown and installation instructions

Extending

The required/optional split lives in assets/check-tools.sh (check_required_tool / check_optional_tool calls), not in this file — to change which tools are required, edit the script.

Mojo Development in Claude.ai Containers

Mojo is a systems programming language from Modular that combines Python-like syntax with C-level performance. This skill handles container setup and execution. For language syntax and semantics, defer to Modular's official skills at github.com/modular/skills — they are authoritative correction layers for pretrained knowledge.

Installation

Install once per session (~20s via uv, ~500MB). Skip if already installed.

if mojo --version 2>/dev/null; then
  echo "Mojo already installed"
else
  # Compiler binary without ML extras (~350MB saved)
  uv pip install --system --break-system-packages modular --no-deps 2>&1 | tail -5
  # Entry points + base deps (numpy, pyyaml, rich)
  uv pip install --system --break-system-packages mojo max 2>&1 | tail -5
  mojo --version
fi

Verify:

echo 'def main(): print("Mojo ready")' > /tmp/_verify.mojo && mojo /tmp/_verify.mojo

Running Mojo Code

Quick tests (write to temp file):

cat > /tmp/test.mojo << 'EOF'
def main():
    print("hello")
EOF
mojo /tmp/test.mojo

File execution (JIT compile + run, ~1.4s overhead):

cat > /home/claude/example.mojo << 'EOF'
def main():
    print("Hello from Mojo")
EOF
mojo /home/claude/example.mojo

Build binary (for benchmarking — ~6s cold compile, but binary runs at native speed):

mojo build /home/claude/example.mojo -o /home/claude/example
/home/claude/example

Use mojo build for benchmarks — mojo (JIT) includes ~1.4s compilation overhead per run. There is no mojo -e flag; always write to a file.

Critical Syntax Corrections (v26.2)

Pretrained models generate outdated Mojo. These corrections are current as of Mojo 26.2:

Wrong (pretrained)Correct (26.2)Notes
fn main():def main():fn is deprecated; def is the only function keyword
let x = 5var x = 5let removed; var for all bindings
inout selfmut self / out selfmut for mutation, out for __init__
@parameter forcomptime forCompile-time loops
List[Int](1, 2, 3)[1, 2, 3]Collection literals
from math import sqrtfrom std.math import sqrtstd. prefix required for all stdlib modules
from time import Xfrom std.time import XIncludes perf_counter_ns, sleep, etc.
__str__ / Stringablewrite_to / WritableString conversion protocol
String(self.x) for int→strString(self.x)This one is actually correct, but str() is not
list.append(item)list.append(item^)Non-copyable types require ^ transfer operator
var x: Int = perf_counter_ns()var x: UInt = perf_counter_ns()Time functions return UInt, not Int
Implicit copy of List[T].copy() or ^ transferList is not implicitly copyable; use explicit copy or move

Companion Skills (Modular Official)

These skills from github.com/modular/skills provide deep syntax correction layers. If they are installed in the user's skill set, read them before writing Mojo code:

  • mojo-syntax — Comprehensive syntax corrections, type system, ownership model. Always use when writing any Mojo code.
  • mojo-python-interop — Calling Python from Mojo, type conversion, extension modules. Use when mixing Mojo and Python.
  • mojo-gpu-fundamentals — GPU programming (no CUDA syntax — Mojo has its own model). Reference only in Claude.ai containers (no GPU available).
  • new-modular-project — Project scaffolding with Pixi or uv. Use when starting a new Mojo/MAX project locally.

If companion skills are not installed, the correction table above covers the most common pretrained errors. For deeper work, fetch the skill content directly:

curl -sL -H "Authorization: token $GH_TOKEN" \
  -H "Accept: application/vnd.github.v3.raw" \
  "https://api.github.com/repos/modular/skills/contents/mojo-syntax/SKILL.md?ref=main"

Container Constraints

  • No GPU: Claude.ai containers are CPU-only. GPU skills are reference material for generating code the user will run locally.
  • Session-ephemeral: Mojo installation doesn't persist across conversations. Reinstall each session.
  • Build artifacts: Store in /home/claude/. Copy final outputs to /mnt/user-data/outputs/.
  • Timeout: Long compilations or benchmarks may hit the ~200s bash timeout. Break work into smaller units.

Benchmarking Pattern

Compare Mojo vs Python on the same algorithm:

# Python baseline
python3 -c "
import time
def fib(n):
    a, b = 0, 1
    for _ in range(n):
        a, b = b, a + b
    return a
# Warmup + timed runs
fib(90)
times = []
for _ in range(100):
    start = time.perf_counter()
    fib(90)
    times.append((time.perf_counter() - start) * 1e6)
import statistics
print(f'Python: median={statistics.median(times):.1f} µs, min={min(times):.1f} µs')
"

# Mojo version
cat > /home/claude/fib.mojo << 'EOF'
from std.time import perf_counter_ns

def fib(n: Int) -> Int:
    var a = 0
    var b = 1
    for _ in range(n):
        var tmp = a
        a = b
        b = tmp + b
    return a

def main():
    # Warmup
    _ = fib(90)
    
    # Timed runs
    var total_ns: UInt = 0
    var min_ns: UInt = 999999999
    for _ in range(100):
        var start = perf_counter_ns()
        _ = fib(90)
        var elapsed = perf_counter_ns() - start
        total_ns += elapsed
        if elapsed < min_ns:
            min_ns = elapsed
    print("Mojo: mean =", total_ns // 100, "ns, min =", min_ns, "ns")
EOF
mojo build /home/claude/fib.mojo -o /home/claude/fib
/home/claude/fib

Expected: Mojo is ~50x faster than CPython on tight numeric loops. SIMD and parallelism widen the gap further but require mojo-syntax and mojo-gpu-fundamentals skills for correct usage.

Compiling WGSL

scripts/forge is a pure-Python WGSL toolchain (numpy is the only dependency): a parser that follows the spec's template-list rules, a minifier, a shape compiler, and a GLSL front end that rewrites WebGL and Shadertoy GLSL for naga (and glslang) to translate. It came from oaustegard/experiments/wgsl-forge, whose RESULTS.md holds the measurements quoted here. Set SKILL=/mnt/skills/user/compiling-wgsl (or this directory) and run every command with PYTHONPATH=$SKILL/scripts.

When NOT to use this skill

SituationUse instead
A raster image (photo, PNG) should become vector shapesimage-to-svg, then this skill on its SVG
The output is a PNG, PDF or SVG file rather than a shaderdrawing-with-pycairo
Charts or dashboardscharting, charting-vega-lite
HLSL or Metalnot covered; naga reads SPIR-V (naga in.spv out.wgsl), so HLSL can go through DXC to SPIR-V first
GLSL for desktop OpenGL with #version 330 or older, or code using iChannel buffers (multi-pass Shadertoy)converts, but the multi-pass plumbing (render targets, feedback) is host code you write
A shader whose host reads names back by reflection (a binding library that matches struct member or function names)run with --keep name1,name2, or do not rename

Setup

export SKILL=/mnt/skills/user/compiling-wgsl
pip install --break-system-packages numpy pillow          # pillow only for --png
command -v naga || cargo install naga-cli                  # validator; required for GLSL, ~3 min
command -v glslangValidator || apt-get install -y glslang-tools   # GLSL fallback route
node -e "require('playwright')" && echo playwright-ok      # GPU checks need it
python3 $SKILL/scripts/selftest.py                         # ~20 s: every route on bundled fixtures

selftest.py prints missing tools: first if naga, glslang or node is absent. Every other line must read ok.

The GPU checks run headless Chromium on SwiftShader. On claude.ai and Claude Code on the web, Playwright's Chromium is already installed. Elsewhere, point CHROME_PATH at a Chromium binary.

Minify a shader

PYTHONPATH=$SKILL/scripts python3 -m forge minify in.wgsl -o out.wgsl       # prints bytes before -> after
python3 $SKILL/scripts/verify.py minify in.wgsl                             # always run this

verify.py minify validates the output with naga and compiles both versions in Tint. It then runs every compute entry point that binds only buffers on random typed inputs: the original twice and the minified once. It exits 1 on any failure.

Read the result lines:

  • ok compute main bit-identical: the minified kernel computes the same bytes.
  • skip ... original disagrees with itself: the original has a race for this dispatch shape. Pass the real shape with --dispatch 64,1,1.
  • skip ... textures or samplers bound: that shader was compiled, not executed. To prove a render shader unchanged, render it in its real host before and after and compare pixels.

Options:

  • --no-aliases skips the alias a=vec4f; pass. Use it for shaders served gzipped: on the 86-shader corpus that pass saves 1.7% raw bytes but adds 0.9% gzip bytes.
  • --keep a,b protects extra names from renaming and removal.

Entry-point names, override names, binding numbers and attributes are never changed. Struct members spelled like swizzles (x, rgb) or like builtin result fields (fract, exp, whole) are never renamed either.

Expect 30–35% of the original bytes on typical shaders (34% on the corpus, against 56% for LucentFlux wgsl-minifier on the files both handle). Shaders that are already terse land nearer 50%: Tilt Rally's nine came out at 51%.

python3 -m forge fmt out.wgsl pretty-prints minified code for reading.

Convert GLSL to WGSL

PYTHONPATH=$SKILL/scripts python3 -m forge glsl shader.frag -o shader.wgsl [--minify]
python3 $SKILL/scripts/verify.py glsl shader.frag --png /tmp/port.png               # always run this
PYTHONPATH=$SKILL/scripts python3 -m forge html toy.glsl -o preview.html            # Shadertoy only

The input kind is detected automatically:

inputdetected byoutput
ShadertoymainImage and no mainthe same interface as compiled scenes: uniform {r, t} at binding 0, vs and fs entries; y flipped to Shadertoy's bottom-left origin, alpha forced to 1
WebGL 2 (#version 300 es) or WebGL 1 (no version)version lineone WGSL entry point main; loose uniforms gathered into one std140 block at binding 0, each sampler2D split into a texture and a sampler from binding 1
Vulkan GLSL 450#version 450passed through as written

The stage comes from the extension (.vert, .frag, .comp) or from the content (gl_Position, local_size_x). --stage overrides it.

forge glsl prints the binding lines the host must now supply, with byte offsets. A WebGL program set uniforms by name; WebGPU writes one buffer at those offsets, and std140 puts a vec3 or mat3 column on a 16-byte boundary. note: lines report every rewrite the converter made.

Translation goes through naga's GLSL reader. When naga refuses the source, it is compiled to SPIR-V with glslang and naga translates that instead (--backend forces either). The glslang route accepts more GLSL but mangles function names; minifying renames them anyway.

verify.py glsl validates and compiles both the WGSL and its minified form.

  • Shadertoy code is also rendered by Chrome's WebGL2 as the reference and by the WGSL on WebGPU, at t=0 and t=1.7. It must reach 30 dB PSNR, and the minified version must draw identically.
  • Other GLSL has no reference renderer, so it is compiled only. To check a compute port, run the WGSL with scripts/forge/gpu.py run_jobs (kind compute) and compare the result with a numpy version of the algorithm.

Compile an SVG to a shader

PYTHONPATH=$SKILL/scripts python3 -m forge svg icon.svg --minify -o icon.wgsl
python3 $SKILL/scripts/verify.py svg icon.svg --size 512 --png /tmp/check.png
PYTHONPATH=$SKILL/scripts python3 -m forge html icon.svg --minify -o preview.html   # live page with host code

Read every warning: line. Skipped elements (text, image, clipPath, mask, filter, pattern, marker) are missing from the shader. verify.py svg reports mean error, PSNR and an ink ratio against Chromium's own SVG rendering. When anything was dropped, it also scores against Chromium rendering the SVG with those parts removed (text, masks, clips, filters, animations), and the pass/fail uses that second score. The first score tells you how much the dropped parts mattered; the second tells you whether what was compiled is right. Then Read the PNG: reference | shader | difference ×4.

The shader's interface is fixed:

  • @group(0) @binding(0) var<uniform> u: U with struct U { r: vec2f, t: f32 }, which holds the canvas size in pixels and the time in seconds (16-byte buffer: [w, h, t, 0]).
  • Vertex entry vs; draw 3 vertices, no vertex buffers.
  • Fragment entry fs, which returns premultiplied RGBA (alphaMode: "premultiplied").

forge html writes a working host page to copy from.

Self-painting. --paint-in 4 (Scene(paint_in=4)) makes the shapes appear one by one in paint order over 4 seconds of the time uniform, each fading in over its own slot. --loop holds the finished picture, then starts again, and forge html shows it live. Table rows stop the loop at the first unrevealed row, so early frames are also cheaper to draw. The reveal follows SVG order (back to front), because reordering overlapping shapes would change the picture. verify.py svg X.svg --paint-in 4 checks the contract:

  • t=0: only the background shows.
  • While painting: no pixel's coverage ever decreases. Ink can legitimately fall when light shapes paint over dark ones, so coverage is the measure.
  • Finished frame: bit-identical to the static shader, minified or not.

Size against accuracy. --grid N (Scene(grid=N)) sets the path coordinate step, 1/N of a nominal pixel. The default of 64 sits at the knee. On Twemoji's lion at 512 px, grid 16 saves 10% of gzip bytes and costs 4.6 dB, and grid 128 adds 4% for 0.6 dB. Rounding float literals to fewer digits was measured and rejected. Literals are already short, so rounding to 5 digits saved 0.3% of a scene shader's bytes and 0.05% of a hand-written one's, and it changed pixels.

Large scenes (matplotlib output, traced images, icon sets).

  • Shape table: four or more consecutive plain shapes become rows in a table that one loop draws. A plain shape is a static path or primitive with a solid fill or stroke.
  • Storage buffer: path data over 8,192 ints moves out of the shader into a storage buffer at @group(0) @binding(1) (var<storage, read> D: array<i32>). forge svg -o x.wgsl then also writes x.bin, which the host uploads. scene.data_buffer holds the same bytes in Python, and forge html embeds them.
  • Segment warning: a scene with more than 20,000 path segments is flagged, because a pixel walks every segment of every shape whose bounding box covers it.

Build a scene in Python

Use this when the shapes come from code, need animation, or need operations SVG lacks. references/scene-api.md lists the whole API; references/example_scene.py is a complete animated scene.

from forge.scene import Scene, T, sin, radial, smooth_union, Circle
s = Scene(320, 200, background="#101418")
s.circle(160, 100, 40 + 4 * sin(T * 2), fill=radial(160, 100, 50, ["#fff7d6", "#ff8a3d"]))
with s.group(translate=(160, 100), rotate=T * 30):
    s.rect(-2, -80, 4, 20, rx=2, fill="#ffd36e")
s.add(smooth_union(Circle(60, 150, 25), Circle(90, 150, 20), k=12), fill="hotpink")
open("scene.wgsl", "w").write(s.compile(minify=True))
open("frame.svg", "w").write(s.to_svg(t=1.3))     # reference frame for checking

Any number can be an expression in T. Check an animated scene at a time where its animated terms are large, not just at t=0: render the shader with time set and compare it with Chromium rendering to_svg(t). scripts/forge/gpu.py's run_jobs takes render and svg jobs with a time field. SDF-only features (smooth_union, subtract, intersect, rounded, onion, soft) make to_svg raise, because SVG cannot express them. Check those by rendering and reading the image.

When to abandon it

  • The SVG relies on unsupported features. If warnings list text, clipPath, mask or filter and those carry the design, the shader will be wrong. Rasterise instead, or convert text to paths first.
  • The shader is too slow. Every pixel loops over every path segment. A scene with thousands of segments (a detailed illustration, a map) is too heavy as one shader: draw it as triangles, or bake it to a texture.
  • A shader under 1 KB. Expect only small gains, so minify only if bytes really matter.

Failure modes

  • naga could not translate the GLSL and glslang also fails → read glslang's message. It is usually real GLSL that Vulkan forbids, such as a sampler passed as a function argument (a note: names it). Rewrite that part by hand: pass the texture and sampler separately.

  • Tint compiles WGSL FAILs with unresolved call target 'subgroupBarrier' → the WGSL came from an older copy of this converter. Since 0.2.0 it strips the subgroup and texture barriers that naga adds for GLSL barrier(), keeping workgroupBarrier().

  • A WebGL port renders but the colours or positions are wrong → check the uniform buffer against the binding offsets that forge glsl printed. The usual mistake is a vec3 written tightly packed instead of on its 16-byte boundary.

  • A Shadertoy port renders upside down in your own host → you dropped the fragCoord flip. The shader expects the uniform r to hold the canvas size in pixels.

  • Integer % or division differs from WebGL for negative operands → GLSL leaves these undefined, and the WGSL takes one definite answer. Rewrite the GLSL to stay non-negative.

  • naga says expected array<i32, 2>, but got array<i32, 2> → this is naga 30's quirk with an alias inside a template argument. The alias pass already avoids it; if it appears, rerun with --no-aliases and report the input.

  • Tint compiles the minified shader but not the original → expected when dead-code removal drops unused code that Tint rejects; the reachable code is unchanged. Two naga test files do this.

  • compute ... bit-identical FAILs with a 2-D or 3-D --dispatch → probably a race in the original: invocations that share id.x write the same element, and two original runs happened to agree. Rerun with the host's real dispatch shape before believing it. Diagnosed 2026-11-02 on Tilt Rally's SMOKE_SIM: 4×4 failed, while 4×1 was identical on three seeds.

  • The harness prints harness failed or every GPU job errors → Chromium or WebGPU is unavailable. Check node -e "require('playwright')", set CHROME_PATH, and keep the --enable-unsafe-webgpu --use-webgpu-adapter=swiftshader flags that scripts/harness/gpu.mjs passes.

  • Small text or hairlines look bolder than in the browser (ink ratio 1.03 to 1.07 on text-heavy charts) → antialiasing works from one distance per shape, so a feature thinner than a pixel gets about half a pixel of coverage too much. The geometry is right. Render larger, or accept it. Measured on a matplotlib chart whose labels are glyph outlines: ink ratio 1.067 at 512 px.

  • warning: N path segments, and a frame takes seconds → per-pixel cost is the number of segments under the pixel. Simplify the paths (fewer points) or bake the image to a texture; this compiler has no tile binning.

  • colour 'var(...)' unsupported → a custom property the reader could not resolve. Plain var(--x) from CSS rules, inline styles and @property initial values is supported. A malformed name stays unresolved and paints black, which is what the browser does with the invalid declaration too.

  • The ink ratio is below 0.97 or above 1.03 at large sizes → a geometry error, not antialiasing: antialiasing error shrinks as size grows, and geometry error does not. Compare verify.py svg --size 128 with --size 768.

  • Curves look faceted at extreme zoom → curves are fitted to 0.02 of the SVG's own pixel, which holds to about 50× magnification. Lower it with --tolerance 0.02; the default is 0.2, of which a tenth goes to the curve fit.

Verification

  • Minifier: verify.py minify must print no FAIL. A good result passes naga, compiles in Tint and gives bit-identical compute buffers. A bad success compiles but computes something else: a renamed name the host looks up, or a shader with textures that was only compiled. For the second case, render it in its host before and after and compare pixels.
  • GLSL: verify.py glsl must print no FAIL, and for Shadertoy code the PNG rows (WebGL | WGSL | difference ×8) must show the same picture. A bad success is two blank images that match: check that the picture has content. Another is a non-Shadertoy port that compiles but was never run against anything.
  • SVG: verify.py svg must print no FAIL, and the PNG must look right. A bad success is a high PSNR on an SVG whose warning: lines show that elements were dropped. A missing element still scores well when it is small.

Diagnosed failures (fixed, kept as signals)

  • 2026-11-02, paint-in check: the first version required ink to rise from frame to frame. It failed on Twemoji's lion, where the dark mane paints first and the light face covers it, so ink fell from 131% to 100% of the final value. That is correct painter's order. The invariant is coverage per pixel, which is what the check now measures.

  • 2026-11-02, real Python-made SVGs from the experiments repo:

    • matplotlib Pareto chart: 235 KB of unrolled WGSL killed SwiftShader's pipeline compiler ("A valid external Instance reference no longer exists"). The shape table fixed it: 6.7 KB of WGSL, 29.0 dB.
    • Palette-cycling cat: 880 shapes broke Tint's array-constructor limit ("excessive number of elements (>32767)"). The storage buffer fixed it: 34.2 dB, ink ratio 1.000.
    • Traced dog: same limit. With the buffer and masks excluded it scored 41.0 dB, but took 215 s per frame on SwiftShader, which led to the segment warning.
    • Also found: a missing f prefix in svg-palette-cycle/build.py writes the literal var(--b{len(BANDS) - 1}) into its SVG.
  • 2026-11-02, a switch case that returns: naga's GLSL reader rejected switch (i) { case 0: return a; ... } ("fall-through switch case block"), even with a break; after the return. The auto backend now falls back to glslang.

  • 2026-11-02, subgroupBarrier: GLSL barrier() came out of naga as four barriers, subgroupBarrier() among them, and Tint rejects that call. naga validated the output, so only the Tint compile in verify.py caught it.

  • 2026-11-02, html preview: forge html had never worked in 0.1.0. A % in its CSS broke the %-formatting of the page template, and nothing ran the command until the GLSL work. selftest.py now covers every route.

  • 2026-11-02, zero error that looked suspicious: every Shadertoy fixture matched WebGL at 0 error. The images were checked and are real: WebGL and WebGPU both run on SwiftShader in the container. Expect small floating-point differences on real GPUs, hence the 30 dB bar rather than exact equality.

  • 2026-11-01, line segments: flattening curves to line segments at the SVG's size left icons 1.8% too light at 512 px (ink ratio 0.982), and the error never shrank with size. The fix was to keep curves as quadratic Béziers with exact distance. The signal was the ink ratio at two sizes.

  • 2026-11-01, missing parentheses: an animated radius compiled without parentheses, - 44+3*sin(..). Frames at t=0 and t=4.7 still matched closely, because the animated term was near zero there, and t=1.3 diverged visibly. The lesson: test animation at large values of its animated terms.

  • 2026-11-01, packed arc flags: 0 014.907 was misread, and two Simple Icons logos failed to parse. No hand-written test packed flags that way.

composing-html

Produce single-file HTML artifacts without hand-writing the page chrome. The composer supplies <!DOCTYPE>, <head>, inlined CSS, base.js, design tokens, masthead, and colophon. You supply a title and the body content.

The product is the chrome and inventory below — primitives you can drop into any artifact without re-deriving what a card, badge, or eyebrow looks like. Templates are shortcuts on top of this, useful when the same artifact shape repeats; see Templates near the end.

Default workflow: freeform

freeform gives you the whole chrome with one content slot — body_html — for the page body. Reach for it first. Reach for a template only when the structure repeats across artifacts (see Templates near the end).

There are two ways to invoke it. Use the --set flow for anything with a substantial body — it sidesteps the JSON-string escaping that bites heredoc-style spec writing (newlines, quotes, </& inside multi-line HTML).

Recommended: HTML in a file, metadata via --set

1. Write the body to a .html file directly (no JSON, no escaping).
2. python scripts/build.py build freeform \
       --set title='My Page' \
       --set subtitle='Optional subhead' \
       --set body_html=@body.html \
       --out artifact.html

--set KEY=VALUE assigns a literal string; --set KEY=@FILE loads the file contents verbatim into that spec field. Repeat for any field. Works for body_html, extra_css, extra_js, eyebrow, page_class, and the same *_html fields in any other template (summary_html, intro_html, details_html, …).

Spec-file workflow (best for structured templates)

1. python scripts/build.py describe <template>     # required keys + skeleton
2. write spec.json
3. python scripts/build.py build <template> --spec spec.json --out artifact.html

For templates with typed slots (pr_review.findings[], slide_deck.slides[], status_report.metrics[]), the spec file is the right shape — the template reasons over the structure. For freeform, the spec is mostly a thin config wrapper around one HTML string; the --set flow above is usually less friction.

You can mix both: small spec.json for metadata, --set body_html=@body.html for the heavy bit. --set overrides any matching field from --spec.

Pitfall: don't inline multi-line HTML into a JSON heredoc

cat > spec.json <<EOF { "body_html": "<multi\nline>\n..." } EOF does not produce valid JSON — JSON strings can't contain raw newlines or unescaped quotes. Either:

  • use --set body_html=@body.html (recommended), or
  • assemble the spec in Python with json.dump(spec, f) so escaping is automatic.

Inventory

Everything in this section is loaded into every artifact via inlined CSS and base.js. Use these tokens and classes inside body_html (or any template's *_html field) without re-declaring them.

Color tokens

TokenHexUse
--ivory#FAF9F5Page background
--paper#FFFFFFCard background
--slate#141413Headings, inverted background
--clay#D97757Brand accent (lines, primary actions)
--clay-d#B85C3EHover/dark variant
--oat#E3DACCSoft contrast surface
--olive#788C5DSuccess, secondary accent
--rust#B04A3FErrors, destructive
--moss#4A6B3ASuccess text
--g100 … --g700graysSurfaces, borders, body text

Semantic aliases: --ok, --warn, --err, --info.

Type stacks

  • --serif — display headings (h1, h2, big numerics).
  • --sans — body text (default).
  • --mono — code, eyebrows, badges, captions.

Geometry

--radius-sm (6px) · --radius (10px) · --radius-lg (16px) · --border · --border-soft · --shadow-card · --shadow-pop.

Layout primitives

  • .page — main column (1080px max). Variants: .page--wide (1280px), .page--narrow (720px). Set via the page_class spec key.
  • .masthead — header strip with .eyebrow + <h1> + .subtitle (auto-rendered from title/subtitle/eyebrow unless show_masthead is false).
  • .grid .grid--2|3|4|auto — responsive CSS grid.
  • .stack, .row — vertical / horizontal flex.
  • .card, .card--soft, .card--elev — content containers.
  • .rule — <hr> underline below <h2>.
  • .colophon — optional footer strip; pass colophon="text" to page() to show it (off by default).

Components

  • Eyebrow: <div class="eyebrow">SECTION</div> — small all-caps label with a leading clay rule.
  • Badge: <span class="badge badge--ok|warn|err|info|clay">v1.0</span>.
  • Kbd: <span class="kbd">⌘K</span>.
  • Bullets: <ul class="bullets"><li>…</li></ul> — clay dots.
  • Code: inline <code> and block <pre><code>. Block code gets a copy button automatically via base.js.
  • Details: native <details><summary>…</summary>…</details> styled.

Tabs

<div class="tabgroup">
  <div class="tabs">
    <button data-target="a">Tab A</button>
    <button data-target="b">Tab B</button>
  </div>
  <div class="tab-panel" data-id="a">…</div>
  <div class="tab-panel" data-id="b">…</div>
</div>

base.js wires this automatically and selects the first tab by default.

Drag-to-reorder

<div data-sortable="true">
  <div draggable="true">…</div>
  <div draggable="true">…</div>
</div>

Optional cross-zone drops: add data-zone="<id>" to each container.

Live parameter bindings

<input type="range" data-bind="size" min="0" max="100" value="50" data-format="number" data-unit="px">
<span data-out="size"></span>
<style>.box { width: var(--bind-size, 50px); }</style>

The CSS custom property --bind-<name> is updated on every input event, and any [data-out="<name>"] element receives the formatted value.

Output rules

Spend output tokens on content, not chrome:

  1. Never write <html>, <head>, <style>, <script>, or <link>. The composer adds all of them. If you find yourself writing a complete page, you missed the skill.
  2. Don't restate design tokens. Reuse the inventory above — var(--clay), .card, .badge--warn, .bullets, etc. are already loaded. Don't hardcode hex/rgb() colours, inline font-family/font-size, or reference tokens that aren't in the palette.
  3. body_html is HTML, not a JSON dialect. Write <section>, <h2>, <ul class="bullets"> directly. No translation layer.
  4. Anything in an _html field is inserted verbatim — escape any user-supplied content yourself. All other string values are HTML-escaped automatically.
  5. One artifact per build. Browser tabs are free.

Checking output

After building, lint the artifact before presenting it:

python scripts/build.py check artifact.html

The checker is deterministic — no model call, stdlib only. It doesn't grade taste (the fixed chrome already prevents the usual AI tells); it flags content that breaks out of the design system or wires base.js hooks to nothing — the failure modes the chrome can't prevent on its own:

rulecatchesseverity
chrome-leak<html>/<head>/<link> (and top-level <style>/<script>) in body_htmlerror
undefined-tokenvar(--typo) — a token not in the palette or declared hereerror
broken-tabsdata-target with no matching .tab-panel[data-id]error
hardcoded-color#hex / rgb() literals instead of palette tokenswarn
inline-typographyfont-family / font-size overriding the type stackswarn
undefined-token for --bind-*(allowed — created by data-bind)—
nested-card.card inside .cardwarn
broken-binddata-bind with no consumer, or orphan data-outwarn
broken-sortabledata-sortable with no draggable childrenwarn
heading-skipheading levels that jump (h1 → h3)warn
img-no-alt<img> without an alt attributewarn

Exit code is non-zero when any error-severity rule fires. The output rules above carry <!-- rule:ID --> anchors tying each guidance line to its check, so the teaching and the enforcement stay in sync. Full-artifact vs body fragment is auto-detected; force with --full / --fragment. --json emits machine-readable findings. Contrast ratios are intentionally not checked — the token pairs are pre-vetted and regex can't judge author-introduced pairs without false positives.

Iteration

Edit the spec, re-run build, open in a browser. If a layout pattern repeats across multiple artifacts, that's when a template earns its keep — otherwise stay in freeform.

Templates: shortcuts for repeat structure

When the same artifact shape recurs (status reports week after week, PR reviews across many PRs, slide decks with consistent navigation), a template's fixed slot map is worth the translation cost. It enforces cross-artifact consistency and skips the layout decisions you'd otherwise re-derive each time.

Use a template only when:

  1. You're producing the same artifact shape repeatedly.
  2. The repeat structure justifies a fixed slot map.
  3. Cross-artifact consistency matters more than per-artifact flexibility.

Otherwise: freeform.

1. python scripts/build.py list                    # all templates, one-line summaries
2. python scripts/build.py describe <template>     # required keys + JSON skeleton
3. write spec.json                                  # only your content + parameters
4. python scripts/build.py build <template> --spec spec.json --out artifact.html

describe prints a valid-JSON starter skeleton you can edit in place. For worked examples, see references/templates.md — but only after picking a template; reading it cold wastes context.

For templates with prose-heavy *_html slots (e.g. summary_html, intro_html, details_html), the same --set KEY=@FILE mechanism from the freeform workflow applies — load the prose from a .html file rather than escaping it into the JSON spec.

There are 21 templates, grouped into 9 categories plus freeform:

  • report.* — status_report, incident_report
  • review.* — pr_review, code_walkthrough, module_map
  • editor.* — triage_board, flag_editor, prompt_tuner
  • deck.* — slide_deck (arrow-key + space navigation)
  • design.* — design_system, component_variants
  • exploration.* — comparison_grid, design_directions, implementation_plan
  • research.* — feature_explainer, concept_explainer
  • diagram.* — svg_figure_sheet, flowchart
  • prototype.* — animation_sandbox, click_flow

Some templates with prose-heavy slots take raw HTML in keys ending with _html (e.g. summary_html, intro_html, details_html). Same rules as freeform.body_html: use the inventory above, escape user-supplied content.

Tests

tests/test_smoke.py covers every template with a representative spec plus explicit security regressions (table escaping, script-tag breakout in prompt_tuner, attribute injection in flag_editor, CSS-color injection, spec mutation in module_map). tests/test_checker.py covers the check linter — one assertion per rule (fires on the violation, silent on the clean case). Run with:

python composing-html/tests/test_smoke.py        # no pytest required
python composing-html/tests/test_checker.py      # no pytest required
python -m pytest composing-html/tests -q          # if pytest is available

When adding or changing a template, add a spec entry and any regression asserts before merging. When adding a checker rule, add it to both scripts/checker.py and a <!-- rule:ID --> anchor in the relevant guidance line, plus a test assertion.

Bookmarklet Creation

Critical Requirements

Comment Style - ABSOLUTE

Use ONLY /* */ comments. NEVER use // comments.

Bookmark execution contexts fail with // style. Every comment must use block format.

/* ✓ Correct */
const x = 5; /* inline */

/* ✗ Wrong - breaks bookmarklets */
// const x = 5;
const y = 10; // inline

IIFE Wrapper

All bookmarklets must wrap in IIFE:

(function() {
  /* bookmarklet code */
})();

Protocol Prefix

All delivered bookmarklets must begin with javascript: protocol:

javascript:(function() {
  /* bookmarklet code */
})();

This makes the code immediately usable without requiring manual modification during installation.

Workflow

1. Generate Pretty-Printed Code

Create readable source with:

  • 2-space indentation
  • Descriptive variable names
  • Block comments for key sections
  • Logical organization
  • Prepend javascript: protocol to the code

This version with javascript: prefix gets stored in GitHub and shown to users, making it ready for installation without manual modification.

2. Provide Installation

Default approach - reference installer:

Install: https://austegard.com/web-utilities/bookmarklet-installer.html

Installer handles:

  • Minification with Terser
  • URL encoding
  • Draggable link generation
  • GitHub repo integration

Alternative - generate link programmatically: Use Terser.js to create installable link if requested:

async function createBookmarkletLink(code, title) {
  const minified = await Terser.minify(code);
  const encoded = encodeURIComponent(minified.code).replace(/'/g, "%27");
  return `<a href="javascript:${encoded}">${title}</a>`;
}

Requires: <script src="https://cdn.jsdelivr.net/npm/terser/dist/bundle.min.js"></script>

3. Deliverables

Always provide:

  1. Pretty-printed source code with javascript: protocol prepended
  2. Installation method (installer link or generated link)
  3. Brief description of functionality
  4. Usage instructions

The code should be delivered in a format ready for direct use - users should be able to copy the entire code block (including javascript:) without modification.

Code Standards

Error Handling

(function() {
  try {
    /* main logic */
  } catch (error) {
    console.error('Bookmarklet error:', error);
    alert('Operation failed: ' + error.message);
  }
})();

Console Logging

Include debug traces by default:

console.log('Bookmarklet: Starting');
/* operations */
console.log('Bookmarklet: Complete');

User Feedback

/* Success */
alert('✓ Content copied to clipboard');

/* Error */
alert('✗ Failed to access clipboard');

Common Patterns

DOM Manipulation

(function() {
  const element = document.querySelector('.target');
  if (!element) {
    alert('Element not found');
    return;
  }
  /* manipulate element */
})();

Data Extraction

(function() {
  const data = Array.from(document.querySelectorAll('.item'))
    .map(item => ({
      title: item.querySelector('.title')?.textContent.trim(),
      value: item.querySelector('.value')?.textContent.trim()
    }));
  
  console.log('Extracted:', data);
})();

Clipboard Operations

(function() {
  const text = 'content to copy';
  navigator.clipboard.writeText(text)
    .then(() => alert('✓ Copied'))
    .catch(err => {
      console.error('Clipboard error:', err);
      alert('✗ Copy failed');
    });
})();

Dynamic Library Loading

(function() {
  if (typeof someLibrary === 'undefined') {
    const script = document.createElement('script');
    script.src = 'https://cdn.example.com/library.js';
    script.onload = function() {
      /* proceed with logic */
    };
    document.head.appendChild(script);
  }
})();

Browser Compatibility

Provide fallbacks for unsupported features:

if (!navigator.clipboard) {
  alert('Clipboard API not supported');
  return;
}

Constraints

Cannot use:

  • External files (CSS, images) without embedding
  • Build tools or preprocessing
  • // style comments

Can use:

  • Fetch API
  • localStorage/sessionStorage
  • Modern browser APIs
  • CDN libraries (loaded dynamically)

Testing

Before delivering:

  1. Verify no // comments exist
  2. Test in browser console wrapped in IIFE
  3. Check error handling with missing DOM elements
  4. Verify user feedback for all paths

Example Output

javascript:(function() {
  /* Pretty-printed bookmarklet code */
})();

Install: https://austegard.com/web-utilities/bookmarklet-installer.html

Extracts all links from current page and copies to clipboard as markdown list. Works on any webpage.

GitHub Storage

User repository: https://github.com/oaustegard/bookmarklets

Pretty-printed format matches storage requirements. Installer loads directly from this repo.

Creating MCP Servers

Build production-ready MCP servers using FastMCP v2 with optimal context efficiency through progressive disclosure patterns.

Core Capabilities

  1. Apply the core patterns - Four requirements for consistency
  2. Implement progressive disclosure - Gateway patterns achieving 85-93% token reduction
  3. Optimize tool descriptions - 65-70% token reduction through proper patterns
  4. Bundle servers - Package as MCPB files with validation
  5. Proven gateway patterns - Three complete implementations (Skills, API, Query)

Architecture Decision

1-3 simple tools?
  → Standard FastMCP with optimized tools
  Load: references/MANDATORY_PATTERNS.md

5+ related capabilities?
  → Gateway pattern (progressive disclosure)
  Load: references/PROGRESSIVE_DISCLOSURE.md
  Load: references/GATEWAY_PATTERNS.md

Optimize existing server?
  → Apply mandatory patterns
  Load: references/MANDATORY_PATTERNS.md

Package for distribution?
  → MCPB bundler
  Load: references/MCPB_BUNDLING.md
  Execute: scripts/create_mcpb.py

Need FastMCP documentation?
  → Search references/LLMS_TXT.md for relevant URLs
  → Use web_fetch on gofastmcp.com URLs

Mandatory Patterns (Summary)

Every implementation should meet these four requirements:

  1. uv (never pip) - uv pip install fastmcp
  2. Optimized tool descriptions - Annotations, Annotated, concise docstrings
  3. Authoritative documentation - Fetch from gofastmcp.com via LLMS_TXT.md index
  4. Apply all patterns - Every implementation meets verification checklist

Details in references/MANDATORY_PATTERNS.md

Documentation Retrieval Workflow

To fetch FastMCP documentation:

1. Read references/LLMS_TXT.md - complete URL index
2. Search for relevant topic keywords
3. Use web_fetch on matched URLs (append .md for markdown)
4. Apply patterns from fetched documentation

Example: Authentication patterns → Search LLMS_TXT.md for "authentication" → web_fetch https://gofastmcp.com/servers/auth/authentication.md

Progressive Disclosure Pattern

For servers with 5+ capabilities:

Three-tier loading:

  1. Metadata (~20 tokens/capability) - Always loaded
  2. Content (~500 tokens) - Load on demand
  3. Execution (0 tokens) - Execute without loading

Achieves 85-93% baseline reduction. See references/PROGRESSIVE_DISCLOSURE.md

Implementation Phases

Phase 1: Research

Read LLMS_TXT.md → Find relevant URLs → web_fetch documentation

Phase 2: Implement

Load appropriate reference based on architecture decision. Apply all four patterns.

Phase 3: Package (Optional)

cd /home/claude
zip -r server-name.mcpb manifest.json server.py README.md
cp server-name.mcpb /mnt/user-data/outputs/

See references/MCPB_BUNDLING.md for manifest format.

Reference Library

Documentation index (load first for FastMCP knowledge):

Core patterns:

Implementation:

Scripts:

  • scripts/create_mcpb.py - Bundle MCP servers into .mcpb files

Verification Checklist

Before completing any FastMCP implementation:

✓ Uses uv (not pip)
✓ FastMCP docs fetched from LLMS_TXT.md URLs (not web_search)
✓ Tool annotations (readOnlyHint, title, openWorldHint)
✓ Annotated parameters with Field
✓ Single-sentence docstrings
✓ 65-70% token reduction vs verbose
✓ Server instructions concise (<100 chars)

For gateway implementations, additionally verify:

✓ 85%+ baseline context reduction
✓ Discover returns metadata only
✓ Load fetches content on demand
✓ Execute runs without context cost

Tool Description Pattern

Before (180 tokens):

@mcp.tool()
async def search_items(query: str):
    """Search for items in the database.
    This tool allows comprehensive searching..."""

After (55 tokens):

@mcp.tool(
    annotations={"title": "Search", "readOnlyHint": True, "openWorldHint": False}
)
async def search_items(
    query: Annotated[str, Field(description="Search text")],
    ctx: Context = None
):
    """Search items. Fast full-text search across all fields."""

Common Pitfalls

❌ Using mcpb pack CLI (causes crashes, just use zip)
❌ Using pip instead of uv
❌ web_search for FastMCP docs (use web_fetch on LLMS_TXT.md URLs)
❌ Verbose tool descriptions
❌ Missing tool annotations
❌ Gateway for 1-3 tools (overhead exceeds benefit)
❌ Mixing unrelated capabilities in single gateway

Preact Developer

Overview

Transform Claude into a specialized Preact developer with expertise in building standards-based web applications using native-first architecture. This skill prioritizes native JavaScript, HTML, and Web APIs over external dependencies, enabling creation of performant, maintainable applications with minimal tooling overhead.

Core Philosophy

Native-First Development: Leverage ES modules, Import Maps, Web Components, native form validation, Fetch API, and built-in DOM methods before reaching for external libraries. Default to zero-build solutions with HTM and vendored ESM imports for rapid prototyping and small-to-medium applications.

Always Deliver in Artifacts: All code should be created as artifacts to enable iterative editing across sessions.

When to Use This Skill

Trigger this skill when working on:

  • Preact projects of any complexity level
  • Data visualization applications requiring CSV/JSON parsing and interactive charts
  • Single-page applications using HTM tagged template literals
  • WebGL/shader-based mathematical visualizations
  • Web Components integration projects
  • Zero-build prototypes with CDN-based dependencies
  • Progressive web applications emphasizing accessibility and performance
  • Interactive widgets with keyboard, focus and ARIA requirements (use ui-sdk, below)

Project Type Decision Tree

Follow this decision tree to determine the optimal architecture:

1. Standalone Prototype or Demo

Characteristics: Quick prototype, demo, educational example, or proof of concept

Architecture:

  • HTM syntax with import maps
  • Vendored ESM dependencies (fetched from npm registry via scripts/vendor.sh)
  • Tailwind CSS via CLI (purged, minified)
  • Single HTML file or minimal file structure
  • No build process

Start with: Run bash scripts/vendor.sh to fetch dependencies, then use assets/boilerplate.html as the foundation

2. Small-to-Medium Application (No Build Tooling)

Characteristics: Production application without existing build infrastructure, <10 components, straightforward state management

Architecture:

  • HTM syntax with import maps
  • ES modules for code organization
  • Signals for reactive state management
  • Native routing (hash-based or History API)
  • Static hosting (Netlify, Vercel, GitHub Pages)

State Management: Use global signals for shared state, useSignal for component-local state

3. Complex Application (Build Tooling Required)

Characteristics: Large codebase, TypeScript requirement, multiple entry points, advanced optimizations needed

Architecture:

  • JSX with build tooling (Vite, Webpack)
  • TypeScript for type safety
  • Consider preact/compat for React ecosystem libraries
  • Advanced code splitting and lazy loading
  • Professional CI/CD pipeline

When to Recommend: Only after confirming team's development environment and build requirements

4. Existing Project

Approach: Match existing patterns and tooling. Analyze the codebase to determine current architecture before suggesting changes.

Technical Standards

Import Map Configuration

Always use this exact import map structure for standalone examples. Dependencies are vendored locally via scripts/vendor.sh (fetched from registry.npmjs.org):

<script type="importmap">
  {
    "imports": {
      "preact": "./vendor/preact.module.js",
      "preact/hooks": "./vendor/hooks.module.js",
      "@preact/signals-core": "./vendor/signals-core.mjs",
      "@preact/signals": "./vendor/signals.mjs",
      "htm": "./vendor/htm.module.js",
      "htm/preact": "./vendor/htm.module.js"
    }
  }
</script>

Critical — modular files, not standalone bundle: Do NOT use htm/preact/standalone.module.js. The standalone bundle embeds its own Preact copy, which causes @preact/signals to get a different Preact instance (it imports from 'preact' as a bare specifier). Modular files + import map = one shared Preact instance for everything.

Why vendored, not CDN: esm.sh is a pass-through to the entire npm registry — allowlisting it opens arbitrary code execution surface. registry.npmjs.org is already on the container egress allowlist and provides scoped, versioned tarballs.

Syntax Preference

Default to HTM tagged template literals unless:

  • User explicitly requests JSX
  • Project already uses JSX tooling
  • TypeScript strict mode requires JSX

JSX to HTM Translation Reference

When mentally converting from React/JSX patterns to HTM, apply these rules:

Mental Model

HTM uses JavaScript template literals. Everything that was {expression} in JSX becomes ${expression}. Component names are also expressions, hence <${Component}>.

Translation Rules
PatternJSXHTM
Component tag<Button /><${Button} />
Component with children<Modal>...</Modal><${Modal}>...</${Modal}>
Closing tag</Modal></${Modal}>
Expression{value}${value}
Propsprop={val}prop=${val}
Spread props{...obj}...${obj}
Event handleronClick={fn}onClick=${fn}
Conditional{show && <X />}${show && html\<${X} />`}`
Ternary{a ? <X /> : <Y />}${a ? html\<${X} />` : html`<${Y} />`}`
Map{items.map(i => <Li />)}${items.map(i => html\
  • ...
  • `)}`
    Key Differences
    1. Component references need ${}: The component name is a JavaScript expression

      // JSX
      <Button onClick={handleClick}>Save</Button>
      
      // HTM
      <${Button} onClick=${handleClick}>Save</${Button}>
      
    2. Nested templates for conditional components: When conditionally rendering components (not HTML elements), wrap in html\``

      // JSX
      {isOpen && <Modal title="Hello" />}
      
      // HTM
      ${isOpen && html`<${Modal} title="Hello" />`}
      
    3. No braces for spread: In HTM, spread uses ...${obj} directly

      // JSX
      <Input {...inputProps} />
      
      // HTM
      <${Input} ...${inputProps} />
      
    4. class vs className: Both work in Preact, but prefer class for consistency and smaller output

    Common Mistakes
    MistakeWrongCorrect
    Missing ${} on component<Button><${Button}>
    Wrong closing syntax</MyComponent></${MyComponent}>
    Braces instead of template{count}${count}
    Spread with braces{...props}...${props}
    Missing html wrapper in conditional${show && <${X} />}${show && html\<${X} />`}`

    Component Patterns

    Use function components with:

    • Hooks for lifecycle and side effects
    • Signals for reactive state (preferred over useState)
    • Suspense for code splitting and async data
    • Context API for cross-component state and dependency injection
    • Error boundaries for graceful error handling

    Styling Strategy

    Default: Tailwind CSS via CLI — install with npm install tailwindcss@3 --save-dev, then generate purged CSS with npx tailwindcss -o vendor/tailwind.css --content "*.html" --minify. This produces ~6KB of CSS containing only used classes. Avoid: Tailwind CDN (cdn.tailwindcss.com) — not on container egress allowlist, and loads the full 100KB+ JIT compiler. Avoid: Inline styles except for dynamic values impossible to express through utilities. Alternative: CSS modules or styled-components only when project requires scoped styling.

    Accessible Components (ui-sdk)

    For any widget with a WAI-ARIA pattern (dialog, popover, menu, menubar, select, combobox, autocomplete, listbox, tabs, tooltip, toast, drawer, date picker, slider, tree, toolbar and the rest of 55 components), use ui-sdk instead of writing focus traps, arrow-key handling and ARIA by hand.

    1. Vendor it: ./scripts/vendor.sh ./vendor --ui-sdk (adds preact/compat and vendor/ui-sdk/; prints the import map).
    2. Find the component in references/ui-sdk.md: one entry per component with what it is for, its module (ui-sdk/<name>.js) and its parts.
    3. Before first use, read its Composition section: ./scripts/ui_sdk_docs.sh <name> --section Composition. Docs are React TSX; the same parts and props work in HTM.
    4. Style by state attributes ([data-open], [data-highlighted], [data-selected]) and start the page CSS with @layer ui-sdk;.

    Requires Preact 11 (vendor.sh pins 11.2.0). To see a component in action before using it: https://austegard.com/ai-tools/ui-sdk-preact/#.

    Dependency Evaluation Framework

    Before recommending any external package, verify:

    1. Native Web APIs cannot accomplish this - Check MDN documentation
    2. Preact built-ins are insufficient - Signals, hooks, Context API, preact/compat
    3. Bundle size cost is justified - Measure actual benefit gained vs. bytes added

    Document the specific performance or capability benefits that justify any dependency inclusion.

    Architecture Considerations

    For complex decisions involving:

    • Client-side routing (hash-based vs. History API vs. library)
    • SSR requirements
    • State management architecture (signals vs. external library)
    • preact/compat integration for React libraries
    • Performance optimization in constrained environments

    Evaluate trade-offs explicitly before committing to an approach. Document reasoning in code comments.

    Domain Standards

    Progressive Enhancement

    Ensure core functionality works without JavaScript where feasible:

    • Use semantic HTML
    • Leverage native form validation
    • Implement keyboard navigation
    • Add ARIA attributes for accessibility
    • Manage focus states properly

    Code Quality

    • Generate simplest working solution first
    • Document non-obvious Preact patterns in code comments
    • Explain hook dependencies
    • Note architectural decisions
    • Infer TypeScript usage from project context

    Development Workflow

    1. Understand Requirements

    Clarify:

    • Target environment (standalone vs. build tools)
    • State complexity
    • Data sources (CSV, JSON, APIs)
    • Accessibility requirements
    • Browser support needs

    2. Choose Architecture Pattern

    Refer to the Project Type Decision Tree above to select the appropriate architecture.

    3. Implement Iteratively

    Start with:

    • Basic HTML structure (use assets/boilerplate.html)
    • Core component hierarchy
    • State management setup
    • Data fetching/parsing logic
    • Styling and polish

    4. Reference Documentation

    Consult bundled references as needed:

    • references/preact-v10-guide.md - Comprehensive Preact API reference (written for v10; vendor.sh now ships 11, where function components receive ref as a prop)
    • references/ui-sdk.md - Accessible component catalog and HTM usage
    • references/architecture-patterns.md - Advanced patterns and best practices

    5. Use Component Patterns

    Leverage assets/component-patterns.md for common UI patterns:

    • Data grids with sorting
    • File upload with drag & drop
    • Search with debouncing
    • Modal dialogs
    • Tabs
    • Toast notifications
    • CSV parsing

    Common Patterns

    Data Parsing (CSV/JSON)

    For data-heavy applications:

    import { useSignal } from '@preact/signals';
    
    function parseCSV(text) {
      const lines = text.trim().split('\n');
      const headers = lines[0].split(',').map(h => h.trim());
      return lines.slice(1).map(line => {
        const values = line.split(',').map(v => v.trim());
        return Object.fromEntries(headers.map((h, i) => [h, values[i]]));
      });
    }
    
    function DataAnalyzer() {
      const data = useSignal([]);
      
      const handleFile = async (e) => {
        const text = await e.target.files[0].text();
        data.value = parseCSV(text);
      };
      
      return html`
        <input type="file" accept=".csv" onChange=${handleFile} />
        <div>Loaded ${data.value.length} rows</div>
      `;
    }
    

    WebGL Integration

    For shader-based visualizations:

    import { useEffect, useRef } from 'preact/hooks';
    
    function ShaderCanvas({ fragmentShader }) {
      const canvasRef = useRef(null);
      
      useEffect(() => {
        const canvas = canvasRef.current;
        const gl = canvas.getContext('webgl2');
        
        // Setup WebGL context, shaders, buffers
        // Render loop
        
        return () => {
          // Cleanup
        };
      }, [fragmentShader]);
      
      return html`<canvas ref=${canvasRef} class="w-full h-full" />`;
    }
    

    Global State with Signals

    // state.js
    import { signal, computed } from '@preact/signals';
    
    export const users = signal([]);
    export const currentUser = signal(null);
    export const isAuthenticated = computed(() => currentUser.value !== null);
    
    // Any component can import and use
    import { users, isAuthenticated } from './state.js';
    

    Constraints

    DO NOT:

    • Recommend npm tooling without confirming user's development environment
    • Suggest dependencies when native solutions exist
    • Optimize prematurely - start with simplest working implementation

    DO:

    • Use HTM syntax by default
    • Create artifacts for all code
    • Prioritize accessibility and progressive enhancement
    • Document architectural decisions in comments

    Resources

    References (Load as Needed)

    • references/ui-sdk.md: ui-sdk for Preact: setup, writing parts in HTM, state and controllers, styling, and a catalog of all 55 components with their modules and parts

    • references/preact-v10-guide.md: Complete Preact v10 API reference (the vendored version is now 11.2.0) covering import maps, HTM syntax, React differences, Signals API, Web Components, SSR, performance patterns, Context, error boundaries, and common gotchas

    • references/architecture-patterns.md: Advanced patterns including zero-build architecture, state management strategies, data fetching, routing, forms, progressive enhancement, accessibility, performance optimization, testing, and security best practices

    Assets (Copy into Projects)

    • assets/ui-sdk/: ui-sdk 0.1.0-beta.10 built for Preact 11 as split ES modules (ui-sdk/<name>.js, ui-sdk/core/<name>.js); copied by vendor.sh --ui-sdk

    • assets/boilerplate.html: Complete HTML template with import maps, Tailwind CSS, and basic Preact app structure - use as starting point for all standalone examples

    • assets/component-patterns.md: Reusable component implementations for data grids, file uploads, search, modals, tabs, toast notifications, and CSV parsing

    Examples

    Minimal Counter (Standalone)

    <!DOCTYPE html>
    <html>
    <head>
      <!-- Run: bash scripts/vendor.sh -->
      <script type="importmap">
        {
          "imports": {
            "preact": "./vendor/preact.module.js",
            "preact/hooks": "./vendor/hooks.module.js",
            "@preact/signals-core": "./vendor/signals-core.mjs",
            "@preact/signals": "./vendor/signals.mjs",
            "htm": "./vendor/htm.module.js",
            "htm/preact": "./vendor/htm.module.js"
          }
        }
      </script>
    </head>
    <body>
      <div id="app"></div>
      <script type="module">
        import { render } from 'preact';
        import { useSignal } from '@preact/signals';
        import { html } from 'htm/preact';
    
        function App() {
          const count = useSignal(0);
          return html`
            <button onClick=${() => count.value++}>
              Count: ${count}
            </button>
          `;
        }
    
        render(html`<${App} />`, document.getElementById('app'));
      </script>
    </body>
    </html>
    

    Data Visualization App

    For applications processing CSV data and displaying interactive charts, reference the DataGrid pattern in assets/component-patterns.md and combine with a charting library like Chart.js or use native Canvas/SVG for custom visualizations.

    WebGL Shader Visualization

    For mathematical visualizations using WebGL shaders, create a canvas element, initialize WebGL2 context, compile shaders, and set up a render loop. Reference MDN WebGL documentation for shader setup patterns.

    Best Practices Summary

    1. Start Simple: Create working prototype before optimizing
    2. Use Signals: Prefer signals over useState for reactive state
    3. Native First: Check if Web APIs can accomplish the task
    4. Progressive Enhancement: Build with accessibility from the start
    5. Document Decisions: Explain non-obvious patterns in comments
    6. Keys in Lists: Always provide stable keys for mapped elements
    7. Error Boundaries: Wrap async operations in error boundaries
    8. Avoid Inline Functions: Don't create handlers inside map() loops

    Validation Checklist

    Before delivering code, verify:

    • Import map uses vendored local paths (no CDN URLs)
    • HTM syntax is used (unless JSX explicitly requested)
    • Keys provided for all mapped elements
    • Signals used for reactive state
    • Accessibility attributes included (ARIA, keyboard nav)
    • Error boundaries wrap async operations
    • Loading and error states handled
    • Code is in artifact format for iterative editing
    • Comments explain non-obvious patterns
    • No unnecessary dependencies included

    Container Testing

    Test Preact apps locally in Claude.ai containers using Playwright. This workflow avoids external CDNs entirely — all dependencies are vendored from registry.npmjs.org.

    Setup (one-time per session)

    # 1. Vendor JS dependencies
    bash scripts/vendor.sh
    
    # 2. Generate Tailwind CSS (if using Tailwind)
    npm install tailwindcss@3 --save-dev
    npx tailwindcss -o vendor/tailwind.css --content "*.html" --minify
    

    Serve and Test

    # 3. Serve locally
    python3 -m http.server 8765 &
    
    # 4. Test with Playwright
    python3 << 'PYEOF'
    from playwright.sync_api import sync_playwright
    
    with sync_playwright() as p:
        browser = p.chromium.launch(headless=True, args=["--no-sandbox"])
        page = browser.new_page()
    
        errors = []
        page.on("console", lambda m: errors.append(m.text) if m.type == "error" else None)
        page.on("pageerror", lambda e: errors.append(str(e)))
    
        page.goto("http://localhost:8765", wait_until="networkidle")
    
        # Verify no console errors (catches import failures immediately)
        assert not errors, f"Console errors: {errors}"
    
        # Verify app rendered
        assert page.locator("#app").inner_html() != "", "App did not render"
    
        # Example: test interaction
        # page.click("button")
        # assert "Count: 1" in page.content()
    
        browser.close()
        print("All tests passed")
    PYEOF
    

    Key guidance

    • Use Playwright directly for local testing — not webctl (webctl is for external sites through the proxy)
    • python3 -m http.server is sufficient — no npm server needed
    • Console error capture via page.on("console") and page.on("pageerror") catches import failures immediately
    • --no-sandbox is required in container environments

    Getting Started

    For immediate implementation:

    1. Run bash scripts/vendor.sh to fetch vendored dependencies
    2. (Optional) Generate Tailwind CSS: npm install tailwindcss@3 --save-dev && npx tailwindcss -o vendor/tailwind.css --content "*.html" --minify
    3. Copy assets/boilerplate.html as the starting point
    4. Read references/preact-v10-guide.md for API details
    5. Reference assets/component-patterns.md for common UI patterns
    6. Consult references/architecture-patterns.md for advanced scenarios

    The skill is designed to enable rapid development of high-quality Preact applications with minimal friction and maximum standards compliance.

    Generating Patches

    Generate portable git patch files from codebase modifications, enabling users to apply Claude's edits to their local repositories.

    When to Use

    Activate after modifying files in an uploaded codebase when the user needs to transfer changes back to their local environment. Typical workflow: user uploads zip → Claude edits files → this skill exports changes as a patch.

    Prerequisites

    Verify git is available and the working directory is a git repository (or can be initialized as one):

    git status 2>/dev/null || git init
    

    If working with an uploaded codebase that lacks git history, initialize and create a baseline commit before making edits:

    git init
    git add -A
    git commit -m "Baseline: original uploaded state"
    

    Generating the Patch

    After completing edits, generate a unified diff:

    # For uncommitted changes (working tree modifications)
    git diff > /mnt/user-data/outputs/changes.patch
    
    # If changes are staged but not committed
    git diff --cached > /mnt/user-data/outputs/changes.patch
    
    # For both staged and unstaged
    git diff HEAD > /mnt/user-data/outputs/changes.patch
    

    For committed changes (preserves commit messages and metadata):

    # All commits since baseline
    git format-patch --stdout baseline..HEAD > /mnt/user-data/outputs/changes.patch
    
    # Or specify number of commits
    git format-patch --stdout -n 3 > /mnt/user-data/outputs/changes.patch
    

    Handling Edge Cases

    Binary files: Git diff excludes binaries by default. Warn the user if binary files were modified:

    git diff --name-only --diff-filter=M | xargs file | grep -v "ASCII\|UTF-8\|empty"
    

    Large patches: For extensive changes, consider splitting by directory or file type:

    git diff -- "*.py" > /mnt/user-data/outputs/python-changes.patch
    git diff -- src/ > /mnt/user-data/outputs/src-changes.patch
    

    No changes detected: Verify files were actually modified. Common issues:

    • Edits made to copies outside the git tree
    • Files not tracked by git (need git add first)

    Output Requirements

    Always output to /mnt/user-data/outputs/ with a descriptive filename. Provide the download link:

    [Download changes.patch](computer:///mnt/user-data/outputs/changes.patch)
    

    User Instructions

    Include these instructions with every patch delivery:


    To apply this patch locally:

    cd /path/to/your/repo
    
    # Preview changes (dry run)
    git apply --check changes.patch
    
    # Apply to working tree
    git apply changes.patch
    

    If using format-patch output (includes commit metadata):

    git am changes.patch
    

    Troubleshooting:

    • git apply --reject changes.patch — applies what it can, writes .rej files for conflicts
    • git apply -R changes.patch — reverses a previously applied patch
    • git apply --3way changes.patch — enables three-way merge for conflicts

    Optional: PR Description

    When requested, generate a pull request description from the patch:

    # Extract summary of changes
    echo "## Summary"
    git diff --stat
    echo ""
    echo "## Changes"
    git diff --name-only | while read f; do echo "- \`$f\`"; done
    

    Combine with a brief description of what was changed and why, suitable for GitHub PR body.

    querying-markdown

    mq is "jq for Markdown" — it parses a .md file into a node stream and lets you select, filter, and transform by structure (.h2, .code("rust"), .link) instead of by line-matching. Reach for it when the task is structural: "every H2 title", "all bash code blocks", "a table of contents", "strip the frontmatter". For plain substring search, grep is still the right tool; for code (not prose) structure, use tree-sitting.

    Before you use mq: is this actually a structural task?

    mq parses the whole document into a node tree before it answers, and that parse cost is real (see Empirical findings). Most "query a markdown file" tasks don't need it. Decide first, using the target — not the file type:

    Your targetUseWhy
    Lines with a fixed prefix — #/## headings, > quotes, - bullets, a leading line/verse numbergrep / awkLine-matching, not structure. grep is faster and already installed.
    A substring anywheregrepmq adds nothing.
    Code structure inside fences (ASTs, symbols, call sites)tree-sittingmq sees the fence, not the code inside it.
    Language-filtered code blocks (.code("bash")); links as structured (text, url) (-F json '.link')mqgrep can't filter a fenced block by language without a brittle hand-rolled fence state machine.
    Markdown→Markdown transforms that must emit valid Markdown — demote/promote headings, rebuild a TOC with anchors, in-place editmqsed doesn't know structure and will corrupt nesting/fences.

    If your task lands in a grep/awk row, do not install mq — close this skill and use the line tool. Diagnosed 2026-06-04: a full-KJV smoke test queried books/chapters/verses (all line-prefix structure) with mq — ~3.3 s per query where grep is milliseconds, the same answers, and a grep post-filter still needed on top. Wrong-shape corpus; mq's selectors earn their parse cost only on the structural rows.

    The judgment call is whether the case is actually line-prefix or only looks it. A heading is a prefix; a heading you want demoted with its subtree, or a match you must re-emit as valid Markdown, is structure — mq's row even when the match looks like a prefix.

    Setup

    mq is a single static binary, not preinstalled. Install on first use (idempotent — exits early if already present, ~1s, no build step):

    bash /mnt/skills/user/querying-markdown/scripts/install-mq.sh
    

    This drops the pinned mq release into /usr/local/bin. Override the version with MQ_VERSION=vX.Y.Z.

    Usage

    mq 'QUERY' file.md          # query a file
    cat file.md | mq 'QUERY'    # query stdin
    mq repl                     # interactive REPL — use to test syntax fast
    

    A node stream flows left→right through |. Selectors (.h, .code, .link) pick nodes; functions (to_text, slugify, map, len) transform them. self is the current node.

    mq '.h2 | to_text()' README.md            # every H2 as plain text
    mq '.code("python") | to_text()' file.md  # all python code blocks
    mq '.h.level' file.md                     # heading depth per heading
    mq -F json '.h2 | to_text()' file.md      # results as JSON
    mq '.h2 | to_text()' file.md | wc -l      # count matches (reliable idiom)
    

    Empirical findings

    Measured 2026-06-04 against a full public-domain KJV Bible (66 files, 4.28 MB).

    Parse-bound, not query-bound. mq reparses the whole document on every invocation; latency tracks document size, not selector or match count. On the 4.28 MB file every query — whether it returned 66 matches or 32,418 — ran ~3.2–3.3 s (~1.3 MB/s); on a normal-sized doc it is single-digit ms. Never loop mq per query over a large corpus: extract once with -F json and work on the result, or accept a constant per-call parse tax.

    Selectors return nodes, not your domain concepts. .h2 over the KJV returned 1,250 nodes — 1,184 chapter headings plus 66 eof markers the source appended per file, while single-chapter books emitted no chapter heading at all. .text also pulled heading text into the paragraph stream. A raw selector count is a node count; map it to your concept with an explicit predicate (e.g. grep -E '^[0-9]+ ' for verses) and check it against a known total before trusting the number.

    An empty result is ambiguous. Zero output means either the selector matched nothing or mq never ran — a wrapper like time/env failed in dash, or a malformed heredoc swallowed the command. Re-run the bare mq 'QUERY' file.md before concluding a selector or function is broken. (Self-inflicted 2026-06-04: a time: not found shell error read as a to_text() defect; to_text() on code blocks works.)

    Reference

    Selector aliases, the built-in function library, table-of-contents and transform recipes, in-place-edit caveats, and CLI flags live in references/cheatsheet.md. Read it before writing a non-trivial query — the dialect is jq-like, not jq, so the function names differ. When unsure of syntax, mq repl gives instant feedback.

    Sponsors

    Details

    Marketplace
    oaustegard/claude-skills
    Source
    plugins/development-tools
    Category
    Development Tools
    License
    MIT
    Keywords
    capturing-browser-logs, check-tools, coding-mojo, compiling-wgsl, composing-html, creating-bookmarklets, creating-mcp-servers, developing-preact, generating-patches, querying-markdown

    More from oaustegard/claude-skills

    All 14