Skip to content

About

A Claude Code plugin that statically reads two SKILL.md or subagent files and derives RPG battle stats from their text…

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

6 Commits

Folders and files

Repository files navigation

skillbrawl

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 .claude directory, runs a full round robin between them, and writes the standings into that project's own README.md as a ## Leaderboard section.

Install

Requires Node.js 18+. No external dependencies.

npm install

Usage

The headline command runs a full battle between two files, outside any live session:

npx skillbrawl path/to/SKILL-A.md path/to/SKILL-B.md

This 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 (default 1000).
  • --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.md

This 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.md

This 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 log

To render a battle as ASCII frames:

node src/renderCli.js path/to/SKILL-A.md path/to/SKILL-B.md

This 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

How stats are derived

  • 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.

How battles are resolved

  • 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.

How the plugin trigger works

  • The skillbrawl plugin hooks the session's skill.prompt and agent.spawn events (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's atom/read/update, $.ui, $.clock) rather than Node's standard library, since the trigger only has meaning running inside a Claude Code session; src/sessionTrigger.js and src/skillFileResolver.js, the decision logic underneath it, are plain, dependency-free, and unit tested.

How the ASCII renderer works

  • 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.

How the standalone CLI works

  • skillbrawl is 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 (--interval to change the pace, --no-clear to disable the terminal clear-screen between frames); --json instead 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));

How the leaderboard works

  • src/skillDirectoryScanner.js lists every SKILL.md under .claude/skills/*/ and every .md file under .claude/agents/ for a project, with no battle logic of its own.
  • src/leaderboard.js runs one battle (via the same runBattle the 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.

Status

This project is built autonomously, milestone by milestone, and every change is gated on its automated test suite passing (npm test).

About

A Claude Code plugin that statically reads two SKILL.md or subagent files and derives RPG battle stats from their text…

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages