# Claude Plugin

RANDSUM provides a **Claude Code plugin** with three skills that give AI agents specialized knowledge for tabletop RPG dice mechanics.

## Available skills
**Dice Rolling**
Roll dice, interpret results, and answer questions about RANDSUM notation and supported game systems. Covers all 19+ modifiers and 6 game systems.

**Dice Probability**
Analyze probability distributions, expected values, and outcome comparisons. Compare strategies like "advantage vs. flat +2" with exact math or Monte Carlo simulation.

**Game Spec Creator**
Create `.randsum.json` specs for custom TTRPG dice mechanics. Translate tabletop game rules into declarative specs that generate typed TypeScript `roll()` functions via codegen.

## What is a Claude Code skill?

A skill is a markdown document that gives Claude specialized knowledge. When Claude loads a RANDSUM skill, it learns domain-specific concepts — dice notation syntax, probability math, or the `.randsum.json` spec format — and can apply them to your questions without you needing to explain the domain.

Skills activate automatically based on context. Ask naturally:

```
Roll 4d6 drop lowest for my strength score
What are the odds of rolling 15+ on 3d6?
Create a .randsum.json spec for Ironsworn
```

Or invoke explicitly with `/dice-rolling`, `/dice-probability`, or `/game-spec-creator`.

## Setup

All skill files live in the [`skills/`](https://github.com/RANDSUM/randsum/tree/main/skills) directory.

Place skill files in your project's `.claude/skills/` directory:

<CodeExample lang="bash" code={`# Download all three skills
for skill in dice-rolling dice-probability game-spec-creator; do
  mkdir -p .claude/skills/$skill/references
  curl -o .claude/skills/$skill/SKILL.md \\
    https://raw.githubusercontent.com/RANDSUM/randsum/main/skills/$skill/SKILL.md
done

# Download reference files
curl -o .claude/skills/dice-rolling/references/NOTATION.md \\
  https://raw.githubusercontent.com/RANDSUM/randsum/main/skills/dice-rolling/references/NOTATION.md
curl -o .claude/skills/dice-rolling/references/GAME_SYSTEMS.md \\
  https://raw.githubusercontent.com/RANDSUM/randsum/main/skills/dice-rolling/references/GAME_SYSTEMS.md
curl -o .claude/skills/dice-probability/references/PROBABILITY_TABLES.md \\
  https://raw.githubusercontent.com/RANDSUM/randsum/main/skills/dice-probability/references/PROBABILITY_TABLES.md
curl -o .claude/skills/game-spec-creator/references/SPEC_EXAMPLES.md \\
  https://raw.githubusercontent.com/RANDSUM/randsum/main/skills/game-spec-creator/references/SPEC_EXAMPLES.md`} />

Load skill content as part of your agent's system prompt:

<CodeExample code={`// Load whichever skills your agent needs
const diceSkill = readFileSync('skills/dice-rolling/SKILL.md', 'utf-8')
const probSkill = readFileSync('skills/dice-probability/SKILL.md', 'utf-8')
const specSkill = readFileSync('skills/game-spec-creator/SKILL.md', 'utf-8')

// Include in your agent's system prompt
const systemPrompt = \`You are a TTRPG assistant.\\n\\n\${diceSkill}\``} />

Paste skill content directly into any LLM conversation. Each skill is self-contained with all references included.

## Skill details

### Dice Rolling

The core skill. Teaches an agent RANDSUM dice notation — a compact syntax for any roll — and how to interpret results for six supported game systems: D&D 5e, Blades in the Dark, Daggerheart, PbtA, Root RPG, and Salvage Union.

**What the agent learns:**
- All RANDSUM notation syntax (`4d6L`, `2d20H+5`, `3d6!`, `d%`, `4dF`, etc.)
- Game-specific result interpretation (critical hits, partial success, desperation rolls)
- When to validate input and how to explain results clearly

**Files:**
- [`skills/dice-rolling/SKILL.md`](https://github.com/RANDSUM/randsum/blob/main/skills/dice-rolling/SKILL.md) — main skill definition
- [`skills/dice-rolling/references/NOTATION.md`](https://github.com/RANDSUM/randsum/blob/main/skills/dice-rolling/references/NOTATION.md) — full notation reference
- [`skills/dice-rolling/references/GAME_SYSTEMS.md`](https://github.com/RANDSUM/randsum/blob/main/skills/dice-rolling/references/GAME_SYSTEMS.md) — game system mechanics

### Dice Probability

Teaches an agent to analyze probability distributions for dice rolls. Handles exact enumeration for small outcome spaces and Monte Carlo simulation for complex rolls.

**What the agent learns:**
- Expected values, variance, and standard deviation for any notation
- Probability of hitting specific thresholds (e.g., "odds of 15+ on 3d6")
- Comparative analysis ("advantage vs. flat +2 bonus")
- Game-system outcome probabilities (e.g., "chance of critical success in Blades")

**Files:**
- [`skills/dice-probability/SKILL.md`](https://github.com/RANDSUM/randsum/blob/main/skills/dice-probability/SKILL.md) — main skill definition
- [`skills/dice-probability/references/PROBABILITY_TABLES.md`](https://github.com/RANDSUM/randsum/blob/main/skills/dice-probability/references/PROBABILITY_TABLES.md) — precomputed reference tables

### Game Spec Creator

Teaches an agent the `.randsum.json` spec format — a declarative JSON Schema for describing tabletop RPG dice mechanics. Specs define a four-stage pipeline (Dice → Modify → Resolve → Outcome) and generate typed TypeScript `roll()` functions via codegen.

**What the agent learns:**
- The full `.randsum.json` schema (pools, modifiers, conditions, outcome tables)
- How to translate natural-language game rules into declarative specs
- Reference resolution (`$ref` for reusable components)
- Validation rules and common patterns across game systems

**Files:**
- [`skills/game-spec-creator/SKILL.md`](https://github.com/RANDSUM/randsum/blob/main/skills/game-spec-creator/SKILL.md) — main skill definition
- [`skills/game-spec-creator/references/SPEC_EXAMPLES.md`](https://github.com/RANDSUM/randsum/blob/main/skills/game-spec-creator/references/SPEC_EXAMPLES.md) — example specs for existing game systems

## Programmatic usage

If you're building a custom agent, you can also use `@randsum/roller` directly:

<CodeExample lang="bash" code={`bun add @randsum/roller`} />

<CodeExample code={`const result = roll('4d6L')
console.log(result.total)  // Sum after dropping lowest
console.log(result.rolls)  // Individual die results`} />

See the [Roller documentation](https://randsum.dev/roller/introduction/) for the full API.

## Dice rolling skill definition

The full skill file that agents receive:

<SkillContent />

## Notation reference

<NotationContent />

## Game systems reference

<GameSystemsContent />

## Links

- [All skills on GitHub](https://github.com/RANDSUM/randsum/tree/main/skills)
- [Dice Rolling skill](https://github.com/RANDSUM/randsum/tree/main/skills/dice-rolling)
- [Dice Probability skill](https://github.com/RANDSUM/randsum/tree/main/skills/dice-probability)
- [Game Spec Creator skill](https://github.com/RANDSUM/randsum/tree/main/skills/game-spec-creator)
- [Claude Code skills documentation](https://docs.anthropic.com/en/docs/claude-code/skills)