Add: inspiration-page-creator skill for autonomous game documentation
This commit is contained in:
332
.opencode/skills/inspiration-page-creator/SKILL.md
Normal file
332
.opencode/skills/inspiration-page-creator/SKILL.md
Normal file
@@ -0,0 +1,332 @@
|
||||
---
|
||||
name: inspiration-page-creator
|
||||
description: This skill should be used when creating new game pages for the Inspiration section of puzzle-design-kb. It automates walkthrough analysis, puzzle extraction, and documentation in a standardized format while managing TODOS.md and committing after completion.
|
||||
---
|
||||
|
||||
# Inspiration Page Creator Skill
|
||||
|
||||
## Quick Start
|
||||
|
||||
```
|
||||
1. Load this skill before starting any inspiration page work
|
||||
2. Read todos/TODOS.md to find next game task marked with [ ]
|
||||
3. Execute autonomous workflow (no user intervention needed)
|
||||
4. Commit and mark TODO complete after page creation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workflow: Autonomous Page Creation
|
||||
|
||||
### Step 1: Identify Target Game from TODOS
|
||||
|
||||
Read `todos/TODOS.md` and locate the first unchecked game entry under "Puzzle Sampling Chapter":
|
||||
|
||||
```markdown
|
||||
- [ ] <Game Name>: analyze walkthrough and create game section
|
||||
- [ ] Examine walkthrough files in src/walkthroughs/<game-dir>/
|
||||
- [ ] Identify the 3 best puzzles using analysis-checklist.md criteria
|
||||
- [ ] Write Problem/Why It Works/Solution/Steps for each puzzle
|
||||
- [ ] Link each puzzle to its pattern type from the Playbook
|
||||
```
|
||||
|
||||
**Set target game name and corresponding walkthrough directory path.**
|
||||
|
||||
---
|
||||
|
||||
### Step 2: Examine Walkthrough Files
|
||||
|
||||
Navigate to `src/walkthroughs/<game-dir>/` and list all files:
|
||||
|
||||
```bash
|
||||
ls src/walkthroughs/<game-dir>/
|
||||
```
|
||||
|
||||
Read the README first if it exists (`README.txt` or similar). Note available walkthrough sources, authors, and any special notes about the game's design.
|
||||
|
||||
Read **at least 2 complete walkthroughs** from different sources to:
|
||||
- Identify all puzzles in the game
|
||||
- Find quotes about player enjoyment moments
|
||||
- Gather multiple perspectives on puzzle mechanics
|
||||
- Collect citation information (author name, source, URL)
|
||||
|
||||
---
|
||||
|
||||
### Step 3: Select 3 Best Puzzles
|
||||
|
||||
Apply these criteria for puzzle selection (from `docs/analysis-checklist.md`):
|
||||
|
||||
**Priority 1: Mechanical Clarity**
|
||||
- Can the pattern type be clearly identified?
|
||||
- Is the solution chain reproducible across different playthroughs?
|
||||
- Does it demonstrate a documented pattern from Playbook?
|
||||
|
||||
**Priority 2: "Aha Moment" Presence**
|
||||
- Do walkthrough authors explicitly mention discovery or satisfaction?
|
||||
- Is there a moment where information clicks together non-trivially?
|
||||
- Does the solution feel earned rather than obvious?
|
||||
|
||||
**Priority 3: Pattern Diversity**
|
||||
- Avoid selecting 3 puzzles of identical pattern type if possible
|
||||
- Show range of mechanics the game offers
|
||||
- Include at least one puzzle requiring multi-step reasoning
|
||||
|
||||
**Select exactly 3 puzzles. Note any 5-8 additional notable puzzles for "Other Puzzles" table.**
|
||||
|
||||
---
|
||||
|
||||
### Step 4: Extract Required Content For Each Featured Puzzle
|
||||
|
||||
For **each of the 3 selected puzzles**, extract:
|
||||
|
||||
1. **Problem Setup (2-3 sentences)**
|
||||
- What must player accomplish?
|
||||
- Key information or prerequisite knowledge required
|
||||
- If riddle or dialogue involved, copy exact game text for blockquote
|
||||
|
||||
2. **What Makes It Rewarding (2-3 sentences + quote)**
|
||||
- Mechanical design choice that creates satisfaction
|
||||
- How information was fairly conveyed to player
|
||||
- Why this isn't trial-and-error or fetch-quest filler
|
||||
- **REQUIRED:** Direct quote from walkthrough author about experiencing this puzzle
|
||||
|
||||
3. **Solution (1 sentence)**
|
||||
- Outcome achieved upon completion
|
||||
|
||||
4. **Steps (numbered list)**
|
||||
- Specific, mechanical actions (no "solve puzzle" vagueness)
|
||||
- Each step should be an observable player action
|
||||
- Include state changes or discovered information as relevant
|
||||
|
||||
5. **Pattern Type Classification**
|
||||
- Identify which Playbook pattern type matches
|
||||
- Write 1-sentence distinction connecting this example to core mechanic
|
||||
- Differentiate from at least one similar pattern type
|
||||
|
||||
6. **Screenshot Placeholder**
|
||||
- One per puzzle with descriptive alt text hint
|
||||
- Describe specific visual: objects, UI state, "before/after" moment
|
||||
|
||||
---
|
||||
|
||||
### Step 5: Extract Additional Content
|
||||
|
||||
1. **At a Glance Table Data:**
|
||||
- Release year
|
||||
- Developer/studio/designer name(s)
|
||||
- One-sentence core mechanic description
|
||||
- Minimum 2 direct quotes about player enjoyment with attributions
|
||||
|
||||
2. **Other Puzzles (6-10 entries):**
|
||||
- Name of puzzle
|
||||
- 10-15 word problem and solution summary
|
||||
- Pattern type classification with link
|
||||
- Include inline quotation citations if memorable moments exist
|
||||
|
||||
3. **References Section:**
|
||||
- Full author names
|
||||
- Source titles
|
||||
- Publication years (if known)
|
||||
- URLs for all cited walkthrough sources
|
||||
|
||||
---
|
||||
|
||||
### Step 6: Create the Page File
|
||||
|
||||
Create file at `src/inspiration/<game-name-kebab-case>.md` using exact template from `references/template.md`.
|
||||
|
||||
**While writing:**
|
||||
- Fill each section with extracted content
|
||||
- Format direct quotes as blockquotes (riddles/game text) or inline commentary (author observations)
|
||||
- Use citation keys consistently: `[Author]`, `[SourceAuthor]`, etc.
|
||||
- Include exactly 3 featured puzzles, plus Other Puzzles table
|
||||
- Add screenshot placeholders with descriptive alt text
|
||||
|
||||
**Word count target:** ~1,000 words total (don't exceed significantly)
|
||||
|
||||
---
|
||||
|
||||
### Step 7: Verify Pattern Type Links
|
||||
|
||||
List existing pattern files to verify all links work:
|
||||
|
||||
```bash
|
||||
ls src/puzzles/*.md
|
||||
```
|
||||
|
||||
Cross-reference every Pattern Type link in your page against this list. **Correct any broken paths before proceeding.**
|
||||
|
||||
Common corrections:
|
||||
- `metaphor-to-literal.md` → `metaphor-literal.md` (actual filename)
|
||||
- Ensure relative path is `../puzzles/` (not `./puzzles/`)
|
||||
|
||||
Build book to confirm no link errors:
|
||||
|
||||
```bash
|
||||
mdbook build 2>&1 | grep -i "<game-name>"
|
||||
```
|
||||
|
||||
If warnings or errors appear about missing links, fix them.
|
||||
|
||||
---
|
||||
|
||||
### Step 8: Update SUMMARY.md
|
||||
|
||||
Add entry under `# Inspiration` section in `src/SUMMARY.md`:
|
||||
|
||||
```markdown
|
||||
## Games Analyzed
|
||||
|
||||
- [<Game Name> (<Year>)](inspiration/<game-name-kebab-case>.md)
|
||||
```
|
||||
|
||||
If "Inspiration" section doesn't exist yet, add it after "Core Principles":
|
||||
|
||||
```markdown
|
||||
# Core Principles
|
||||
|
||||
- [Core Principles](core-principles.md)
|
||||
|
||||
# Inspiration
|
||||
|
||||
## Games Analyzed
|
||||
|
||||
- [<Game Name> (<Year>)](inspiration/<game-name-kebab-case>.md)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 9: Update TODOS and Commit
|
||||
|
||||
Mark the game task as complete in `todos/TODOS.md`:
|
||||
|
||||
**Before:**
|
||||
```markdown
|
||||
- [ ] <Game Name>: analyze walkthrough and create game section
|
||||
- [ ] Examine walkthrough files in src/walkthroughs/<game-dir>/
|
||||
- [ ] Identify the 3 best puzzles using analysis-checklist.md criteria
|
||||
- [ ] Write Problem/Why It Works/Solution/Steps for each puzzle
|
||||
- [ ] Link each puzzle to its pattern type from the Playbook
|
||||
```
|
||||
|
||||
**After:**
|
||||
```markdown
|
||||
- [x] <Game Name>: analyze walkthrough and create game section
|
||||
- [x] Examine walkthrough files in src/walkthroughs/<game-dir>/
|
||||
- [x] Identify the 3 best puzzles using analysis-checklist.md criteria
|
||||
- [x] Write Problem/Why It Works/Solution/Steps for each puzzle
|
||||
- [x] Link each puzzle to its pattern type from the Playbook
|
||||
```
|
||||
|
||||
**Stage and commit:**
|
||||
|
||||
```bash
|
||||
git add src/inspiration/<game>.md todos/TODOS.md src/SUMMARY.md
|
||||
git commit -m "Complete: <Game Name> inspiration page with 3 featured puzzles and pattern type links"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Critical Validation Checklist
|
||||
|
||||
Before committing, verify:
|
||||
|
||||
- [ ] File created at correct path: `src/inspiration/<kebab-case-game-name>.md`
|
||||
- [ ] Exactly 3 featured puzzles with full Problem/Rewarding/Solution/Steps sections
|
||||
- [ ] One screenshot placeholder per featured puzzle with specific alt text hint
|
||||
- [ ] At least one direct quote in each "What Makes It Rewarding" section (formatted correctly)
|
||||
- [ ] Minimum two quotes in "What players found enjoyable" field of At a Glance table
|
||||
- [ ] Other Puzzles table has 6-10 entries with pattern links and descriptions
|
||||
- [ ] References section includes full URLs for every cited walkthrough source
|
||||
- [ ] All Pattern Type links verified against existing `src/puzzles/*.md` files
|
||||
- [ ] Citation keys are consistent (key in text matches entry in References)
|
||||
- [ ] Word count near 1,000 words (acceptable range: 800-1,200)
|
||||
- [ ] SUMMARY.md updated with new game entry
|
||||
- [ ] TODOS.md marked complete for this game task
|
||||
- [ ] No unintended files staged (check `git status` before commit)
|
||||
|
||||
---
|
||||
|
||||
## Autonomy Rules
|
||||
|
||||
**Do not ask user for input on:**
|
||||
- Which puzzle to describe next (proceed through all 3 selected puzzles)
|
||||
- Word count adjustments (trust the ~1,000 word target)
|
||||
- Whether to include a specific detail (if it fits guidelines, include it)
|
||||
- Commit message format (use standard template: "Complete: <Game>...")
|
||||
|
||||
**Do ask user for input on:**
|
||||
- Only if walkthrough files are missing or incomplete in expected directory
|
||||
- If Pattern Type classification is genuinely ambiguous (after checking existing playbook types)
|
||||
- If game design decision is unclear from available walkthroughs
|
||||
|
||||
---
|
||||
|
||||
## Common Pitfalls to Avoid
|
||||
|
||||
### ❌ Wrong: Narrative-over-mechanics focus
|
||||
```markdown
|
||||
"The tragic story of Bobbin Threadbare and his quest to save the world..."
|
||||
```
|
||||
|
||||
### ✅ Correct: Mechanical description
|
||||
```markdown
|
||||
"Player learns magical drafts by observing enchanted objects; each draft can then be reused elsewhere."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ❌ Wrong: Vague reward analysis
|
||||
```markdown
|
||||
"This puzzle is clever and creative."
|
||||
```
|
||||
|
||||
### ✅ Correct: Mechanical satisfaction
|
||||
```markdown
|
||||
"The player realizes the dragon only eats *white* sheep (established in dialogue), so DYE learned on wool becomes camouflage—applying rules consistently across contexts rather than trial-and-error spam."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ❌ Wrong: Missing quote attribution
|
||||
```markdown
|
||||
"One walkthrough notes this was memorable."
|
||||
```
|
||||
|
||||
### ✅ Correct: Proper citation placement
|
||||
```markdown
|
||||
"One walkthrough notes: 'the magical land was unlike any I'd ever seen' [AuthorKey]."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Path References
|
||||
|
||||
- **Output location:** `src/inspiration/<game-name>.md`
|
||||
- **Walkthrough sources:** `src/walkthroughs/<game-dir>/`
|
||||
- **Task tracking:** `todos/TODOS.md`
|
||||
- **Navigation links:** `src/SUMMARY.md`
|
||||
- **Pattern type files:** `src/puzzles/*.md`
|
||||
- **Skill references:** This skill's directory contains template and formatting guide
|
||||
|
||||
---
|
||||
|
||||
## Execution Command Flow
|
||||
|
||||
```bash
|
||||
# Step 1: Identify target game
|
||||
cat todos/TODOS.md | grep -A 5 "^\- \[ \]" | head -20
|
||||
|
||||
# Step 2: List walkthrough files
|
||||
ls src/walkthroughs/<game-dir>/
|
||||
|
||||
# Step 7: Verify pattern links exist
|
||||
ls src/puzzles/*.md
|
||||
|
||||
# Step 8: Build check after page creation
|
||||
mdbook build 2>&1 | grep -i "<game-name>"
|
||||
|
||||
# Step 9: Commit changes
|
||||
git add src/inspiration/<game>.md todos/TODOS.md src/SUMMARY.md
|
||||
git commit -m "Complete: <Game Name> inspiration page with 3 featured puzzles and pattern type links"
|
||||
```
|
||||
Reference in New Issue
Block a user