A Claude Code plugin that statically reads two SKILL.md or subagent files and derives RPG battle stats from their text, then renders a deterministic, seeded turn-by-turn battle as ASCII animation whenever two skills are active in a session.
This repository currently contains two pieces:
- The stat extractor: the module that turns a single SKILL.md or subagent markdown file into HP, attack, defense, and speed numbers based on features of its text (instruction length, imperative verb density, constraint/warning word density, and average sentence length).
- The battle engine: a seeded, turn-by-turn resolution engine that takes two fighters' stats and produces a reproducible battle log and winner.
- The ASCII renderer: turns a battle log into a sequence of text arena frames (HP bars plus the attack that just landed), ready to print or feed into a plugin pane one frame at a time.
- The plugin trigger: a Claude Code plugin (
.claude-plugin/plugin.json,hooks/) that watches a session for skills and subagents loading, and the moment a second distinct one is active, resolves both of their files, runs a battle, and plays the ASCII animation in a pane automatically. - The standalone CLI (
skillbrawl): a single command that runs a full battle between two files from a plain terminal, with no live session required, and plays it back as a paced ASCII animation. - The leaderboard (
skillbrawl-leaderboard): a command that discovers every skill and subagent in a project's own.claudedirectory, runs a full round robin between them, and writes the standings into that project's own README.md as a## Leaderboardsection.
Requires Node.js 18+. No external dependencies.
npm installThe headline command runs a full battle between two files, outside any live session:
npx skillbrawl path/to/SKILL-A.md path/to/SKILL-B.mdThis extracts stats for both files, runs the battle, and plays the result back as a sequence of ASCII frames, pacing them one second apart (clearing the screen between frames when run in an interactive terminal). Options:
--interval <ms>— milliseconds to wait between frames (default1000).--no-clear— don't clear the screen between frames; frames scroll past instead, which is useful when piping output to a file or pager.--json— skip the animation and print the fighters and full turn-by-turn log as JSON instead, for scripting.
As a library:
import { readFileSync } from "node:fs";
import { extractStats } from "./src/statExtractor.js";
const raw = readFileSync("path/to/SKILL.md", "utf8");
const { name, description, stats, features } = extractStats(raw);
console.log(stats); // { hp, attack, defense, speed }From the command line:
node src/cli.js path/to/SKILL.mdThis prints the parsed name/description, the derived stats, and the raw text features they were computed from, as JSON.
To run a battle between two files directly:
node src/battleCli.js path/to/SKILL-A.md path/to/SKILL-B.mdThis extracts stats for both files, runs a full battle, and prints the fighters, the random seed used, and the turn-by-turn log as JSON.
As a library:
import { runBattle } from "./src/battleEngine.js";
const result = runBattle(
{ name: "skill-a", stats: { hp: 120, attack: 40, defense: 20, speed: 60 } },
{ name: "skill-b", stats: { hp: 90, attack: 55, defense: 15, speed: 45 } }
);
console.log(result.winner); // "skill-a" or "skill-b"
console.log(result.log); // full turn-by-turn logTo render a battle as ASCII frames:
node src/renderCli.js path/to/SKILL-A.md path/to/SKILL-B.mdThis extracts stats, runs the battle, and prints one ASCII arena frame per attack (HP bars for both fighters plus the attack that just landed), ending with a frame announcing the winner.
As a library:
import { renderBattle, renderBattleAnimation } from "./src/renderer.js";
const frames = renderBattle(fighterA, fighterB, result); // array of frame strings
const animation = renderBattleAnimation(fighterA, fighterB, result); // joined with blank lines- HP scales with instruction length (word count of the file body).
- Attack scales with imperative-verb density (how often sentences open with a command verb like "run", "check", "never").
- Defense scales with constraint/warning word density (words like "never", "avoid", "must", "unless").
- Speed scales inversely with average sentence length — terser instructions move faster.
All formulas are deterministic: the same input file always produces the same stats.
- Each battle is seeded from a hash of the two fighters' names, so the same pair of files always produces the same seed, turn order, damage rolls, and winner.
- Within a round, the faster fighter attacks first; a speed tie is broken using the seeded random stream rather than always favoring one side.
- Each attack deals damage based on the attacker's attack stat minus half the defender's defense, with seeded +/-15% variance and a seeded 10% chance of a critical hit (1.5x damage). Damage is always at least 1, so a battle is guaranteed to end.
- The battle continues until one fighter's HP reaches zero (or a round cap is hit, in which case it is a draw), and the full turn-by-turn log is returned alongside the winner.
- The
skillbrawlplugin hooks the session'sskill.promptandagent.spawnevents (hooks/register.js) and records each distinct skill/subagent name it sees, in load order. - The moment a second distinct skill or subagent is seen, the plugin picks
the first two it recorded, resolves each one's file by checking the
conventional project (
.claude/skills/<name>/SKILL.md,.claude/agents/<name>.md) and user (~/.claude/...) locations, extracts stats for both, runs a battle, and opens a pane that plays the resulting ASCII animation one frame at a time. It only fires once per session. - If either file can't be found at a known location, the pane shows a status line explaining that instead of starting a battle.
- This part depends on APIs the Claude Code plugin host provides (
claude-code'satom/read/update,$.ui,$.clock) rather than Node's standard library, since the trigger only has meaning running inside a Claude Code session;src/sessionTrigger.jsandsrc/skillFileResolver.js, the decision logic underneath it, are plain, dependency-free, and unit tested.
- Each entry in a battle log becomes one frame: a round header, an HP bar for each fighter scaled to their max HP, and a line describing the attack that just landed (critical hits are called out separately from normal hits).
- The final frame announces the winner (or a draw), so the frame sequence is a complete, replayable transcript of the battle.
- Rendering is a pure function of the battle log and starting stats, so the
same battle always renders the same frames; this is checked against a
committed golden transcript (
test/golden/alpha-vs-beta.txt) for a fixed matchup and seed.
skillbrawlis a single, dependency-free bin entry (src/skillbrawl.js) that wires together the stat extractor, battle engine, and renderer for two files passed directly on the command line, without needing a live Claude Code session or the plugin's skill/subagent resolution.- By default it plays the battle back frame by frame with a real delay
between frames (
--intervalto change the pace,--no-clearto disable the terminal clear-screen between frames);--jsoninstead prints the complete fighters/result object immediately, for scripting or tests. - The frame-by-frame playback (
src/animatePlayer.js) takes its write and delay functions as parameters, so the pacing logic is unit tested without real timers or a real terminal.
To build a leaderboard across a project's own skills:
node src/leaderboardCli.js path/to/project [--readme <path>] [--json] [--dry-run]This looks for path/to/project/.claude/skills/*/SKILL.md and
path/to/project/.claude/agents/*.md, runs one battle between every pair of
them, and tallies wins, losses, draws, and win rate per fighter. By default
it writes a ranked markdown table into that project's README.md (creating
the file if it doesn't exist yet), replacing a previous leaderboard section
in place if one is already there rather than appending a duplicate. Options:
--readme <path>— write to a specific file instead of<project>/README.md.--json— print the standings, matches, and fighter files as JSON instead of touching any file, for scripting.--dry-run— print the markdown section that would be written, without writing it.
As a library:
import { buildLeaderboard, formatLeaderboardMarkdown } from "./src/leaderboard.js";
const { standings, matches } = buildLeaderboard([fighterA, fighterB, fighterC]);
console.log(formatLeaderboardMarkdown(standings));src/skillDirectoryScanner.jslists everySKILL.mdunder.claude/skills/*/and every.mdfile under.claude/agents/for a project, with no battle logic of its own.src/leaderboard.jsruns one battle (via the samerunBattlethe rest of skillbrawl uses) between every distinct pair of fighters in a fixed order, so the same group of fighters always produces the same standings, then ranks fighters by wins, then win rate, then name.- The rendered section is wrapped in
<!-- skillbrawl:leaderboard:start -->and<!-- skillbrawl:leaderboard:end -->marker comments; re-running the command replaces everything between those markers and leaves the rest of the README untouched, so the leaderboard can be refreshed repeatedly without hand-editing.
This project is built autonomously, milestone by milestone, and every change
is gated on its automated test suite passing (npm test).