How Skills Are Triggered Automatically in the Superpowers Plugin

The Superpowers plugin automatically triggers skills by loading YAML skill manifests at session startup and registering a pre-task hook that intercepts every agent operation to match and execute relevant skills based on contextual triggers without explicit user commands.

The Superpowers plugin in the openai/plugins repository implements a mandatory workflow system where skills are triggered automatically based on contextual matching rather than manual invocation. According to the source code in plugins/superpowers/README.md, this ensures that your coding agent adheres to defined methodologies seamlessly during every phase of operation, from brainstorming to sub-agent development.

The Automatic Trigger Mechanism

The automatic skill execution pipeline operates through four distinct stages that ensure zero manual intervention while maintaining strict workflow adherence.

Bootstrap Loading at Session Start

When an agent session initializes, the Superpowers bootstrap loads every skill definition stored in the plugins/superpowers/skills/ directory. As documented in plugins/superpowers/README.md, the system scans for YAML and JSON manifest files and ingests their trigger criteria into memory. For environments supporting session-startup hooks (such as Pi), the plugin injects the using-superpowers bootstrap both at session start and immediately after compaction to guarantee persistent skill availability.

Pre-Task Hook Registration

After loading skill definitions, the bootstrap registers a pre-task hook that intercepts every agent-initiated operation. According to lines 77-78 of plugins/superpowers/README.md, "The agent checks for relevant skills before any task. Mandatory workflows, not suggestions." This hook executes before brainstorming sessions, git worktree creation, plan writing, or sub-agent operations, ensuring skills evaluate context before the agent proceeds.

Context Matching and Skill Selection

The pre-task hook inspects the current task context—including phases like writing-plans, brainstorming, or subagent-driven-development—and matches these against the trigger arrays defined in each skill manifest. When the current phase aligns with a skill's trigger criteria, the system flags that skill for immediate execution.

Automatic Skill Execution

Once matched, the skill runs automatically before the agent's primary task completes. The agent proceeds only after the skill finishes execution, ensuring the workflow remains aligned with the defined methodology. This process requires no explicit /skill command or user intervention, as emphasized in lines 43-44 of the README: "because the skills trigger automatically, you don't need to do anything special. Your coding agent just has Superpowers."

Defining Auto-Triggered Skills

Skills specify their automatic triggers within YAML manifests located at plugins/superpowers/skills/<skill-name>/SKILL.md. The trigger field accepts an array of task phases that activate the skill when matched.

# plugins/superpowers/skills/example-skill/SKILL.md

name: example-skill
trigger:
  - writing-plans      # runs automatically when writing-plan phase starts

description: Demonstrates an auto-triggered skill
steps:
  - run: echo "Example skill executed"

With this file present in the skills directory, the bootstrap loads it at session initialization. When the agent enters the writing-plans phase, the pre-task hook detects the match and executes the skill automatically.

Implementation Architecture

The automatic triggering system relies on a lightweight execution loop that maintains persistent context awareness throughout the session.

// Simplified bootstrap logic from the Superpowers plugin
function loadAllSkills() {
  const skillFiles = globSync('plugins/superpowers/skills/**/SKILL.md');
  return skillFiles.map(readSkillManifest);
}

function preTaskHook(context) {
  const skills = loadAllSkills();
  for (const skill of skills) {
    if (skill.trigger.includes(context.currentPhase)) {
      runSkill(skill);
    }
  }
}

// Register hook once per session
agent.on('beforeTask', preTaskHook);

This architecture ensures that skill definitions remain declarative while the bootstrap handles imperative execution logic. The separation between manifest configuration and hook registration allows developers to add new automatic behaviors by simply creating new skill directories without modifying core plugin code.

Summary

• Bootstrap initialization loads all skill manifests from plugins/superpowers/skills/**/SKILL.md at session start and after compaction.
• Pre-task hooks intercept every agent operation to enforce mandatory workflow checks before task execution begins.
• Context matching compares the current task phase against skill trigger arrays to determine automatic execution eligibility.
• Zero configuration is required beyond creating skill manifests; the system handles invocation automatically without explicit commands.

Frequently Asked Questions

How does the Superpowers plugin determine which skill to trigger automatically?

The plugin compares the current task context—such as writing-plans or brainstorming—against the trigger array defined in each skill's manifest file. When a match occurs between the active phase and a skill's specified triggers, that skill executes automatically before the primary task proceeds.

What is the difference between mandatory workflows and suggestions in the Superpowers plugin?

According to plugins/superpowers/README.md, skills represent mandatory workflows rather than optional suggestions. The pre-task hook enforces execution before the agent completes any operation, ensuring strict adherence to defined methodologies rather than merely recommending best practices that the agent might ignore.

Where are automatic skill triggers defined in the Superpowers plugin?

Triggers are defined in skill manifest files located at plugins/superpowers/skills/<skill-name>/SKILL.md. Each manifest contains a trigger field listing the task phases—such as subagent-driven-development—that automatically activate that specific skill when encountered during the agent session.

Do automatic skills persist after session compaction in the Superpowers plugin?

Yes. For environments supporting session hooks (such as Pi), the plugin re-injects the using-superpowers bootstrap both at initial session startup and immediately following compaction events. This ensures the pre-task hook and skill library remain active and available throughout the entire session lifecycle.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}