npc-blocking - SKILL.md Agent Skill

name: npc-blocking description: Use when an NPC guards an exit, item, or action. Handles bypass flags, turn limits, and NPC behavior enforcement.

NPC Blocking & Bypass Logic

When to Apply

Apply this skill when:

The player is in a location with NPCs
An NPC guards an exit, item, or action
The player attempts to pass a guarded area
The player interacts with or attacks an NPC

Bypass Flags

Before applying NPC blocking behavior, check the current flags in game state. If any of these bypass flags are set, the NPC has already been dealt with and no longer blocks passage or guards items:

Flag	NPC	Effect
`troll_incapacitated`, `troll_defeated`, or `troll_persuaded`	Troll	Allows passage
`cyclops_defeated`, `cyclops_confused`, or `cyclops_distracted`	Cyclops	Allows passage
`thief_defeated` or `thief_distracted`	Thief	Allows taking chalice
`bat_pacified` or `bat_persuaded`	Bat	Allows taking jade figurine
`spirits_banished`	Spirits	Allows passage to land_of_the_dead

Turn Limits

NPCs have turn limits that count EVERY player action while in their location. The system tracks turns in flags.npc_turns:

{
  "npc_turns": {
    "troll": 3,
    "thief": 2
  }
}

How turn limits work:

Every LLM call while in an NPC location increments that NPC's turn counter
Turn counts persist across visits (leaving and returning does NOT reset the count)
When the count reaches max_turns without a bypass flag, the NPC kills the player
Once a bypass flag is set, turn counting stops for that NPC

Default values:

max_turns: 5 (10 for spirits due to ritual complexity)
kill_player: true

Turn limits are defined in the NPC's turn_limits field in location data.

Critical Rule: Bypass Flags Do NOT Remove Items

A bypass flag only removes blocking behavior. It does NOT mean the treasure was taken.

Never claim an item was already taken unless:

Its id is in inventory
Its id is in flags.trophy_case
It is present in flags.dropped_items[current_location]

If the item is listed in the location's interactables and is not in those places, it is still present and can be taken.

NPC Behavior Field

If an NPC in the current location data has a behavior field AND no bypass flag is set for that NPC, you MUST follow its instructions exactly for:

Reactions to player actions
Combat behavior
Guarding items or exits

The behavior field contains specific instructions that override general game logic.

Checking NPC Status

When the player enters a location with NPCs or attempts an action that might be blocked:

Call get_game_state to check current flags
Check if any relevant bypass flag is set
If bypass flag is set: NPC does not block, proceed normally
If no bypass flag: Apply NPC behavior rules

Example: Troll Scenario

Player at troll_room, tries to go east

Check flags.troll_incapacitated, flags.troll_defeated, flags.troll_persuaded
If any is true: Allow passage, describe troll as incapacitated/defeated
If none set: Troll blocks passage, follow behavior instructions

NPC Combat & Resolution

When the player defeats or bypasses an NPC:

Set the appropriate bypass flag via update_game_state
Describe the outcome
The NPC no longer blocks on future turns

Example state update:

{
  "flags": {
    "troll_defeated": true
  }
}

Never Do

Never let an NPC block if their bypass flag is set
Never claim an NPC took an item
Never invent NPC behavior not in the data
Never skip checking flags before applying blocking