How Superpowers Handles Manual Invocation of Skills: A Complete Technical Guide

Superpowers enforces manual invocation of skills through a three-layer system: skill-tool gating that requires explicit tool calls, slash-command flags that disable model auto-invocation, and OpenCode @mention syntax for user-triggered execution.

The Superpowers framework (obra/superpowers) distinguishes between automatic skill dispatch by primary agents and manual invocation of skills initiated by users. This architectural choice ensures that sensitive or complex operations require explicit user consent and oversight, preventing autonomous agents from taking unintended actions.

The Three-Layer Enforcement Strategy for Manual Skill Invocation

Superpowers implements complementary mechanisms across different interfaces to guarantee that skills are only executed when explicitly requested.

Skill-Tool Gating via the using-superpowers Skill

The core using-superpowers skill, defined in [skills/using-superpowers/SKILL.md](https://github.com/obra/superpowers/blob/main/skills/using-superpowers/SKILL.md), establishes the primary gating mechanism. Before responding to any user message, the model must invoke the Skill tool.

If a skill is relevant to the user's request, the model must call the Skill tool first to load that skill's context and checklist. If no skill applies, the model must explicitly ask the user to invoke the desired skill rather than proceeding autonomously. This creates a hard stop that prevents accidental skill execution.

Slash-Command De-activation with disable-model-invocation

For slash commands that perform high-impact operations, Superpowers disables automatic model invocation through a configuration flag. In the command definitions for [commands/brainstorm.md](https://github.com/obra/superpowers/blob/main/commands/brainstorm.md), [commands/execute-plan.md](https://github.com/obra/superpowers/blob/main/commands/execute-plan.md), and [commands/write-plan.md](https://github.com/obra/superpowers/blob/main/commands/write-plan.md), the flag disable-model-invocation: true is set.

As documented in [RELEASE-NOTES.md](https://github.com/obra/superpowers/blob/main/RELEASE-NOTES.md#L165), this flag prevents Claude and Claude-Code from invoking these commands automatically. The user must manually trigger them by typing the slash command or explicitly requesting the skill in natural language.

OpenCode @mention Syntax for Explicit User Triggers

For OpenCode users, Superpowers supports a manual @mention mechanism that requires explicit user action. The OpenCode plugin, implemented in [.opencode/plugin/superpowers.js](https://github.com/obra/superpowers/blob/main/.opencode/plugin/superpowers.js), injects a session-startup hook that explains the dual invocation paths.

According to the design plan in [docs/plans/2025-11-22-opencode-support-design.md](https://github.com/obra/superpowers/blob/main/docs/plans/2025-11-22-opencode-support-design.md), users can invoke subagents either automatically by primary agents or manually via @mention superpowers:<skill-name>. This syntax ensures the user consciously selects which skill to activate rather than having the system infer intent.

Architectural Flow of Manual Skill Invocation

The enforcement of manual invocation follows a strict decision tree that prevents accidental execution:

User message → (1) Check for applicable skills
   ├─ If a skill applies → invoke Skill tool (using-superpowers)
   │      ↓
   │   Skill content is loaded, model follows the skill checklist
   └─ If no skill applies → proceed to normal response

Slash command entered by user → command file (brainstorm/execute-plan/write-plan)
   └─ Model is blocked from auto-invoking because disable-model-invocation: true

OpenCode session start → plugin injects using-superpowers content + skill list
   └─ Users may manually trigger a subagent skill via @mention superpowers:<skill-name>

This architecture ensures that any skill not automatically required by the workflow must be explicitly called by the user through one of the three supported interfaces.

Code Examples for Manual Skill Invocation

Invoking Skills with the Skill Tool

When using Claude or Claude-Code, the model must invoke the Skill tool to load a skill's context before execution:

{
  "tool": "skill",
  "arguments": {
    "skill_name": "superpowers:brainstorming"
  }
}

Once invoked, the model receives the full content of the brainstorming skill and must complete the checklist defined within that skill before responding to the user.

Running Disabled Slash Commands

For commands with disable-model-invocation: true, the user must manually trigger execution:

/brainstorm

Because the disable-model-invocation flag is set in [commands/brainstorm.md](https://github.com/obra/superpowers/blob/main/commands/brainstorm.md), the model cannot auto-execute this command even if the user's intent seems clear. The user must type the slash command explicitly or specifically ask the model to run the command after acknowledging the manual requirement.

Using @mention in OpenCode

OpenCode users trigger skills manually through the @mention syntax:

@mention superpowers:brainstorming

The OpenCode plugin interprets this @mention and internally runs the use_skill tool, loading the requested skill only after the user has explicitly mentioned it. This prevents the AI from proactively invoking skills during the conversation flow.

Session Startup Hook Implementation

The OpenCode plugin ensures users understand manual invocation policies from the start of every session:

// Inside .opencode/plugin/superpowers.js
'session.started': async () => {
  const usingSuperpowers = await readSkill('using-superpowers')
  const skillsList = await findAllSkills()
  const toolMapping = getToolMappingInstructions()
  return { context: `${usingSuperpowers}\n\n${skillsList}\n\n${toolMapping}` }
}

This hook injects the using-superpowers skill content—which explains the manual invocation requirement—into every session context, ensuring users are aware they must explicitly trigger skills via @mention or tool calls.

Summary

Superpowers enforces manual invocation of skills through a comprehensive three-layer architecture:

• Skill-tool gating requires models to invoke the Skill tool before accessing any skill content, preventing automatic responses based on skill knowledge.
• Slash-command flags (disable-model-invocation: true) block models from auto-executing sensitive commands like /brainstorm, /execute-plan, and /write-plan.
• OpenCode @mention syntax provides a user-controlled trigger mechanism that loads skills only when explicitly requested via @mention superpowers:<skill-name>.

These mechanisms ensure that users maintain full control over when skills execute, preventing unintended autonomous actions while preserving the flexibility of manual skill invocation when needed.

Frequently Asked Questions

What is the difference between automatic and manual skill invocation in Superpowers?

Automatic skill invocation occurs when primary agents dispatch skills without explicit user commands, typically as part of a predefined workflow. Manual invocation of skills requires the user to explicitly trigger execution through one of three methods: invoking the Skill tool, typing a slash command with disable-model-invocation: true, or using the @mention syntax in OpenCode. The Superpowers framework defaults to manual invocation for all non-essential skills to ensure user oversight.

Why does Superpowers block models from invoking certain slash commands?

Superpowers sets disable-model-invocation: true in high-impact command definitions such as [commands/brainstorm.md](https://github.com/obra/superpowers/blob/main/commands/brainstorm.md), [commands/execute-plan.md](https://github.com/obra/superpowers/blob/main/commands/execute-plan.md), and [commands/write-plan.md](https://github.com/obra/superpowers/blob/main/commands/write-plan.md). This prevents the AI from autonomously executing planning, brainstorming, or execution workflows that could significantly alter project state without explicit user consent. As noted in [RELEASE-NOTES.md](https://github.com/obra/superpowers/blob/main/RELEASE-NOTES.md), this flag ensures these commands remain under strict manual control.

How do I manually invoke a skill in OpenCode?

To manually invoke a skill in OpenCode, use the @mention syntax followed by the skill identifier: @mention superpowers:<skill-name>. For example, typing @mention superpowers:brainstorming triggers the OpenCode plugin to load the brainstorming skill via its internal use_skill tool. The plugin, defined in [.opencode/plugin/superpowers.js](https://github.com/obra/superpowers/blob/main/.opencode/plugin/superpowers.js), processes the @mention only when explicitly entered by the user, preventing automatic skill loading during normal conversation flow.

Where is the manual invocation policy defined in the Superpowers codebase?

The manual invocation policy is defined across several key files in the obra/superpowers repository. The core enforcement logic resides in [skills/using-superpowers/SKILL.md](https://github.com/obra/superpowers/blob/main/skills/using-superpowers/SKILL.md), which mandates Skill tool invocation before accessing any skill content. Command-specific restrictions appear in the slash command definitions under commands/, utilizing the disable-model-invocation flag. Platform-specific implementation for OpenCode appears in [.opencode/plugin/superpowers.js](https://github.com/obra/superpowers/blob/main/.opencode/plugin/superpowers.js) and [docs/plans/2025-11-22-opencode-support-design.md](https://github.com/obra/superpowers/blob/main/docs/plans/2025-11-22-opencode-support-design.md).

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