dice-roller
This skill should be used when the GM needs to roll dice or when the user asks to "roll dice", "make a dice roll", "roll for initiative", "roll a skill check", "roll damage", or needs to resolve RPG mechanics with random dice outcomes. Provides deterministic dice rolling for tabletop RPG adventures.
When & Why to Use This Skill
The Dice Roller skill is a specialized utility designed for tabletop RPG (TTRPG) automation within Claude. It provides a deterministic engine to execute complex dice expressions—such as d20, 2d6+3, and Fudge dice—via bash scripts. By delivering structured JSON output, it enables AI agents to accurately resolve game mechanics like skill checks, combat damage, and initiative, ensuring a seamless and rule-compliant narrative experience.
Use Cases
- Skill Checks and Saving Throws: Automatically calculate character successes or failures against difficulty classes (DC) in systems like D&D or Pathfinder.
- Combat and Damage Calculation: Streamline encounters by rolling for initiative and calculating multi-die damage results with modifiers.
- Narrative Randomization: Use percentile rolls (d100) or Fudge dice to determine the outcome of environmental events, loot generation, or NPC reactions.
- Programmatic RPG Mechanics: Integrate dice rolling into larger automated gaming workflows where JSON data is required for state management.
| name | dice-roller |
|---|---|
| description | This skill should be used when the GM needs to roll dice or when the user asks to "roll dice", "make a dice roll", "roll for initiative", "roll a skill check", "roll damage", or needs to resolve RPG mechanics with random dice outcomes. Provides deterministic dice rolling for tabletop RPG adventures. |
Dice Roller Skill
Provides a bash script for rolling dice in RPG adventures with JSON output for programmatic use.
How to Roll Dice
Execute the dice roller script with a dice expression:
bash "${CLAUDE_PLUGIN_ROOT}/skills/dice-roller/scripts/roll.sh" "2d6+3"
The script is bundled with this skill and executes from the plugin directory.
Supported Expressions
| Expression | Meaning |
|---|---|
1d20 |
Roll one 20-sided die |
2d6 |
Roll two 6-sided dice, sum them |
1d20+5 |
Roll d20, add 5 |
3d8-2 |
Roll 3d8, subtract 2 |
4dF |
Roll 4 Fudge dice (-1, 0, +1 each) |
d100 |
Roll percentile (1-100) |
Output Format
The script outputs JSON with individual rolls and computed total:
{
"expression": "2d6+3",
"rolls": [4, 2],
"modifier": 3,
"total": 9
}
When to Roll
For adventures with RPG rules (indicated by System.md), use dice rolls for:
- Skill Checks: Roll per system rules, compare to difficulty threshold
- Attack Rolls: Roll to hit, then roll damage if successful
- Saving Throws: Roll to resist effects or avoid hazards
- Initiative: Roll to determine turn order in combat
Example Usage
Skill Check (d20 system):
bash "${CLAUDE_PLUGIN_ROOT}/skills/dice-roller/scripts/roll.sh" "1d20+5"
# Output: {"expression": "1d20+5", "rolls": [14], "modifier": 5, "total": 19}
Narrate the outcome based on the result vs the difficulty class.
Damage Roll:
bash "${CLAUDE_PLUGIN_ROOT}/skills/dice-roller/scripts/roll.sh" "2d6+3"
# Output: {"expression": "2d6+3", "rolls": [5, 4], "modifier": 3, "total": 12}
Describe the impact narratively - "Your sword bites deep, dealing 12 damage."
Best Practices
- Always narrate outcomes - players see the story, not raw numbers
- Parse the JSON output to extract the total for mechanical comparisons
- Include context in narration (what was rolled, why it matters)
- For hidden rolls (GM secrets), execute silently and narrate only the outcome