This page explains how AI agents find and invoke skills in the Superpowers system: the platform-specific tools used to load skills, the superpowers:skill-name namespace format, how natural language in description frontmatter fields drives trigger matching, and the announcement convention agents follow after invoking a skill.
For the mandatory protocol governing when agents check for skills, see page 3.2. For how the three-tier priority system resolves conflicts between project, personal, and superpowers skills, see page 3.4. For low-level implementation details on directory scanning and path resolution, see page 4.5. </old_str> <new_str>
This page explains how AI agents find and invoke skills in the Superpowers system: the platform-specific tools used to load skills, the superpowers:skill-name namespace format, how natural language in description frontmatter fields drives trigger matching, and the announcement convention agents follow after invoking a skill.
For the mandatory protocol governing when agents check for skills, see page 3.2. For how the three-tier priority system resolves conflicts between project, personal, and superpowers skills, see page 3.4. For low-level implementation details on directory scanning and path resolution, see page 4.5.
Skills are discovered through two complementary mechanisms: bootstrap context injection at session start and on-demand discovery through platform-specific tools.
At session start, the session-start.sh hook injects the using-superpowers skill content directly into the agent's context. This provides immediate awareness of the skills system without requiring an explicit skill load operation.
Bootstrap Injection Flow from Session Start to Agent Context
The bootstrap ensures the agent knows:
Sources: hooks/session-start.sh RELEASE-NOTES.md25-27 RELEASE-NOTES.md333-336
When an agent needs to find or invoke a specific skill, it uses the platform-native Skill (or skill) tool. Invoking the tool by name loads the full SKILL.md content into the agent's context in a single operation — no separate file read is required.
| Platform | Tool Name | Invocation Example |
|---|---|---|
| Claude Code | Skill | Skill("superpowers:brainstorming") |
| Cursor | Skill | Skill("superpowers:brainstorming") |
| OpenCode | skill | skill load superpowers/brainstorming |
| Codex | Native skill discovery | Skills resolved from ~/.agents/skills/superpowers/ |
Prior to v3.2.3, agents used the Read tool on raw SKILL.md file paths. The change to the Skill tool was explicit and intentional — the Skill tool is the only correct mechanism for invoking skills in Claude Code (RELEASE-NOTES.md406-418). Attempting to read skill files with Read directly is an anti-pattern.
All platforms share the same directory scanning logic in lib/skills-core.js, but expose it through different tool interfaces.
Sources: RELEASE-NOTES.md406-418 RELEASE-NOTES.md179-183 skills/using-superpowers/SKILL.md14-18
Skills are identified by their directory name and an optional superpowers: namespace prefix. The naming system enables explicit tier selection and priority override.
Each skill has three consistent identifiers that must agree:
| Identifier | Format | Example |
|---|---|---|
| Directory name | lowercase kebab-case | skills/brainstorming/ |
Frontmatter name: field | matches directory name | name: brainstorming |
| Prefixed reference | superpowers: + name | superpowers:brainstorming |
The superpowers: prefix was standardized in v3.2.0 (RELEASE-NOTES.md470-477). All cross-skill references inside SKILL.md files use the prefixed form (e.g., superpowers:test-driven-development) to explicitly pin the superpowers tier.
Skill name components and resolution paths
Sources: RELEASE-NOTES.md470-477 RELEASE-NOTES.md383-386
resolveSkillPath()The resolveSkillPath() function in lib/skills-core.js implements namespace-aware resolution:
superpowers: prefix — strip the prefix, skip personal/project tiers, resolve directly from the superpowers skills directory.resolveSkillPath() logic in lib/skills-core.js
The returned sourceType field indicates which tier satisfied the request. A null return means no skill matched; the agent may broaden the search or ask for clarification.
Sources: lib/skills-core.js100-140 RELEASE-NOTES.md470-477
Skills are not invoked by exact command names alone. The agent reads description frontmatter fields and matches them against the user's natural language intent.
description Field as a TriggerEvery SKILL.md begins with YAML frontmatter containing a description field. This field is written specifically to match the conditions under which the skill should fire — not to summarize the skill's workflow.
---
name: brainstorming
description: "You MUST use this before any creative work - creating features,
building components, adding functionality, or modifying behavior."
---
The convention is: start with "Use when..." or a direct imperative describing trigger conditions (skills/brainstorming/SKILL.md1-4). The description should cover relevant error messages, symptoms, and intent keywords — not describe the workflow steps. Summarizing the workflow in the description causes agents to skip reading the skill body (documented in RELEASE-NOTES.md as "The Description Trap", RELEASE-NOTES.md271-276).
| User Request | Matching description Keywords | Resolved Skill |
|---|---|---|
| "Let's build a new feature" | "creative work", "adding functionality" | brainstorming |
| "This test keeps failing" | "systematic investigation", "root cause" | systematic-debugging |
| "I want to implement this plan" | "implementing planned work", "batch execution" | executing-plans |
| "Can we review this code?" | "code review", "completed step" | requesting-code-review |
Matching is done by the platform's Skill tool or findSkillsInDir() in lib/skills-core.js, which returns a ranked list of candidates with their names and descriptions. The agent then selects and invokes the best match.
Sources: skills/brainstorming/SKILL.md1-4 skills/using-superpowers/SKILL.md1-4 RELEASE-NOTES.md271-276 lib/skills-core.js54-97
After invoking the Skill tool and loading a skill's content, the agent must announce the invocation before executing the workflow. This is specified in skills/using-superpowers/SKILL.md as a mandatory step in the flowchart:
Announce: "Using [skill] to [purpose]"
This announcement appears immediately after the Invoke Skill tool step and before any checklist creation or skill execution (skills/using-superpowers/SKILL.md26-55).
Skill invocation flow from using-superpowers/SKILL.md
The announcement serves two purposes:
If a skill contains a numbered checklist, the agent converts each item into a TodoWrite task before proceeding. This ensures the full workflow is tracked and not skipped.
Sources: skills/using-superpowers/SKILL.md26-55
When an agent receives a user request, it follows the mandatory protocol defined in using-superpowers/SKILL.md.
Complete discovery-to-invocation sequence
Sources: skills/using-superpowers/SKILL.md26-55 lib/skills-core.js54-140
Agents discover skills through description field matching. Common patterns:
| User Intent | Key description Keywords | Resolved Skill |
|---|---|---|
| "Let's build a new feature" | "creative work", "adding functionality" | superpowers:brainstorming |
| "This test is failing" | "root cause", "systematic investigation" | superpowers:systematic-debugging |
| "Let's implement the plan" | "implementing planned work" | superpowers:executing-plans |
| "Starting a new session" | "starting any conversation" | superpowers:using-superpowers |
The description field is explicitly optimized for this matching pattern. See page 8.4 for authoring guidance.
Sources: RELEASE-NOTES.md271-276 skills/using-superpowers/SKILL.md1-4
Each platform provides native tools for skill invocation, but all delegate to shared discovery logic in lib/skills-core.js.
Skill ToolThe Skill tool reads and loads skills in one operation. Content is injected directly into the agent's context — no separate file read needed.
| Property | Value |
|---|---|
| Tool name | Skill |
| Input | Skill name: "superpowers:brainstorming" or "brainstorming" |
| Output | Full SKILL.md content injected into context |
| Anti-pattern | Using the Read tool on skill file paths directly |
Sources: RELEASE-NOTES.md179-183 RELEASE-NOTES.md406-418
skill ToolOpenCode uses its native skill tool. Skills must be symlinked to ~/.config/opencode/skills/superpowers/.
| Operation | Example |
|---|---|
| List available skills | skill list |
| Load a specific skill | skill load superpowers/brainstorming |
The plugin registers via experimental.chat.system.transform in .opencode/plugins/superpowers.js to inject bootstrap context at session start.
Sources: RELEASE-NOTES.md119-129 RELEASE-NOTES.md139-146
Codex discovers skills through its native skill system by scanning ~/.agents/skills/. The superpowers skills directory is symlinked there:
~/.agents/skills/superpowers/ → symlink → ~/path/to/superpowers/skills/
No explicit tool invocation is required. Skills activate when their name matches a request or their description matches the session context. The superpowers:bootstrap pseudo-skill loaded from using-superpowers also activates via the using-superpowers direction in AGENTS.md.
Sources: RELEASE-NOTES.md31-38 RELEASE-NOTES.md56-59
Skill content uses tool names from the Claude Code API. The bootstrap context maps these to platform equivalents so skills authored for one platform run on others:
Tool reference mapping across platforms
Sources: RELEASE-NOTES.md383-390
Skill discovery relies on YAML frontmatter parsing to extract metadata without reading full skill content.
Each SKILL.md file begins with frontmatter:
The extractFrontmatter() function in skills-core.js parses this metadata.
extractFrontmatter() FunctionextractFrontmatter() Parsing Logic
Sources: lib/skills-core.js6-52
findSkillsInDir() FunctionDirectory scanning recursively discovers all skills:
findSkillsInDir() Recursive Directory Scanning
The function builds a complete catalog of available skills with their metadata and source tier.
Sources: lib/skills-core.js54-97
The discovery system implements several optimizations to minimize latency:
findSkillsInDir() limits recursion to maxDepth = 3 by default, preventing deep directory tree traversal.
| Depth | Directory Level | Example |
|---|---|---|
| 0 | Skills root | skills/ |
| 1 | Skill directories | skills/brainstorming/ |
| 2 | Skill subdirectories | skills/subagent-driven-development/templates/ |
| 3 | Max depth | (stops here) |
Sources: lib/skills-core.js62
Discovery reads only frontmatter, not full skill content. The extractFrontmatter() function stops parsing after the closing --- delimiter.
Content avoided during discovery:
This reduces I/O and parsing overhead by ~90% compared to full file reads.
Sources: lib/skills-core.js16-52
The using-superpowers skill content is cached in the agent's context via bootstrap injection, avoiding repeated file reads for the most frequently accessed skill.
Sources: RELEASE-NOTES.md333-336
The discovery system handles missing skills and malformed frontmatter gracefully.
When resolveSkillPath() returns null:
Sources: lib/skills-core.js139
extractFrontmatter() returns empty strings for missing fields:
Skills with empty names default to their directory name in findSkillsInDir():
Sources: lib/skills-core.js50 lib/skills-core.js83
The checkForUpdates() function includes timeout protection (3 seconds) and error handling:
Sources: lib/skills-core.js148-170
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.