How to use the Tune Enemy AI agent skill

What is an agent skill, and what does this one make the agent do?

An agent skill is a folder of instructions that an AI coding agent can load when a task matches it. The main file, SKILL.md, tells the agent how to approach that kind of work. This skill covers the brain of combat enemies: aggro, target selection, navigation, spacing, attack choices, telegraphs, retreats, boss behavior, behavior-state machines and deterministic AI regression tests.

Once it is active, the agent is guided to model enemy decisions explicitly with named states such as idle, investigate, pursue, reposition, windup, attack, recover, stagger, retreat and defeated. Each state transition is expected to state its prerequisites, exit conditions, minimum dwell time and cooldown effects. The agent also separates perception, intent and motion, so enemies choose one action from legal options instead of changing their minds mid-attack.

• Structures enemy behavior as named states with clear transition rules
• Makes attacks telegraphed so players can see them before they become active
• Uses authoritative collision and navigation results for movement success
• Writes deterministic tests for target loss, obstruction, path failure, boss phases, reset and more
• Runs a real browser encounter after automated tests

Install the tune-enemy-ai skill

Download the skill ZIP from this page. The skill folder contains agents/openai.yaml and SKILL.md. Unzip it into one of two locations, depending on how you want to use it.

For a personal install that applies across your projects, unzip the folder into ~/.claude/skills/. For a skill that only applies to one project, unzip it into that project's .claude/skills/ folder.

If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.

• Personal: ~/.claude/skills/
• Single project: the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills

Trigger the skill with natural requests

You do not need a special command. The skill's description lists the situations it covers, so ask for enemy work in plain language that names the kind of problem. The more specific the request, the easier it is for the agent to match the skill and apply its state and testing rules.

Good requests name the enemy, the behavior and the problem. Include the feature you care about, such as aggro, boss phases or retreats.

• Design a state machine for a melee grunt that telegraphs a heavy attack and retreats when hurt.
• Debug why my archer keeps chasing the player into walls and never fires.
• Balance the spacing between two enemy types so they do not swarm the player together.
• Write deterministic regression tests for my boss's phase transitions and reset behavior.
• Review this enemy's attack choices and tell me where the player gets instant turn-and-hit damage.

Example workflow for a new enemy

A typical session starts with a description of the enemy and what it should do. The agent is expected to propose named states and transition rules, then implement them and add fixtures for the decision surface. Fixtures cover situations such as target acquisition, target loss, obstruction, close-range pressure and multiple enemies.

The skill asks the agent to assert transitions and outcomes, not only final positions, so tests check why an enemy acted as it did. Finish by running a real browser encounter to confirm the behavior feels right in the game.

What you need before you start

The skill lists no required tools or packages. It is guidance for an agent working on your game code, so you need an existing action game project or a plan for one, and an AI coding agent that supports agent skills. The skill does not supply game assets, an engine integration or a finished enemy.

The skill is licensed under MIT. It does not run scripts and does not use the network, according to its listing.

Safety notes on scripts and network access

Because this skill runs no scripts and uses no network, its contents are instructions rather than executable code. Still, read the SKILL.md and agents/openai.yaml files before installing any skill, and review every change the agent makes to your game code and tests.

The guidance itself asks the agent to base movement success on authoritative collision and navigation results, not on rendered pose or assumed path completion. Keep that rule in mind when reviewing the agent's output.

• Files in the skill: agents/openai.yaml and SKILL.md
• Runs scripts: no
• Uses network: no

Tips for better enemy AI results

Describe the player's experience you want, such as a readable windup or a boss that pauses between phases. The skill emphasises fair combat, so a clear goal helps the agent choose spacing and commitment values.

Ask for tests before tuning. Deterministic fixtures make it easier to see what a balance change actually altered.

• Name each enemy archetype and its role in the encounter.
• Ask the agent to list state transitions with their prerequisites, exit conditions, dwell times and cooldowns.
• Request fixtures for multiple enemies and interruption, not just a single enemy in an empty room.
• Always finish with a real browser encounter, not only automated tests.