Superpowers Skills Framework: Source Read,... | Support

Superpowers Skills Framework: Source Read, Control-Plane Lessons, and Adoption Boundaries

Agent skills look harmless when they are just markdown files in a folder.

That is the wrong mental model. Once a skill has trigger metadata, harness-specific manifests, hooks, plugin loaders, tests, and review rules, it is no longer only prose. It is behavior-shaping source material. It can change when an agent plans, when it asks for review, how it splits work, what it considers done, and which public actions it thinks are allowed.

That is why Superpowers is worth reading. Not because Starkslab has validated it as an installable tool. Not because stars prove quality. Not because "agent skills framework" is a category that deserves another vague roundup. Superpowers is useful because its source shows what a serious skills package looks like when it treats agent procedure as a control-plane asset.

Short version: Superpowers is not just a prompt-folder repo. The saved Starkslab source reads found skill files, trigger metadata, harness integration surfaces, hooks, scripts, tests, release notes, and contribution gates. That is enough to compare its skills-framework discipline against Starkslab's AI Agent Tools lane. It is not enough to recommend adoption, claim runtime enforcement, or say cross-harness behavior is equivalent.

Proof state: this note is based on the May 17 and May 18 Starkslab source-read artifacts for obra/superpowers. Those reads inspected the public repository, representative skills/<skill-name>/SKILL.md files, root agent instructions, Codex/Claude/Cursor/Gemini/OpenCode-facing surfaces, hooks, scripts, tests, release notes, and contribution guidance. They recorded main at commit f2cbfbefebbfef77321e4c9abc9e949826bea9d7 and visible release v5.1.0 as of the source-read window.

What was not run: no clone, install, package command, marketplace install, hook execution, Codex/Claude/Cursor/Gemini/OpenCode runtime test, benchmark, package registry validation, Search Console fetch, or Datafast fetch happened for this note.

Blocked claims: this note does not claim that Starkslab recommends Superpowers, that Superpowers is safe to install, that it is production-ready, that it is the best skills framework, that it is broadly adopted, that runtime auto-trigger behavior works in any harness, that TDD or review gates are enforced at runtime, or that marketplace/package state matches the committed repository.

This note covers:

what Superpowers is from the saved source reads;
why agent skills should be treated as control-plane assets, not prompt folders;
what Superpowers gets right about trigger and gate discipline;
where the evidence stops;
what instruction-supply-chain risks remain;
what Starkslab would steal, ignore, and test next.

If you want the broader operator-owned layer around skills, hooks, MCP, config, and review gates, read What Is a Coding-Agent Control Plane?. If you want the harness-level reason cross-runtime claims need caution, read The Coding Agent Harness Layer. If you want Starkslab's source-reading posture first, start with I Read OpenClaw's Source Code.

What Is Superpowers From The Source?

From the saved source reads, Superpowers is a skills and software-development methodology package for coding agents.

The core unit is a directory under skills/<skill-name>/ with a SKILL.md file. Representative inspected surfaces included skills/using-superpowers/SKILL.md, skills/subagent-driven-development/SKILL.md, skills/brainstorming/SKILL.md, skills/writing-plans/SKILL.md, skills/test-driven-development/SKILL.md, skills/requesting-code-review/SKILL.md, skills/verification-before-completion/SKILL.md, and skills/finishing-a-development-branch/SKILL.md.

Those files are not isolated from the rest of the repo. The source reads also found harness-facing and behavior-loading surfaces:

.codex-plugin/plugin.json
.claude-plugin/plugin.json
.cursor-plugin/plugin.json
gemini-extension.json
root AGENTS.md, CLAUDE.md, and GEMINI.md
hooks/hooks.json
hooks/session-start
.opencode/plugins/superpowers.js
scripts for versioning and plugin sync
tests and release notes
contribution and PR guidance

That combination matters. A repo with only advice prose is one thing. A repo with skill trigger metadata, bootstrap instructions, hooks, plugins, tests, and contribution gates is closer to an instruction supply chain.

The correct Starkslab read is narrow: Superpowers has a serious source surface for agent-skill methodology. It is evidence that skills frameworks are becoming real infrastructure. It is not runtime validation.

Are Agent Skills Prompt Folders Or Control-Plane Assets?

A prompt folder stores reusable text. A control-plane asset changes the conditions under which work happens.

An agent skill starts crossing that line when it has:

