XKCD Says What: Fetch and Embed XKCD Comics

You help users find one relevant XKCD comic and turn it into something immediately usable in a document or terminal. Your role is to resolve the comic request, validate the result, and generate clean Markdown or HTML output without dragging in complex dependencies.

Core Principle

Return one validated comic with a clear selection rationale, and reject fancy extras that need heavyweight tooling.

Quick Reference

Use this skill when the user wants to:

fetch the latest XKCD comic
fetch a random XKCD comic via https://c.xkcd.com/random/comic/
find a likely comic from a short search term or natural-language description
insert the comic into README.md or another Markdown file
print valid HTML anchor or image markup to the terminal

Default behavior:

if no target document is supplied, update README.md
if the user asks for HTML, print HTML to the terminal instead of editing a file unless they explicitly request both
if the user asks for ASCII art, reject it unless it can be done with a small shell or Python helper and no special libraries or terminal clients

Workflow

Classify the request — Determine whether the user wants latest, random, a numeric comic id, a direct XKCD URL, or an archive-based match from a phrase or description. Also determine the requested output mode: Markdown edit, terminal HTML, or both.
Resolve one comic — Use scripts/fetch_xkcd.py to retrieve the comic metadata and output snippets:
- latest should use https://xkcd.com/info.0.json
- random should resolve through https://c.xkcd.com/random/comic/
- search and natural-language lookup should parse https://xkcd.com/archive/ and choose the nearest title match conservatively
- if the match is approximate, say so clearly
Validate the result — Confirm that the comic page URL and image URL resolve with HTTP 200 before editing a document or presenting the HTML snippet. If validation fails, surface the failure explicitly instead of pretending the embed worked.
Generate the requested output — Use the returned snippets to produce one of:
- Markdown image syntax
- linked Markdown image syntax
- HTML anchor markup
- HTML image markup
Edit the target document when needed — If the user wants the comic embedded in Markdown:
- update the explicit target file when provided
- otherwise update README.md
- verify the inserted link or embed text is present in the file after editing
Handle ASCII requests conservatively — Do not promise ASCII rendering by default. Reject it unless a relatively simple shell or Python script with only standard tooling can do the job. In this skill, ASCII output is intentionally rejected because rendering arbitrary PNG images reliably requires image-decoding or terminal-rendering dependencies that are outside the allowed simplicity bar.
Report the outcome — Summarize which comic was selected, why it was selected, what output was produced, what file was changed if any, and what validation succeeded.

Available Tools

`scripts/fetch_xkcd.py`

Resolve a comic request, emit reusable snippets, and optionally validate the page and image URLs.

python3 skills/xkcd-says-what/scripts/fetch_xkcd.py latest --format json --validate
python3 skills/xkcd-says-what/scripts/fetch_xkcd.py random --format markdown-linked
python3 skills/xkcd-says-what/scripts/fetch_xkcd.py "subduction ocean crust" --format html-anchor --validate
python3 skills/xkcd-says-what/scripts/fetch_xkcd.py https://xkcd.com/2057/ --format html-image

Prefer --format json when the agent needs both the metadata and the ready-to-use snippets.

Example Interaction

User: "Add a random XKCD comic to the README and also show me the HTML anchor."

Your approach:

Run python3 skills/xkcd-says-what/scripts/fetch_xkcd.py random --format json --validate
Use the returned linked Markdown image snippet to update README.md
Print the returned HTML anchor snippet in the terminal
Confirm that the README now contains the comic link and that both validated URLs returned HTTP 200

Anti-Patterns

The Transcript Fantasy

Problem: Pretending archive search covers comic transcripts, alt text, or semantic understanding far beyond the archive title list.

Fix: Be explicit that archive-based search is title-driven and approximate. If confidence is low, say so.

The Broken Embed

Problem: Inserting Markdown or HTML before checking whether the comic page and image URL actually resolve.

Fix: Validate first, then edit the file or print the snippet.

The ASCII Rabbit Hole

Problem: Pulling in Pillow, ImageMagick, chafa, or other special clients just to force an ASCII output mode.

Fix: Reject ASCII rendering under this skill's constraints and explain that the feature exceeds the allowed complexity budget.

Reasoning Requirements

Standard Reasoning

Classifying the request as latest, random, direct id, URL, or archive search
Interpreting script output and selecting the correct snippet type
Deciding whether to edit a file or print terminal output

Extended Reasoning

Use extended reasoning for:

ambiguous natural-language descriptions with several plausible archive matches
requests that combine file edits, terminal output, and validation requirements
deciding whether a low-confidence archive match is acceptable or should be surfaced as uncertain

Execution Strategy

Sequential

classify the request before fetching
fetch before validating
validate before editing a target document

Parallelizable

page URL validation and image URL validation can run concurrently
if needed, multiple candidate archive scores can be compared independently before choosing one result

Subagent Candidates

Task	Agent Type	When to Spawn
Repository doc update	general-purpose	When the embed needs to be inserted into multiple docs
Codebase exploration	explore	When the correct target Markdown file is unclear

Context Management

Approximate Token Footprint

Skill base: ~2k tokens
With script usage examples: ~3k tokens
With live fetched comic metadata: ~4k tokens

Context Optimization

Load scripts/fetch_xkcd.py only when the request needs exact arguments or output formats
Prefer the JSON output mode when one fetch needs to drive several outputs
Do not paste fetched HTML into chat unless debugging matching logic

What You Do NOT Do

You do not scrape more of xkcd.com than needed for one comic selection
You do not claim ASCII support under the current simplicity constraint
You do not rehost comic images; use XKCD's existing page and image URLs
You do not silently downgrade validation failures into success

Integration Graph

Inbound (From Other Skills)

Source Skill	Source State	Leads to State
writing-skills	Workflow Step 6: Add reference assets	XSW1: Need a runnable helper for repeatable comic lookup

Outbound (To Other Skills)

This State	Leads to Skill	Target State
XSW4: Need a polished Markdown destination after embedding	shields-badges	README polish after comic insertion

Complementary Skills

Skill	Relationship
writing-skills	Similar authoring conventions for maintaining the skill itself
do-nothing-scripting	Useful fallback when the user wants a manual script outline instead of immediate automation
shields-badges	Helps refine README presentation after the comic embed is added

Notes

XKCD exposes reliable per-comic JSON at https://xkcd.com/<num>/info.0.json and the latest comic at https://xkcd.com/info.0.json.
The archive page is good enough for lightweight title matching, but it is not a transcript search index.
XKCD comics are licensed for sharing under Randall Munroe's published license terms; preserve attribution context by linking back to the comic page and avoid implying commercial reuse rights.