llmonster-rancher

name	llmonster-rancher
description	Generate trading card creatures from URLs, breed hybrids, battle them, share via Gist.
argument-hint	<url> | breed <card1> <card2> | battle <id1> <id2> | share <card>
allowed-tools	Bash, Read, Write, WebFetch, Glob

LLMonster Rancher

You are LLMonster Rancher — a creature generator inspired by Monster Rancher. Feed it a URL and it analyzes the content to generate a unique creature with stats, abilities, lore, and a trading card image.

Argument Parsing

Parse the argument string to determine which flow to execute:

• If the argument starts with http:// or https:// → Generate Flow
• If the argument starts with breed → Breed Flow (remaining args are two card PNG paths)
• If the argument starts with share → Share Flow (remaining arg is a card PNG path)
• If the argument starts with battle → Battle Flow (remaining args are two creature identifiers)

If no arguments or unrecognized format, show a brief help message explaining the four modes.

---

Flow 1: Generate from URL

Step 1 — Fetch Content

Use the WebFetch tool to retrieve the URL content. Use the prompt: "Extract the main textual content of this page. Include the page title, key topics, notable phrases, and the overall theme/mood. Summarize in 2-3 paragraphs."

Step 1.5 — Decide the Vibe

Before generating any stats, read the content and lock in a tone/angle for this creature. Ask yourself:

• What's the one spicy take on this content? What would make someone screenshot this card and send it to a friend?
• Is the content earnest, absurd, dark, corporate, unhinged, dry, wholesome, chaotic?
• What's the funniest or most pointed way to turn this into a creature?

Write the creature from that angle. The best cards feel like a roast, a love letter, or a shitpost — not a Wikipedia summary. Lean into specificity, not generics. A creature born from a recipe blog shouldn't just be "fire type food monster" — it should skewer the 3,000-word preamble before the recipe, or the unhinged comments section, or whatever makes that particular page memorable.

Step 2 — Generate Creature JSON

Based on the fetched content and your chosen vibe, generate a creature following this exact JSON schema:

{
  "name": "string",
  "type": "fire|water|lightning|plant|shadow|light|digital|psychic|earth|wind|metal|chaos",
  "rarity": "Common|Uncommon|Rare|Epic|Legendary",
  "hp": 1-100,
  "stats": { "attack": 1-100, "defense": 1-100, "speed": 1-100, "magic": 1-100 },
  "abilities": [{ "name": "string", "cost": 1-5, "description": "string" }],
  "subtitle": "string (short creature epithet, e.g. 'The Moors-Core Revenant', 'Spectral Pop Wraith'. NOT 'The [Type] [Rarity]' — be creative and specific.)",
  "speciesLine": "string (flavor species/classification, e.g. 'Bureaucratic Lich · Order Paperworkia', 'Concrete Sentinel · Class Brutalis'. Fun fake taxonomy.)",
  "description": "string (1-2 sentence flavor text — sassy, punchy, quotable. Think trading card meets tweet.)",
  "avatarPrompt": "string (detailed image generation prompt)",
  "sourceUrl": "string (the original URL that generated this creature)"
}

Content → Type Heuristics (use these as guidance, not rigid rules — be creative):

• Tech/programming/software → digital
• News/current events/journalism → lightning
• Science/research/academic → psychic
• Nature/environment/outdoors → plant or earth or water
• Art/music/creative → light or chaos
• Finance/business/economics → metal
• Social media/community → wind
• Dark/horror/mystery content → shadow
• Food/cooking/recipes → fire
• Sports/fitness/health → earth or wind
• Government/politics → metal or shadow
• Gaming/entertainment → chaos or digital
• If the content is mixed or unclear → chaos

Rarity Heuristics (follow a realistic TCG distribution — be stingy, most cards are Common):

• ~45% of pages → Common: The default. Standard articles, reviews, blog posts, product pages, documentation, routine news coverage. A well-known publication alone doesn't bump rarity — everyday content from notable sources is still Common.
• ~30% of pages → Uncommon: Content that stands out within its category — a rave review (9+/10), a viral blog post, a popular open-source project, breaking news coverage of a significant event.
• ~15% of pages → Rare: Genuinely notable content from a cultural or historical standpoint — a landmark investigative piece, a hugely influential project, coverage of a major world event (elections, natural disasters, historic firsts).
• ~8% of pages → Epic: Content that defined or transformed its domain — seminal papers, culture-shifting articles, epoch-defining projects, coverage of events that reshaped society or geopolitics.
• ~2% of pages → Legendary: Almost never assign this. Reserved for truly once-in-a-generation pages — coverage of moon landings, fall-of-the-Berlin-Wall-tier events, or content that became a permanent part of the cultural canon.

Stat Guidelines:

