mirror of
https://github.com/Donchitos/Claude-Code-Game-Studios
synced 2026-04-21 13:27:18 +00:00
Skills refinement: improve formatting, phase structure, and trigger descriptions across 9 skills
- balance-check: rewrote as explicit phases with domain routing table; expanded trigger hints - scope-check: restructured into numbered phases for clarity - adopt, review-all-gdds, help, project-stage-detect: add argument mode headers or trigger hints - gate-check, sprint-status, story-readiness: minor wording and structure improvements Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Donchitos
parent
af2b864796
commit
a2f8ed93ff
9 changed files with 194 additions and 98 deletions
|
|
@ -24,6 +24,9 @@ wrong internal format.
|
|||
**Output:** `docs/adoption-plan-[date].md` — a persistent, checkable migration plan.
|
||||
|
||||
**Argument modes:**
|
||||
|
||||
**Audit mode:** `$ARGUMENTS[0]` (blank = `full`)
|
||||
|
||||
- **No argument / `full`**: Complete audit — all artifact types
|
||||
- **`gdds`**: GDD format compliance only
|
||||
- **`adrs`**: ADR format compliance only
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: balance-check
|
||||
description: "Analyzes game balance data files, formulas, and configuration to identify outliers, broken progressions, degenerate strategies, and economy imbalances. Use after modifying any balance-related data or design."
|
||||
description: "Analyzes game balance data files, formulas, and configuration to identify outliers, broken progressions, degenerate strategies, and economy imbalances. Use after modifying any balance-related data or design. Use when user says 'balance report', 'check game balance', 'run a balance check'."
|
||||
argument-hint: "[system-name|path-to-data-file]"
|
||||
user-invocable: true
|
||||
allowed-tools: Read, Glob, Grep
|
||||
|
|
@ -8,44 +8,68 @@ context: fork
|
|||
agent: economy-designer
|
||||
---
|
||||
|
||||
When this skill is invoked:
|
||||
## Phase 1: Identify Balance Domain
|
||||
|
||||
1. **Identify the balance domain** from the argument.
|
||||
Determine the balance domain from `$ARGUMENTS[0]`:
|
||||
|
||||
2. **Read relevant data files** from `assets/data/` and `design/balance/`.
|
||||
- **Combat** → weapon/ability DPS, time-to-kill, damage type interactions
|
||||
- **Economy** → resource faucets/sinks, acquisition rates, item pricing
|
||||
- **Progression** → XP/power curves, dead zones, power spikes
|
||||
- **Loot** → rarity distribution, pity timers, inventory pressure
|
||||
- **File path given** → load that file directly and infer domain from content
|
||||
|
||||
3. **Read the design document** for the system being checked from `design/gdd/`.
|
||||
If no argument, ask the user which system to check.
|
||||
|
||||
4. **Perform analysis**:
|
||||
---
|
||||
|
||||
For **combat balance**:
|
||||
- Calculate DPS for all weapons/abilities at each power tier
|
||||
- Check time-to-kill at each tier
|
||||
- Identify any options that dominate all others (strictly better)
|
||||
- Check if defensive options can create unkillable states
|
||||
- Verify damage type/resistance interactions are balanced
|
||||
## Phase 2: Read Data Files
|
||||
|
||||
For **economy balance**:
|
||||
- Map all resource faucets and sinks with flow rates
|
||||
- Project resource accumulation over time
|
||||
- Check for infinite resource loops
|
||||
- Verify gold sinks scale with gold generation
|
||||
- Check if any items are never worth purchasing
|
||||
Read relevant files from `assets/data/` and `design/balance/` for the identified domain.
|
||||
Note every file read — they will appear in the Data Sources section of the report.
|
||||
|
||||
For **progression balance**:
|
||||
- Plot the XP curve and power curve
|
||||
- Check for dead zones (no meaningful progression for too long)
|
||||
- Check for power spikes (sudden jumps in capability)
|
||||
- Verify content gates align with expected player power
|
||||
- Check if skip/grind strategies break intended pacing
|
||||
---
|
||||
|
||||
For **loot balance**:
|
||||
- Calculate expected time to acquire each rarity tier
|
||||
- Check pity timer math
|
||||
- Verify no loot is strictly useless at any stage
|
||||
- Check inventory pressure vs acquisition rate
|
||||
## Phase 3: Read Design Document
|
||||
|
||||
5. **Output the analysis**:
|
||||
Read the GDD for the system from `design/gdd/` to understand intended design targets,
|
||||
tuning knobs, and expected value ranges. This is the baseline for "correct" behaviour.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Perform Analysis
|
||||
|
||||
Run domain-specific checks:
|
||||
|
||||
**Combat balance:**
|
||||
- Calculate DPS for all weapons/abilities at each power tier
|
||||
- Check time-to-kill at each tier
|
||||
- Identify any options that dominate all others (strictly better)
|
||||
- Check if defensive options can create unkillable states
|
||||
- Verify damage type/resistance interactions are balanced
|
||||
|
||||
**Economy balance:**
|
||||
- Map all resource faucets and sinks with flow rates
|
||||
- Project resource accumulation over time
|
||||
- Check for infinite resource loops
|
||||
- Verify gold sinks scale with gold generation
|
||||
- Check if any items are never worth purchasing
|
||||
|
||||
**Progression balance:**
|
||||
- Plot the XP curve and power curve
|
||||
- Check for dead zones (no meaningful progression for too long)
|
||||
- Check for power spikes (sudden jumps in capability)
|
||||
- Verify content gates align with expected player power
|
||||
- Check if skip/grind strategies break intended pacing
|
||||
|
||||
**Loot balance:**
|
||||
- Calculate expected time to acquire each rarity tier
|
||||
- Check pity timer math
|
||||
- Verify no loot is strictly useless at any stage
|
||||
- Check inventory pressure vs acquisition rate
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Output the Analysis
|
||||
|
||||
```
|
||||
## Balance Check: [System Name]
|
||||
|
|
@ -73,21 +97,23 @@ When this skill is invoked:
|
|||
[Specific values with suggested adjustments and rationale]
|
||||
```
|
||||
|
||||
6. **Fix & Verify Cycle**
|
||||
---
|
||||
|
||||
After presenting the report, ask:
|
||||
## Phase 6: Fix & Verify Cycle
|
||||
|
||||
> "Would you like to fix any of these balance issues now?"
|
||||
After presenting the report, ask:
|
||||
|
||||
If yes:
|
||||
- Ask which issue to address first (refer to the Recommendations table by priority row)
|
||||
- Guide the user to update the relevant data file in `assets/data/` or formula in `design/balance/`
|
||||
- After each fix, offer to re-run the relevant balance checks for that system to verify the fix did not introduce new outliers or degenerate interactions
|
||||
- If the fix changes a tuning knob that is defined in a GDD or referenced by an ADR, remind the user:
|
||||
> "This value is defined in a design document. Run `/propagate-design-change [path]` on the affected GDD to find downstream impacts before committing."
|
||||
> "Would you like to fix any of these balance issues now?"
|
||||
|
||||
If no:
|
||||
- Summarize the open issues and suggest saving the report to `design/balance/balance-check-[system]-[date].md` for later.
|
||||
If yes:
|
||||
- Ask which issue to address first (refer to the Recommendations table by priority row)
|
||||
- Guide the user to update the relevant data file in `assets/data/` or formula in `design/balance/`
|
||||
- After each fix, offer to re-run the relevant balance checks to verify no new outliers were introduced
|
||||
- If the fix changes a tuning knob defined in a GDD or referenced by an ADR, remind the user:
|
||||
> "This value is defined in a design document. Run `/propagate-design-change [path]` on the affected GDD to find downstream impacts before committing."
|
||||
|
||||
End with:
|
||||
> "Re-run `/balance-check` after fixes to verify."
|
||||
If no:
|
||||
- Summarize open issues and suggest saving the report to `design/balance/balance-check-[system]-[date].md` for later
|
||||
|
||||
End with:
|
||||
> "Re-run `/balance-check` after fixes to verify."
|
||||
|
|
|
|||
|
|
@ -1,9 +1,10 @@
|
|||
---
|
||||
name: gate-check
|
||||
description: "Validate readiness to advance between development phases. Produces a PASS/CONCERNS/FAIL verdict with specific blockers and required artifacts."
|
||||
description: "Validate readiness to advance between development phases. Produces a PASS/CONCERNS/FAIL verdict with specific blockers and required artifacts. Use when user says 'are we ready to move to X', 'can we advance to production', 'check if we can start the next phase', 'pass the gate'."
|
||||
argument-hint: "[target-phase: systems-design | technical-setup | pre-production | production | polish | release]"
|
||||
user-invocable: true
|
||||
allowed-tools: Read, Glob, Grep, Bash, Write
|
||||
context: fork
|
||||
---
|
||||
|
||||
# Phase Gate Validation
|
||||
|
|
@ -33,6 +34,8 @@ The project progresses through these stages:
|
|||
|
||||
## 1. Parse Arguments
|
||||
|
||||
**Target phase:** `$ARGUMENTS[0]` (blank = auto-detect current stage, then validate next transition)
|
||||
|
||||
- **With argument**: `/gate-check production` — validate readiness for that specific phase
|
||||
- **No argument**: Auto-detect current stage using the same heuristics as
|
||||
`/project-stage-detect`, then validate the NEXT phase transition
|
||||
|
|
|
|||
|
|
@ -4,6 +4,8 @@ description: "Analyzes what is done and the users query and offers advice on wha
|
|||
argument-hint: "[optional: what you just finished, e.g. 'finished design-review' or 'stuck on ADRs']"
|
||||
user-invocable: true
|
||||
allowed-tools: Read, Glob, Grep
|
||||
context: |
|
||||
!echo "=== Live Project State ===" && echo "Stage: $(cat production/stage.txt 2>/dev/null | tr -d '[:space:]' || echo 'not set')" && echo "Latest sprint: $(ls -t production/sprints/*.md 2>/dev/null | head -1 || echo 'none')" && echo "Session state: $(head -5 production/session-state/active.md 2>/dev/null || echo 'none')"
|
||||
---
|
||||
|
||||
# Studio Help — What Do I Do Next?
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: project-stage-detect
|
||||
description: "Automatically analyze project state, detect stage, identify gaps, and recommend next steps based on existing artifacts."
|
||||
description: "Automatically analyze project state, detect stage, identify gaps, and recommend next steps based on existing artifacts. Use when user asks 'where are we in development', 'what stage are we in', 'full project audit'."
|
||||
argument-hint: "[optional: role filter like 'programmer' or 'designer']"
|
||||
user-invocable: true
|
||||
allowed-tools: Read, Glob, Grep, Bash
|
||||
|
|
@ -93,6 +93,7 @@ Use template: `.claude/docs/templates/project-stage-report.md`
|
|||
|
||||
**Date**: [date]
|
||||
**Stage**: [Concept/Systems Design/Technical Setup/Pre-Production/Production/Polish/Release]
|
||||
**Stage Confidence**: [PASS — clearly detected / CONCERNS — ambiguous signals / FAIL — critical gaps block progress]
|
||||
|
||||
## Completeness Overview
|
||||
- Design: [X%] ([N] docs, [gaps])
|
||||
|
|
|
|||
|
|
@ -29,6 +29,9 @@ completeness. This skill reviews the *relationships* between all GDDs.
|
|||
inherits those inconsistencies)
|
||||
|
||||
**Argument modes:**
|
||||
|
||||
**Focus:** `$ARGUMENTS[0]` (blank = `full`)
|
||||
|
||||
- **No argument / `full`**: Both consistency and design theory passes
|
||||
- **`consistency`**: Cross-GDD consistency checks only (faster)
|
||||
- **`design-theory`**: Game design holism checks only
|
||||
|
|
|
|||
|
|
@ -1,73 +1,126 @@
|
|||
---
|
||||
name: scope-check
|
||||
description: "Analyze a feature or sprint for scope creep by comparing current scope against the original plan. Flags additions, quantifies bloat, and recommends cuts."
|
||||
description: "Analyze a feature or sprint for scope creep by comparing current scope against the original plan. Flags additions, quantifies bloat, and recommends cuts. Use when user says 'any scope creep', 'scope review', 'are we staying in scope'."
|
||||
argument-hint: "[feature-name or sprint-N]"
|
||||
user-invocable: true
|
||||
allowed-tools: Read, Glob, Grep
|
||||
context: |
|
||||
!git diff --stat HEAD~20 2>/dev/null
|
||||
allowed-tools: Read, Glob, Grep, Bash
|
||||
context: fork
|
||||
---
|
||||
When this skill is invoked:
|
||||
|
||||
1. **Read the original plan** — Find the relevant document:
|
||||
- If a feature name: read the design doc from `design/gdd/`
|
||||
- If a sprint number: read the sprint plan from `production/sprints/`
|
||||
- If a milestone: read the milestone definition from `production/milestones/`
|
||||
# Scope Check
|
||||
|
||||
2. **Read the current state** — Check what has actually been implemented or is in progress:
|
||||
- Scan the codebase for files related to the feature/sprint
|
||||
- Read git log for commits related to this work
|
||||
- Check for TODO comments that indicate unfinished scope additions
|
||||
Compares original planned scope against current state to detect, quantify, and triage
|
||||
scope creep. Read-only — never edits files without approval.
|
||||
|
||||
3. **Compare original vs current scope**:
|
||||
**Argument:** `$ARGUMENTS[0]` — feature name, sprint number, or milestone name.
|
||||
|
||||
```markdown
|
||||
## Scope Check: [Feature/Sprint Name]
|
||||
Generated: [Date]
|
||||
---
|
||||
|
||||
### Original Scope
|
||||
[List of items from the original plan]
|
||||
## Phase 1: Find the Original Plan
|
||||
|
||||
### Current Scope
|
||||
[List of items currently implemented or in progress]
|
||||
Locate the baseline scope document for the given argument:
|
||||
|
||||
### Scope Additions (not in original plan)
|
||||
| Addition | Who Added | When | Justified? | Effort |
|
||||
|----------|-----------|------|------------|--------|
|
||||
| [item] | [commit/person] | [date] | [Yes/No/Unclear] | [S/M/L] |
|
||||
- **Feature name** → read `design/gdd/[feature].md` or matching file in `design/`
|
||||
- **Sprint number** (e.g., `sprint-3`) → read `production/sprints/sprint-03.md` or similar
|
||||
- **Milestone** → read `production/milestones/[name].md`
|
||||
|
||||
### Scope Removals (in original but dropped)
|
||||
| Removed Item | Reason | Impact |
|
||||
|-------------|--------|--------|
|
||||
| [item] | [why removed] | [what's affected] |
|
||||
If the document is not found, report the missing file and stop. Do not proceed without
|
||||
a baseline to compare against.
|
||||
|
||||
### Bloat Score
|
||||
- Original items: [N]
|
||||
- Current items: [N]
|
||||
- Items added: [N] (+[X]%)
|
||||
- Items removed: [N]
|
||||
- Net scope change: [+/-N] ([X]%)
|
||||
---
|
||||
|
||||
### Risk Assessment
|
||||
- **Schedule Risk**: [Low/Medium/High] — [explanation]
|
||||
- **Quality Risk**: [Low/Medium/High] — [explanation]
|
||||
- **Integration Risk**: [Low/Medium/High] — [explanation]
|
||||
## Phase 2: Read the Current State
|
||||
|
||||
### Recommendations
|
||||
1. **Cut**: [Items that should be removed to stay on schedule]
|
||||
2. **Defer**: [Items that can move to a future sprint/version]
|
||||
3. **Keep**: [Additions that are genuinely necessary]
|
||||
4. **Flag**: [Items that need a decision from producer/creative-director]
|
||||
```
|
||||
Check what has actually been implemented or is in progress:
|
||||
|
||||
4. **Output the scope check** with a clear verdict:
|
||||
- **On Track**: Scope within 10% of original
|
||||
- **Minor Creep**: 10-25% scope increase — manageable with adjustments
|
||||
- **Significant Creep**: 25-50% scope increase — need to cut or extend timeline
|
||||
- **Out of Control**: >50% scope increase — stop and re-plan
|
||||
- Scan the codebase for files related to the feature/sprint
|
||||
- Read git log for commits related to this work (`git log --oneline --since=[start-date]`)
|
||||
- Check for TODO/FIXME comments that indicate unfinished scope additions
|
||||
- Check active sprint plan if the feature is mid-sprint
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Compare Original vs Current Scope
|
||||
|
||||
Produce the comparison report:
|
||||
|
||||
```markdown
|
||||
## Scope Check: [Feature/Sprint Name]
|
||||
Generated: [Date]
|
||||
|
||||
### Original Scope
|
||||
[List of items from the original plan]
|
||||
|
||||
### Current Scope
|
||||
[List of items currently implemented or in progress]
|
||||
|
||||
### Scope Additions (not in original plan)
|
||||
| Addition | Source | When | Justified? | Effort |
|
||||
|----------|--------|------|------------|--------|
|
||||
| [item] | [commit/person] | [date] | [Yes/No/Unclear] | [S/M/L] |
|
||||
|
||||
### Scope Removals (in original but dropped)
|
||||
| Removed Item | Reason | Impact |
|
||||
|-------------|--------|--------|
|
||||
| [item] | [why removed] | [what's affected] |
|
||||
|
||||
### Bloat Score
|
||||
- Original items: [N]
|
||||
- Current items: [N]
|
||||
- Items added: [N] (+[X]%)
|
||||
- Items removed: [N]
|
||||
- Net scope change: [+/-N] ([X]%)
|
||||
|
||||
### Risk Assessment
|
||||
- **Schedule Risk**: [Low/Medium/High] — [explanation]
|
||||
- **Quality Risk**: [Low/Medium/High] — [explanation]
|
||||
- **Integration Risk**: [Low/Medium/High] — [explanation]
|
||||
|
||||
### Recommendations
|
||||
1. **Cut**: [Items that should be removed to stay on schedule]
|
||||
2. **Defer**: [Items that can move to a future sprint/version]
|
||||
3. **Keep**: [Additions that are genuinely necessary]
|
||||
4. **Flag**: [Items that need a decision from producer/creative-director]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Verdict
|
||||
|
||||
Assign a canonical verdict based on net scope change:
|
||||
|
||||
| Net Change | Verdict | Meaning |
|
||||
|-----------|---------|---------|
|
||||
| ≤10% | **PASS** | On Track — within acceptable variance |
|
||||
| 10–25% | **CONCERNS** | Minor Creep — manageable with targeted cuts |
|
||||
| 25–50% | **FAIL** | Significant Creep — must cut or formally extend timeline |
|
||||
| >50% | **FAIL** | Out of Control — stop, re-plan, escalate to producer |
|
||||
|
||||
Output the verdict prominently:
|
||||
|
||||
```
|
||||
**Scope Verdict: [PASS / CONCERNS / FAIL]**
|
||||
Net change: [+X%] — [On Track / Minor Creep / Significant Creep / Out of Control]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Next Steps
|
||||
|
||||
After presenting the report, offer concrete follow-up:
|
||||
|
||||
- **PASS** → no action required. Suggest re-running before next milestone.
|
||||
- **CONCERNS** → offer to identify the 2–3 additions with best cut ratio. Reference `/sprint-plan update` to formally re-scope.
|
||||
- **FAIL** → recommend escalating to producer. Reference `/sprint-plan update` for re-planning or `/estimate` to re-baseline timeline.
|
||||
|
||||
Always end with:
|
||||
> "Run `/scope-check [name]` again after cuts are made to verify the verdict improves."
|
||||
|
||||
---
|
||||
|
||||
### Rules
|
||||
|
||||
- Scope creep is additions without corresponding cuts or timeline extensions
|
||||
- Not all additions are bad — some are discovered requirements. But they must be acknowledged and accounted for.
|
||||
- Not all additions are bad — some are discovered requirements. But they must be acknowledged and accounted for
|
||||
- When recommending cuts, prioritize preserving the core player experience over nice-to-haves
|
||||
- Always quantify scope changes — "it feels bigger" is not actionable, "+35% items" is
|
||||
|
|
|
|||
|
|
@ -1,9 +1,10 @@
|
|||
---
|
||||
name: sprint-status
|
||||
description: "Fast sprint status check. Reads the current sprint plan, scans story files for status, and produces a concise progress snapshot with burndown assessment and emerging risks. Run at any time during a sprint for quick situational awareness."
|
||||
description: "Fast sprint status check. Reads the current sprint plan, scans story files for status, and produces a concise progress snapshot with burndown assessment and emerging risks. Run at any time during a sprint for quick situational awareness. Use when user asks 'how is the sprint going', 'sprint update', 'show sprint progress'."
|
||||
argument-hint: "[sprint-number or blank for current]"
|
||||
user-invocable: true
|
||||
allowed-tools: Read, Glob, Grep
|
||||
context: fork
|
||||
---
|
||||
|
||||
# Sprint Status
|
||||
|
|
@ -20,6 +21,8 @@ files, and makes at most one concrete recommendation.
|
|||
|
||||
## 1. Find the Sprint
|
||||
|
||||
**Argument:** `$ARGUMENTS[0]` (blank = use current sprint)
|
||||
|
||||
- If an argument is given (e.g., `/sprint-status 3`), search
|
||||
`production/sprints/` for a file matching `sprint-03.md`, `sprint-3.md`,
|
||||
or similar. Report which file was found.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: story-readiness
|
||||
description: "Validate that a story file is implementation-ready. Checks for embedded GDD requirements, ADR references, engine notes, clear acceptance criteria, and no open design questions. Produces READY / NEEDS WORK / BLOCKED verdict with specific gaps."
|
||||
description: "Validate that a story file is implementation-ready. Checks for embedded GDD requirements, ADR references, engine notes, clear acceptance criteria, and no open design questions. Produces READY / NEEDS WORK / BLOCKED verdict with specific gaps. Use when user says 'is this story ready', 'can I start on this story', 'is story X ready to implement'."
|
||||
argument-hint: "[story-file-path or 'all' or 'sprint']"
|
||||
user-invocable: true
|
||||
allowed-tools: Read, Glob, Grep
|
||||
|
|
@ -23,6 +23,8 @@ gap list for each non-ready story.
|
|||
|
||||
## 1. Parse Arguments
|
||||
|
||||
**Scope:** `$ARGUMENTS[0]` (blank = ask user via AskUserQuestion)
|
||||
|
||||
- **Specific path** (e.g., `/story-readiness production/epics/combat/story-001-basic-attack.md`):
|
||||
validate that single story file.
|
||||
- **`sprint`**: read the current sprint plan from `production/sprints/` (most
|
||||
|
|
|
|||
Loading…
Reference in a new issue