How to use the Playtest Report agent skill (playtest-report)

What does the playtest-report skill make the agent do?

The skill works in two modes. In new mode, the agent outputs a blank playtest report template with sections for session info, test focus, first impressions, gameplay flow, bugs, feature-specific feedback, quantitative data, overall assessment and a top-3 priority list. The template ends the job: nothing is routed or saved.

In analyze mode, you give the agent a path to raw tester notes. It reads those notes, cross-references them with existing design documents, and fills in the template with structured findings. Observations that describe defects such as crashes, framerate drops or softlocks go in the Bugs Encountered table; observations about how the game feels to play go under pain points.

• Sorts findings into four buckets: design changes, balance adjustments, bug reports and polish items.
• Suggests next commands for each bucket, such as /propagate-design-change, /balance-check, /bug-report and adding items to the polish backlog in production/.
• Flags playtest observations that conflict with design intent.
• Can ask permission and then save the report to production/qa/playtests/.

How do you install the playtest-report skill?

The skill is distributed as a ZIP file from the agent-skills directory page. Download the ZIP and unzip it into one of two locations. For a personal setup, unzip into ~/.claude/skills/. For a single project, unzip into the project's .claude/skills/ folder.

If you use the Claude apps rather than Claude Code, you can upload the skill instead. In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the skill there.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload

What do you need before the skill works?

The skill is written for a larger multi-agent game-studio setup. It expects Claude Code or a compatible SKILL.md agent runtime, and it needs the repository's .claude/hooks/yaml-helper.sh script along with the .claude/docs files named config-resolution, director-gates and automation-modes. It also needs Bash access for the config-resolution command.

Pillars are optional but improve the review. If design/gdd/game-concept.md or design/game-brief.md exists, the skill uses it for pillars. Existing design documents are used for cross-referencing.

Several routing steps call sibling commands: /propagate-design-change, /balance-check, /bug-report, /bug-triage and /design-review. Those must exist or the routing steps will not work.

• Claude Code or a compatible SKILL.md runtime
• The .claude/hooks/yaml-helper.sh script and .claude/docs files (config-resolution, director-gates, automation-modes)
• Bash access for the config-resolution command
• Optional: design/gdd/game-concept.md or design/game-brief.md, plus existing design documents
• Sibling commands: /propagate-design-change, /balance-check, /bug-report, /bug-triage, /design-review

How do you trigger the skill with natural requests?

The skill accepts an argument in the form [new|analyze path-to-notes] with an optional --review flag set to full, lean or solo. If you give no argument, the agent asks whether you want a new blank template or want to analyze notes and will provide a path.

The --review flag overrides the review_mode setting for that run. In full mode the Creative Director player experience review runs. In lean and solo modes it is skipped.

• Blank form: ask for a new playtest report template
• Analyze notes: give the path to your raw notes file, for example "Analyze the playtest notes at notes/tester3.txt"
• Lighter review: add --review lean or --review solo to skip the director review

What does an example run look like?

Suppose you have a text file of notes from a first-time tester. You run analyze mode on that file. The agent reads the notes, checks them against your design documents, and fills in the template. Pain points and confusion points are listed with severity, crashes go into the bug table, and findings are grouped into the four routing buckets.

If review mode is full, the agent then spawns the creative-director agent to assess the player experience against your pillars or the hypothesis being tested. Before saving, the agent asks permission to write production/qa/playtests/playtest-[date]-[tester].md. If you say yes, it writes the file and closes with next steps: address the highest-priority category first, re-run /design-review after design changes, and re-run /bug-triage after fixing bugs.

What are the safety notes for scripts and network access?

The skill runs scripts. Its config-resolution step runs the repository's yaml-helper.sh script through Bash to read review_mode and automation settings. It does not use the network. The tools it is allowed to use are Read, Glob, Grep, Write, Agent, AskUserQuestion and that one Bash command.

It writes files only after asking. Phase 4 requires your permission before saving a report. Read the script before installing if you want to confirm what it does on your machine.

• Runs scripts: yes, the yaml-helper.sh config-resolution command via Bash
• Uses network: no
• Writes to disk only after you approve the save step

Tips for getting useful results

Give the agent notes that include tester details, build and the features being tested, because the session info section is filled from them. Keep your design documents current, since cross-referencing depends on them. Use the review flag deliberately: lean or solo is faster when you only need the report and routing.

• Put the build identifier and session type in your notes so the session info is accurate
• Keep game-concept.md or game-brief.md up to date so the review has pillars to work from
• Use new mode when you only need the blank form to hand to testers