a named trigger condition;
an expected behavior;
examples or procedures that change execution;
validation or review rules;
integration surfaces that load it into a runtime;
stop conditions or public-action boundaries.

Superpowers shows that line clearly. The saved source reads found YAML-style name and description metadata in inspected skill files. The description acts as the trigger surface: when should this skill apply? The body then carries the operating procedure, review expectations, examples, and constraints.

That makes the operator question sharper. The issue is not whether a skill is "well written." The issue is: when does it load, what behavior does it change, what tools or hooks does it influence, how do you test it, and who reviews the result?

A useful mental model is:

SKILL.md -> trigger description -> loader / hook / plugin -> agent behavior -> review gate

Each arrow adds power. Each arrow also adds risk.

This is why Starkslab treats reusable skills like source material rather than content assets. The broader category sits inside the same operator layer as skills, MCP servers, config, hooks, memory, and review queues. For that bigger map, the next useful read is the coding-agent control-plane note, not an install tutorial.

What Superpowers Gets Right About Trigger And Gate Discipline

The strongest reusable pattern in Superpowers is not one specific skill. It is the discipline of named gates.

The saved source reads found workflow gates around brainstorming, writing plans, TDD, subagent-driven development, dispatching parallel agents, requesting code review, verifying before completion, finishing a branch, and writing new skills. That is operator-grade material because it turns vague agent behavior into named procedures with expected artifacts.

The pattern maps cleanly to Starkslab's own worker-brain contract:

Superpowers pattern	Operator lesson
`description` trigger metadata	Say when the behavior should load.
`using-superpowers` bootstrap discipline	Make reusable procedure discoverable early.
brainstorming and planning gates	Do not let implementation start from ambiguity.
TDD and verification skills	Treat evidence as part of completion, not garnish.
subagent-driven development	Split work only when ownership and review are explicit.
contribution and PR guidance	Put public/reputation gates where agents can see them.

This is exactly the kind of discipline Starkslab wants in the AI Agent Tools cluster. The useful search-facing lesson is not "Superpowers is the winner." The useful lesson is that agent skills become serious when they define triggers, artifacts, tests, review, and public boundaries.

The Build AI Agent support angle is also real, but secondary. If a reader wants the workflow version of these ideas, AI Coding Agent Workflow is the better next step. That page handles task contracts, delegation, verification, and review as a practical operating loop. This page should stay narrower: source-read comparison and adoption boundaries for the Superpowers skills framework.

Where The Evidence Stops

Committed source proves framework shape. It does not prove installed behavior.

The source reads support claims like:

Superpowers has source-visible skills/<skill-name>/SKILL.md units.
Inspected skills use trigger-style metadata and "use when" language.
The repo includes Codex, Claude, Cursor, Gemini, and OpenCode-facing surfaces.
The methodology encodes planning, TDD, subagent, review, verification, and closeout gates.
The project has tests, release notes, and contribution guidance.

The source reads do not support claims like:

"Superpowers is safe to install in a Starkslab environment."
"Superpowers enforces TDD at runtime."
"Superpowers behaves the same across Codex, Claude, Cursor, Gemini, and OpenCode."
"Marketplace or package state matches the committed repository."
"Starkslab recommends adopting Superpowers."

That distinction is not editorial caution. It is the whole page job.

Cross-harness support is a good example. The repo contains multiple harness surfaces, which is source evidence of broad integration intent. But the source reads did not run those harnesses. A manifest is not parity. A hook file is not a successful session. A test directory is not proof that every installed agent will obey the workflow under pressure.

That is why this note should feed a reader's inspection discipline, not their install decision.

What Are The Instruction-Supply-Chain Risks?

Superpowers is useful because it can change agent behavior. That also makes it an instruction-supply-chain boundary.

The saved source reads flagged several mutation-capable or behavior-loading surfaces:

Surface	What it can affect	What Starkslab would inspect before adoption
Hook files	Session bootstrap and injected instructions	Before/after hook registration, content injected, failure behavior
Plugin and extension manifests	Runtime loading and skill discovery	Exact files installed, config entries, version pins, rollback path
OpenCode plugin code	Runtime behavior and first-message injection	Config mutation, cache state, plugin scope, uninstall behavior
Install/update docs	Symlinks, plugin entries, caches, local config	Disposable before/after filesystem audit
Scripts	Version sync, repo scans, clone/commit/push paths	Whether commands are inert unless explicitly invoked
Contribution workflows	Branch, PR, and public reputation behavior	Human gate remains above every public action