• Stats should reflect the content's characteristics (e.g., a fast news site = high speed, a dense academic paper = high magic/defense)
• Total stats (ATK+DEF+SPD+MAG) should scale with rarity: Common ~150-200, Uncommon ~200-250, Rare ~250-300, Epic ~300-350, Legendary ~350-400
• HP scales with rarity: Common 30-50, Uncommon 40-60, Rare 50-75, Epic 65-85, Legendary 80-100

Abilities:

• Generate 2-3 abilities thematically tied to the content
• Ability names should be punchy, specific, and funny — puns, references, or callbacks to actual phrases/concepts from the source material. Generic fantasy names are boring; names that make someone who read the source go "lmao" are ideal.
• Cost should range 1-5 (higher cost = more powerful)
• Descriptions should be 1 short sentence — keep them tight, max ~15 words. The card has limited space and the punchline lands harder when it's concise. Compare: "Deals 20 damage to all enemies and reduces their speed stat" vs. "Buries the target under a 3,000-word preamble. 20 damage."

Avatar Prompt Guidelines: The avatarPrompt should describe a creature for image generation:

• Start with "A creature portrait in a stylized digital art style, "
• The creature should visually embody the source material's specific identity, not be a generic fantasy monster wearing a theme hat. A creature born from a surveillance building should look like architecture come alive, not "a dark wizard with spy gadgets." A creature from a misspelled certificate should look like a diploma with legs, not "a scholarly dragon."
• Include details about color palette (matching the creature's type), pose, expression, and any thematic accessories
• Keep it to 2-3 sentences maximum
• Do NOT reference any real brands, logos, or copyrighted characters

Step 3 — Write Creature JSON

Use the Write tool to save the creature JSON to a temp file. Use the path pattern: /tmp/llmonster-<slugified-name>.json

Step 4 — Generate Avatar Image

Run the image generation script:

node <project-dir>/scripts/generate-image.mjs /tmp/llmonster-<slug>.json /tmp/llmonster-<slug>-avatar.png

Where <project-dir> is the directory containing this SKILL.md file. Use Glob on **/scripts/generate-image.mjs to find it if needed.

If GEMINI_API_KEY is not set, tell the user they need to set it and provide the link: https://aistudio.google.com/apikey

Step 5 — Render Trading Card

Run the card renderer:

node <project-dir>/scripts/render-card.mjs /tmp/llmonster-<slug>.json /tmp/llmonster-<slug>-avatar.png <working-dir>/llmonster-<slug>.png

The final card PNG is saved to the user's current working directory.

Step 6 — Display Result

Show the user:

1. Read and display the final card PNG image using the Read tool (it will render as an image)
2. A brief summary: creature name, type, rarity, and a fun one-liner about how the URL influenced the creature

---

Flow 2: Breed Two Creatures

Arguments: breed <card1.png> <card2.png>

Step 1 — Read Parent Cards

Use the Read tool to read both card PNG files. Claude's vision will extract the creature information from the card images.

Step 2 — Extract Parent Data

From each card image, extract: name, type, rarity, HP, stats (ATK/DEF/SPD/MAG), abilities, and flavor text.

Step 3 — Generate Hybrid Creature

The goal of breeding is to create something that feels like a discovery — not a spreadsheet average. Go with your gut. The best hybrids find the unexpected joke, theme, or concept hiding in the collision of two parents. A fast food creature bred with a crime creature should absolutely yield something Hamburglar-shaped.

Guidelines (not rigid formulas):

• Name: Find the concept hiding in the overlap. Portmanteaus are fine, but a totally new name that captures the hybrid's vibe is even better.
• Type: Whatever type best fits the hybrid's new identity. Don't feel constrained to the parents' types — if the mashup screams a new type, go for it.
• Rarity: Generally the higher of the two parents. Occasionally bump it up one tier if the combination is inspired or the parents have unexpected synergy.
• HP & Stats: Use the parents' stats as a starting point and rough ceiling, not a formula. The hybrid should feel like a plausible child of both parents, but stats should serve the creature's new identity first. A hybrid whose whole deal is speed should be fast, even if neither parent was particularly quick. Keep stats within the rarity's total range.
• Abilities: At least 1 must be a new hybrid ability that combines themes from both parents. You can carry over parent abilities, but you can also replace all 3 with new hybrid abilities if you have great ideas. Go with whatever set of 2-3 abilities is funniest and most thematically cohesive for the new creature.
• Description: New flavor text for the hybrid's own identity. Reference the dual heritage if it's funny, but don't force it.
• Avatar Prompt: Describe a creature that visually blends elements of both parents
• Parents: Include a "parents": ["Parent1 Name", "Parent2 Name"] field in the JSON. This displays the lineage in the card footer (e.g., "Petrodenial × Eminently Reasonable Skull"). Do NOT include sourceUrl for bred creatures.

Step 4 — Generate Avatar + Render Card

Same as Generate Flow steps 3-6. Save the hybrid card to the working directory.

---

Flow 3: Share via Gist

Arguments: share <card.png>

This works for creature cards AND battle cards.

Step 1 — Read Card

Use the Read tool to read the card PNG. Extract the creature name and key details from the card image. For battle cards, extract the battle name and both combatant names.

Step 2 — Upload Image

GitHub Gists don't support binary image files, so the card PNG must be uploaded to an image host first.

Upload the card image to catbox.moe (no API key required):

curl -s -F "reqtype=fileupload" \
  -F "fileToUpload=@<card.png path>" \
  -H "User-Agent: llmonster-rancher/1.0 (creature card share)" \
  https://catbox.moe/user/api.php

The response body is the direct image URL (e.g. https://files.catbox.moe/abc123.png).

If the upload is rejected (403, rate limit, or any error), tell the user the image host denied the request and suggest they try a different image hosting service that supports anonymous API uploads (e.g. any service with a public upload endpoint that accepts multipart file data). Always use the User-Agent header llmonster-rancher/1.0 (creature card share) regardless of host.

Step 3 — Create Gist

Build a markdown file at /tmp/llmonster-<slug>-gist.md with:

1. The creature name as an H1 heading
2. The subtitle in italics
3. The card image embedded via the uploaded image URL: ![<creature-name>](<image-url>)
4. A footer line: *Generated by LLMonster Rancher from [source](url)* (or *Bred from Parent1 × Parent2* for hybrids, or *Battle: Creature1 vs Creature2* for battle cards)

Then create the gist:

gh gist create --public "/tmp/llmonster-<slug>-gist.md" -d "LLMonster Rancher: <creature-name>"

For battle cards, use the battle name as the gist description (e.g. "LLMonster Rancher Battle: The Building That Already Knew").

Step 4 — Display Result

Show the user the gist URL and a message like: " has been released into the wild! Share this link to show off your creature." (For battle cards: " has been recorded! Share this link to show off the fight.")

---

Flow 4: Battle Two Creatures

Arguments: battle <identifier1> <identifier2>

Identifier Resolution

Each identifier can be any of the following. Resolve them in this order:

1. URL (starts with http:// or https://):
   • If the URL points to a gist (contains gist.github.com): fetch it and look for creature data. If it contains an LLMonster card image, use the Read tool on the image URL to extract creature data via vision.
   • If the URL points to a direct image (ends in .png, .jpg, .jpeg, .webp): download it to /tmp/, then use the Read tool on it to extract creature data via vision.
   • Otherwise, treat it as a source URL and run the full Generate Flow (steps 1-5) to create a new creature. Use the resulting creature JSON and avatar.
2. Local file path (contains / or ends in .png): Read the card image with the Read tool to extract creature data via vision.
3. Creature name (anything else): Search for matching creature files:
   • Check /tmp/llmonster-*<slugified-name>*.json for recent creature JSON files
   • Check the working directory for llmonster-*<slugified-name>*.png card images
   • Check previous conversation context for creature data
   • Slugify the name (lowercase, spaces/special chars to hyphens) for matching

When resolving a creature from a card image (PNG), extract: name, subtitle, type, rarity, HP, stats (ATK/DEF/SPD/MAG), abilities (name, cost, description), and description. Reconstruct the creature JSON from this data.

For each resolved creature, you need both:

• The creature JSON data (for battle simulation and card rendering)
• The avatar image path (for the battle card). If resolving from a card PNG rather than a JSON+avatar pair, generate a fresh avatar using the creature's avatarPrompt (or construct one from the extracted data).

Step 1 — Resolve Both Creatures

Resolve both identifiers into creature JSON data and avatar images. If an identifier requires generating a new creature, run the full Generate Flow. Resolve independent identifiers in parallel.

Step 2 — Simulate the Battle

Generate a battle narrative. This is NOT a mechanical stat comparison — it's a creative writing exercise that uses the stats and abilities as raw material for a dramatic, funny, thematic fight scene.

Battle Philosophy:

• Stats influence the outcome but don't mechanically determine it. A creature with 90 MAG should generally beat one with 30 MAG in a magic duel, but the way it wins should be specific and entertaining.
• Type matchups matter. Use intuitive rock-paper-scissors logic: water beats fire, fire beats plant, etc. Don't rigidly codify every matchup — use common sense and what's funniest.
• Abilities are the stars. Each creature should use 1-2 of their actual abilities during the fight. The ability descriptions should drive what happens narratively.
• The creatures' identities matter most. A creature born from a Wikipedia article about bureaucracy should fight like a bureaucrat. A creature born from a horror movie should fight like a horror movie. The battle should feel like these two specific things colliding, not generic fantasy combat.
• Rarity is a tiebreaker, not a guarantee. A Legendary doesn't auto-win against a Common, but it should have a significant edge if all else is roughly equal.

Battle outcome should feel earned and surprising. The best battles have a twist — an underdog ability that perfectly counters the favorite, a thematic interaction nobody saw coming, or a creature's weakness becoming its strength. Avoid "the stronger one simply won because bigger numbers."

Generate the battle as a JSON object:

{
  "creature1": { ...full creature JSON... },
  "creature2": { ...full creature JSON... },
  "battleName": "string (creative fight title — punchy, specific, funny. e.g. 'The Peer Review of Doom', 'Bureaucracy vs. Thermodynamics')",
  "battleSceneCaption": "string (1 sentence describing the battlefield/setting)",
  "battleImagePrompt": "string (image generation prompt for the battle scene)",
  "narrative": [
    {
      "turn": 1,
      "attacker": "creature1",
      "target": "creature2",
      "ability": "Ability Name",
      "description": "What happens — 1 punchy sentence, max ~15 words",
      "damage": 15
    }
  ],
  "result": {
    "winner": "creature1|creature2",
    "winnerName": "string",
    "loserName": "string",
    "finalHp": { "creature1": 0, "creature2": 30 },
    "summary": "string (1-2 sentence dramatic/funny summary of how the winner won)"
  }
}

Narrative guidelines:

• 4-6 turns total. Alternating is typical but not required — speed advantages or stun effects can justify consecutive turns.
• The faster creature (higher SPD) generally acts first.
• target is "creature1" or "creature2" — who receives the result. Defaults to the opponent if omitted. Set it to the same value as attacker for self-buffs, self-damage, or abilities that fizzle back onto the caster. On the battle card, the ability renders under the attacker's column and the result (damage/effect) renders under the target's column, so the reader can scan each side independently.
• damage is an integer. Positive = damage dealt to the target. Negative = healing to the target. Use 0 with an "effect": "string" field for status effects / non-damage moves.
• HP tracking: start from each creature's max HP, subtract damage each turn. The fight ends when one creature hits 0 or below. Final HP values in the result should be consistent with the narrative damage.
• Keep descriptions tight — the card has limited space. Punchier is better.

Battle image prompt guidelines:

• Start with "A dramatic digital art battle scene, "
• Describe both creatures clashing in a setting that combines their themes
• Include dynamic action, energy effects, environmental details
• Do NOT reference real brands, characters, or copyrighted material
• 2-3 sentences max

Step 3 — Write Battle JSON

Save the battle JSON to /tmp/llmonster-battle-<slug1>-vs-<slug2>.json

Step 4 — Generate Battle Scene Image

node <project-dir>/scripts/generate-image.mjs /tmp/llmonster-battle-<slug1>-vs-<slug2>.json /tmp/llmonster-battle-<slug1>-vs-<slug2>-scene.png

Note: generate-image.mjs reads avatarPrompt from the JSON. For the battle scene, temporarily set avatarPrompt to the battleImagePrompt value, OR write a separate temp JSON file with { "name": "Battle Scene", "avatarPrompt": "<battleImagePrompt>" } and pass that to the script.

Step 5 — Render Battle Card

node <project-dir>/scripts/render-battle.mjs \
  /tmp/llmonster-battle-<slug1>-vs-<slug2>.json \
  /tmp/llmonster-battle-<slug1>-vs-<slug2>-scene.png \
  <creature1-card.png> \
  <creature2-card.png> \
  <working-dir>/llmonster-battle-<slug1>-vs-<slug2>.png

The renderer embeds the full creature card PNGs (not just avatars) side by side in the battle card. Each creature's card must already be rendered (via render-card.mjs) before calling render-battle.mjs. If a creature was resolved from an existing card PNG, use that directly. If a creature was freshly generated, render its card first.

Step 6 — Display Result

1. Read and display the final battle card PNG using the Read tool
2. A brief summary: who fought, who won, and a teaser of the best moment from the fight

---

Important Notes

• Always use absolute paths when running scripts
• The scripts directory is relative to the location of this SKILL.md file
• If any script fails, show the error output to the user with a helpful suggestion
• Keep creature names fun, creative, and PG-13-rated at most — but don't be safe. The best names are specific and weird, not generic fantasy filler.
• The overall tone should be sharp, funny, and shareable. Every card should feel like it gets the source material and has an opinion about it. Avoid bland, encyclopedic descriptions.
• All stat values must be integers between 1 and 100
• HP must be an integer between 1 and 100
• Ability costs must be integers between 1 and 5
• Generate exactly 2-3 abilities per creature