agentsclimarketplace

Game spec creator

Skill RANDSUM/randsum/skills/game-spec-creator

Help users create .randsum.json specs for custom TTRPG dice mechanics. Use when someone wants to define a new game system, translate tabletop game rules into declarative specs, or understand the RANDSUM spec format.From its SKILL.md

Install
npx -y skills add RANDSUM/randsum --skill game-spec-creator

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 13 stars13 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its file declares

Copied from the file, not written here

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

6.5 KB, as published. Nobody here has run it

Game Spec Creator

Create .randsum.json specs that declaratively define tabletop RPG dice mechanics. A spec describes a four-stage pipeline -- Dice -> Modify -> Resolve -> Outcome -- and generates a typed TypeScript roll() function via codegen.

Spec Structure

Every spec requires these top-level fields:

{
  "$schema": "https://randsum.dev/schemas/v1/randsum.json",
  "name": "My Game",
  "shortcode": "mygame",
  "game_url": "https://example.com",
  "version": "1.0.0",
  "roll": { ... }
}

Optional top-level sections for reuse across rolls:

  • pools -- Named dice pool definitions. Reference with { "$ref": "#/pools/<name>" }.
  • tables -- Lookup tables mapping roll values to result strings.
  • outcomes -- Named outcome operations for result classification.

The roll Object

The roll object defines the pipeline:

FieldStageRequiredPurpose
inputs--NoDeclare runtime parameters (stat, modifier, rating)
dice1Yes*Pool reference + quantity. *Or use dicePools for multi-pool rolls
modify2NoModifier chain (keepHighest, keepLowest, add, cap)
resolve3YesResolution: "sum", countMatching, tableLookup, or comparePool
outcome4NoMap resolved value to a game result string
when--NoConditional overrides based on input values
details--NoExtra typed fields returned alongside the result
postResolveModifiers--NoArithmetic applied after resolve (e.g. 2d6+stat)

Inputs

Inputs are typed parameters the caller passes at roll time. Bind them in the pipeline with { "$input": "paramName" }.

"inputs": {
  "modifier": { "type": "integer", "minimum": -5, "maximum": 5, "default": 0 },
  "mode": { "type": "string", "enum": ["Normal", "Advantage"], "optional": true }
}

Types: integer, string, boolean. Inputs can have default, minimum/maximum, enum, optional, and description.

Dice

Single pool (inline or referenced):

"dice": { "pool": { "sides": 20 }, "quantity": 1 }
"dice": { "pool": { "$ref": "#/pools/actionDice" }, "quantity": { "$input": "rating" } }

Multi-pool (use dicePools instead of dice):

"dicePools": {
  "hope": { "pool": { "sides": 12 } },
  "fear": { "pool": { "sides": 12 } }
}

Modify

Array of modifier operations applied to individual dice before resolving:

"modify": [
  { "keepHighest": 1 },
  { "add": { "$input": "modifier" } },
  { "cap": { "min": 1, "max": 20 } }
]

Available: keepHighest, keepLowest, add, cap, markDice/keepMarked.

Resolve

  • "sum" -- Total all remaining dice
  • { "countMatching": { "operator": ">=", "value": 7 } } -- Count successes
  • { "tableLookup": { "$ref": "#/tables/myTable" } } -- Map total through a table
  • { "comparePoolHighest": { "pools": ["a","b"], "outcomes": {...} } } -- Compare pools

Outcome

Map the resolved value to game result strings:

"outcome": {
  "ranges": [
    { "min": 10, "max": 27, "result": "strong_hit" },
    { "min": 7, "max": 9, "result": "weak_hit" },
    { "min": -11, "max": 6, "result": "miss" }
  ]
}

Also supports tableLookup (with $ref or inline) and degreeOfSuccess for PF2e-style tiers.

Conditional Overrides (when)

Override pipeline stages based on input values. First match wins; unspecified stages fall through:

"when": [{
  "condition": { "input": "mode", "operator": "=", "value": "Advantage" },
  "override": {
    "dice": { "pool": { "sides": 20 }, "quantity": 2 },
    "modify": [{ "keepHighest": 1 }, { "add": { "$input": "modifier" } }]
  }
}]

Pool Conditions

Check dice composition rather than totals -- used in tables for mechanics like Blades criticals:

{
  "poolCondition": { "countWhere": { "operator": "=", "value": 6 }, "atLeast": 2 },
  "result": "critical"
}

Use atLeastRatio (0-1) instead of atLeast for proportion-based checks.

Guided Workflow

When helping a user create a spec, follow these steps:

1. Identify the core mechanic

Ask: What dice do you roll? What determines success or failure? Classify it:

  • Sum-based: Roll dice, add modifiers, compare to target (D&D, PbtA)
  • Pool-based: Roll many dice, count successes (World of Darkness, Shadowrun)
  • Keep-best/worst: Roll multiple, keep highest or lowest (Blades, advantage/disadvantage)
  • Comparison: Compare two pools (Daggerheart hope/fear)
  • Table lookup: Roll and consult a table (Salvage Union, random encounters)

2. Map inputs

What does the player choose or provide? Common patterns:

  • Numeric modifier (stat bonus, skill rank)
  • Pool size (action rating, dice pool count)
  • Mode selection (advantage/disadvantage, boost/cut)
  • Table name (which random table to roll on)

3. Build the pipeline

Define pools, modifiers, resolution strategy, and outcome ranges. Use when for variant mechanics. Validate against packages/games/randsum.json.

Common Patterns

Tiered outcomes (PbtA-style): Range-based outcome with strong hit / weak hit / miss.

Keep highest with fallback (Blades-style): keepHighest: 1 default, when rating=0 overrides to keepLowest: 1 with 2 dice.

Advantage/Disadvantage (D&D-style): when conditions that change pool quantity and keep strategy.

Pool conditions (criticals): poolCondition in table ranges to detect multiple max-value dice.

Multi-pool comparison (Daggerheart-style): dicePools + comparePoolHighest resolve.

Post-resolve arithmetic: postResolveModifiers for bonuses applied after resolution (not per-die).

Boolean-conditional values: { "$input": "flag", "ifTrue": 20, "ifFalse": 12 } for inputs that change die size.

Validation and Testing

  • Meta-schema: packages/games/randsum.json (or https://randsum.dev/schemas/v1/randsum.json)
  • Run codegen: bun run --filter @randsum/games gen
  • Run tests: bun run --filter @randsum/games test
  • Check bundle size: each game should be under 8 KB (except table-heavy games)

Examples

See references/SPEC_EXAMPLES.md for complete working specs at three complexity levels.

Keep looking

Skills are one crate of 611,178. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.