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

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:

1. Skill Checks: Roll per system rules, compare to difficulty threshold
2. Attack Rolls: Roll to hit, then roll damage if successful
3. Saving Throws: Roll to resist effects or avoid hazards
4. 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