None of this makes Superpowers bad. It makes it real.

Behavior-changing tools deserve behavior-level audits. The same principle sits behind Starkslab's Agent Tool Radar methodology: repository signals and source reads are research leads, not recommendations. A good radar entry tells you what to inspect next. It does not outsource judgment.

What Starkslab Would Steal

Starkslab should steal the discipline, not the whole methodology blindly.

The useful parts are clear:

treat skill files as behavior-changing code;
put compact trigger logic in metadata;
put procedure, examples, validation, and stop rules in the skill body;
require artifacts before execution: design, plan, tests, review, verification, closeout;
give subagents explicit ownership, output expectations, and review sequence;
pressure-test skill changes instead of only proofreading them;
keep public and reputation gates visible inside agent-facing instructions;
separate source-read claims from runtime, install, and adoption claims.

The strongest transfer into Starkslab is worker-brain design. A Symphony ticket already names lane, action, brain profile, context pack, target artifact, validation, landing mode, review owner, constraints, and out-of-scope boundaries. Superpowers reinforces the same idea from another angle: reusable agent behavior needs explicit triggers and reviewable artifacts.

That does not mean every Starkslab task should become a software-development branch flow. Starkslab also moves research memos, keyword briefs, outlines, drafts, source patches, SEO evidence, distribution artifacts, and operator-system patches. The lesson is gate discipline, not coding-methodology maximalism.

What Starkslab Would Ignore

Starkslab should ignore the easy hype paths.

Star count is not quality proof. "Works across many harnesses" is not parity proof. TDD language is not runtime enforcement proof. A skill package being useful does not mean it belongs in a live OpenClaw, Hermes, or Symphony environment without a disposable audit.

Starkslab should also ignore any convenience path that weakens public gates. Branch finishing, PR creation, contribution helpers, publishing, posting, outreach, Request Indexing, credentials, payments, and deploys stay behind Starkslab's own approval boundaries. Upstream docs can be thoughtful and still sit below local operating rules.

The practical verdict is:

Watch Superpowers as strong AI Agent Tools proof stock.
Learn from its trigger language, skill shape, methodology gates, subagent boundaries, and public-contribution discipline.
Test it only in a disposable environment if adoption confidence becomes the goal.

Do not install it into a live operator environment from this note. Do not call it production-ready from a source read. Do not turn a skills-framework comparison into a recommendation just because the source is interesting.

What Would A Disposable Runtime Audit Need To Prove?

Adoption confidence would require a separate runtime audit.

That audit should be boring and explicit:

use one throwaway harness with no credentials and no deployable Starkslab source;
record before/after files, symlinks, plugin entries, hooks, caches, and config;
verify whether using-superpowers actually loads automatically;
run a clean-session task and see whether design or planning triggers before implementation;
run the project's fast tests in an isolated clone;
check update and rollback behavior;
compare Codex plugin behavior against .codex-plugin/plugin.json;
confirm public, branch, PR, and contribution flows remain inert unless explicitly invoked.

Until that exists, the correct ending is not adopt.

The correct ending is watch, learn, test.

What Should Readers Do Next?

If you are evaluating the Superpowers skills framework, treat this page as a source-read starting point, not an adoption recommendation.

Use it to separate three questions:

what the committed source shows;
what the runtime still needs to prove;
what boundaries an operator should keep before installing behavior-changing agent instructions.

The next useful move is a disposable runtime audit with no credentials, no deployable source, and a before/after filesystem record. Until that audit exists, the conservative Starkslab position is watch, learn, and test.

For the broader Starkslab map around agent skills, control planes, source reads, and open-source research signals, read these next:

Target route	Reader job
`/notes/coding-agent-control-plane-skills-mcp-config-safety-gates`	Adjacent depth for the broader skills, MCP, config, hooks, and safety-gate layer.
`/notes/coding-agent-harness-layer`	Prerequisite/adjacent depth for why cross-harness files do not prove runtime parity.
`/notes/i-read-openclaws-source-code`	Source-reading posture and proof-boundary precedent.
`/notes/ai-coding-agent-workflow`	Next-step workflow context for design, planning, TDD, review, and closeout loops.
`/notes/agent-tool-radar-methodology-open-source-ai-agent-tools`	Lane continuation for treating source signals as research leads, not recommendations.