Skip to content

docs: clarify Codex skill loading in using-superpowers #1506

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
caokaizz wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: clarify Codex skill loading in using-superpowers #1506

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 12 additions & 10 deletions skills/using-superpowers/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: using-superpowers
description: Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions
description: Use when starting any conversation and deciding which superpowers skills apply in the current environment
---

<SUBAGENT-STOP>
Expand All @@ -27,13 +27,15 @@ If CLAUDE.md, GEMINI.md, or AGENTS.md says "don't use TDD" and a skill says "alw

## How to Access Skills

**In Claude Code:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you—follow it directly. Never use the Read tool on skill files.
**In Claude Code:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you—follow it directly.

**In Codex:** Skills load through native discovery. Read only the specific `SKILL.md` files and supporting references you need, then follow them directly. See `references/codex-tools.md` for tool mapping.

**In Copilot CLI:** Use the `skill` tool. Skills are auto-discovered from installed plugins. The `skill` tool works the same as Claude Code's `Skill` tool.

**In Gemini CLI:** Skills activate via the `activate_skill` tool. Gemini loads skill metadata at session start and activates the full content on demand.

**In other environments:** Check your platform's documentation for how skills are loaded.
**In other environments:** Check your platform's documentation for how skills are loaded, then adapt the workflow to that platform's native tools.

## Platform Adaptation

Expand All @@ -43,7 +45,7 @@ Skills use Claude Code tool names. Non-CC platforms: see `references/copilot-too

## The Rule

**Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means that you should invoke the skill to check. If an invoked skill turns out to be wrong for the situation, you don't need to use it.
**Load or invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means that you should check. If a loaded skill turns out to be wrong for the situation, you don't need to use it.

```dot
digraph skill_flow {
Expand All @@ -52,10 +54,10 @@ digraph skill_flow {
"Already brainstormed?" [shape=diamond];
"Invoke brainstorming skill" [shape=box];
"Might any skill apply?" [shape=diamond];
"Invoke Skill tool" [shape=box];
"Load skill via platform mechanism" [shape=box];
"Announce: 'Using [skill] to [purpose]'" [shape=box];
"Has checklist?" [shape=diamond];
"Create TodoWrite todo per item" [shape=box];
"Track checklist in native task tool" [shape=box];
"Follow skill exactly" [shape=box];
"Respond (including clarifications)" [shape=doublecircle];

Expand All @@ -65,13 +67,13 @@ digraph skill_flow {
"Invoke brainstorming skill" -> "Might any skill apply?";

"User message received" -> "Might any skill apply?";
"Might any skill apply?" -> "Invoke Skill tool" [label="yes, even 1%"];
"Might any skill apply?" -> "Load skill via platform mechanism" [label="yes, even 1%"];
"Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"];
"Invoke Skill tool" -> "Announce: 'Using [skill] to [purpose]'";
"Load skill via platform mechanism" -> "Announce: 'Using [skill] to [purpose]'";
"Announce: 'Using [skill] to [purpose]'" -> "Has checklist?";
"Has checklist?" -> "Create TodoWrite todo per item" [label="yes"];
"Has checklist?" -> "Track checklist in native task tool" [label="yes"];
"Has checklist?" -> "Follow skill exactly" [label="no"];
"Create TodoWrite todo per item" -> "Follow skill exactly";
"Track checklist in native task tool" -> "Follow skill exactly";
}
```

Expand Down