How to use the Map Systems agent skill: install and run it

What the Map Systems skill makes the agent do

An agent skill is a folder containing a SKILL.md file that tells an AI agent how to carry out a specific task. This skill covers one stage of game planning: breaking a concept into systems.

The agent reads the game concept, lists explicit systems mentioned in the concept (such as inventory, combat or progression), and then infers implicit systems. For example, the source notes that inventory implies an item database, equipment slots, weight or capacity rules, an inventory UI, and item serialization for save and load. It then records dependencies between systems and ranks them into a suggested design order.

• Reads the game concept file and any existing design work
• Enumerates explicit and implicit systems, organized by category
• Maps which systems depend on which others
• Suggests a design order based on those dependencies
• Writes a systems index file

Install the Map Systems skill

Download the ZIP file for this skill from this page and unzip it. The skill is a folder that must end up inside a skills directory the agent reads from. You have two options.

For all your projects, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder.

In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/map-systems/
• Project install: .claude/skills/map-systems/ inside your repository

Prepare your project before running it

The skill expects a game concept file at design/gdd/game-concept.md. If you use minimal workflow mode, it reads design/game-brief.md instead. The concept file is created by the /brainstorm skill. If neither file exists, the skill stops and tells you to run /brainstorm first.

The skill also relies on the yaml-helper.sh script and .claude/docs configuration files in the surrounding repository. These come with the Claude Code Game Studios template. Without them the skill cannot read its settings, so run it inside that repository structure.

• Required: design/gdd/game-concept.md (or design/game-brief.md in minimal mode)
• Required: yaml-helper.sh script and .claude/docs configuration files in the repository
• Required: Claude Code or a compatible agent that supports SKILL.md skills

Trigger the skill with a request

You can invoke the skill directly with a slash command, or ask for it in plain language once it is installed. The skill accepts two modes.

With no argument, it runs the full decomposition workflow and creates or updates the systems index. With the next argument, it picks the highest-priority system that has not been designed yet and hands off to /design-system.

Optional flags are listed in the argument hint as --review full, lean or solo, which controls how often the agent asks for your approval.

• /map-systems runs the full workflow to create or update the systems index
• /map-systems next picks the next undesigned system and hands off to /design-system
• Plain request example: "Break my game concept into systems and map the dependencies"

Work through the approval steps

This skill is collaborative. In the default collaborative setting, the agent asks you to confirm the system list, the dependencies, the priorities and each file write before it continues. Each answer is handled before the next step runs.

If you want less interruption, the source describes guided and autonomous modes, which ask less often. In autonomous mode the agent records its decisions and proceeds. Expect repeated questions if you want to stay in control of the output.

• Confirm or edit the system list, including missing, merged or unnecessary systems
• Approve the dependency map
• Approve the priority order
• Approve each file write

Safety notes: scripts and network access

The skill runs scripts. Its configuration step calls the yaml-helper.sh script in the repository's hooks folder to read settings. It is allowed to read and write files in the project and to use the task tools it lists. The source states that it does not use the network.

Because it runs a script, read the script in your repository before you run the skill on a project you do not trust.

• Runs scripts: yes, via yaml-helper.sh to resolve configuration
• Uses network: no
• Writes files in the project, such as the systems index, after you approve each write