superpowers-dsh

English | 简体中文

superpowers-dsh

Superpowers for the DeepSeek Harness: a plugin bundle that ports the core skills of obra/superpowers (the Claude-Code skills library: TDD, debugging, planning, collaboration patterns) to DSH's Cordis plugin architecture.

The plugin registers a skill provider into the host layer of the ctx.skills registry, so every agent preset's scope chain merges these skills. Skill bodies ship inside the package (skills/<name>/SKILL.md) and are located from import.meta.url — an assembly fact of the package, never user configuration.

Contents

• Install & use in your DeepSeek Harness
• DSH version compatibility
• Skills
• How it works
• Upstream sync
• Porting notes
• Adding your own skills
• License

Install & use in your DeepSeek Harness

A plugin bundle for DeepSeek Harness (DSH). Installing it registers the 15 skills below into the host skill registry, so every agent session in your profile sees them in its skill catalog and can load them with the skill tool. Skill content is synced from upstream obra/superpowers v7.0.1.

Simplest: one command

No global dsh install required. Run this from any directory:

npx @deepseek-ai/dsh plugin --profile web add github:LayneChai/superpowers-dsh

Then restart npx @deepseek-ai/dsh web (or dsh web) and refresh the browser.

Easiest: let the DeepSeek Harness agent install it

Open the DeepSeek Harness web UI, start a new conversation, and send this message:

Please install the plugin from this link: https://github.com/LayneChai/superpowers-dsh

The agent will run the install for you (dsh plugin --profile web add → restart the profile → verify the skills registered), so you never have to type a command. Afterwards you can ask it to run dsh --profile web --dump-config and confirm a superpowers-dsh row is present.

Install from npm (recommended — one command)

The package is published on npm as superpowers-dsh (synced to the npmmirror mirror for mainland China):

dsh plugin --profile web add superpowers-dsh

Use the dsh plugin form — a plain npm install superpowers-dsh installs the package as a library in the current directory but does not register it into any DeepSeek Harness profile, so the skills would never load.

Install from GitHub

# from anywhere
dsh plugin --profile web add https://github.com/LayneChai/superpowers-dsh.git

Install from a tarball or a local folder

# tarball (e.g. the release asset superpowers-dsh-0.1.0.tgz)
dsh plugin --profile web add C:\path\to\superpowers-dsh-0.1.0.tgz

# or the unpacked package folder (pnpm links it, so edits take effect on restart)
dsh plugin --profile web add C:\path\to\superpowers-dsh

Restart and verify

The bundle layer mounts at profile startup, so restart the profile (stop and re-run dsh web / npx @deepseek-ai/dsh web, then refresh the browser). To confirm the layer is composed:

dsh --profile web --dump-config     # a `superpowers-dsh` row must be present

The skills then appear in the agent skill catalog (using-superpowers is the entry-point skill) and are loadable with the skill tool.

A successful install looks like this:

Using another profile (headless / tui / custom)

Point --profile at whichever profile you run:

dsh plugin --profile headless add superpowers-dsh
dsh --profile headless --dump-config

Uninstall

dsh plugin --profile web remove superpowers-dsh
# then restart the profile again

Notes

• Installers in mainland China can set the npm mirror first — it makes dsh plugin add superpowers-dsh fast: npm config set registry https://registry.npmmirror.com
• A plugin installed from a folder or file: spec is linked, not copied: changes to that folder take effect after the next profile restart.
• Consumers need no npm account and no 2FA — installing is a plain package download.

DSH version compatibility

Bottom line: compatible with every DSH version published on npm, verified end-to-end on DSH 0.2.0-rc.2 (the current latest). No known incompatibilities.

Checked 2026-10-03. npm dist-tags: latest = next = 0.2.0-rc.2, alpha = 0.2.1-alpha.1.

Support matrix

Known compatibility notes

• No known incompatibilities. Since 0.1.7-rc.2 DSH has a plugin compatibility gate (evaluatePluginCompatibility): it only inspects the @deepseek-ai/dsh* peerDependencies a plugin declares and skips the whole bundle when a range does not match. This plugin declares no peerDependencies, so the gate never blocks it — which also means DSH does not version-check it for you, so re-run the audit below after a DSH upgrade.
• Same-name precedence is deliberate: the plugin registers at PACKAGED_SKILL_RANK = 550 while DSH's bundled root is BUNDLED_SKILL_RANK = 600 (lower wins), so your own skill wins a same-name collision. No in-box DSH skill shares a name with these.
• Windows note: the bash helpers in the skill bodies need Git for Windows (Git Bash); the Node helpers (server.cjs, render-graphs.js) run everywhere. The prose invokes bundled scripts through their interpreter (bash scripts/...), so it does not depend on Unix executable bits.
• The install method does not affect compatibility: npm, GitHub, and a linked local folder all load the same bundle declaration.

How to re-verify compatibility

One command re-runs every check above — including the real-registry mount — against the DSH you actually have installed:

node scripts/check-dsh-compat.mjs
# or point it at another node_modules, or set $DSH_NODE_MODULES
node scripts/check-dsh-compat.mjs D:\path\to\profile\node_modules

Output on this machine:

dsh SDK      : @deepseek-ai/dsh-skill 0.2.0-rc.2
mounted      : 15 skills listed and read through the real SkillRegistry
rank         : PACKAGED_SKILL_RANK=550 is below BUNDLED_SKILL_RANK=600

check-dsh-compat: OK — this plugin matches the installed DSH SDK

It checks, in order: that the SDK is present and which version it is → that the installed SDK's own type declarations still declare the provider interface this plugin implements (registerProvider, SkillProvider.list/get, SkillCandidate, SkillResourceBase, the 'custom' source bucket) → that lib/index.js really mounts into SkillRegistry and every skill reads back → the rank relationship. Any failure exits 1 and names the contract that changed.

On a machine with no DSH installed (CI, a fresh container) there is nothing to compare against, so it prints SKIPPED and exits 0 — that is "unchecked", not "failed", so a publish pipeline is never blocked by a missing local DSH. Pass an explicit directory or --require to make a missing SDK an error, or set DSH_COMPAT_REQUIRE=1 node scripts/check-dsh-compat.mjs.

The conclusion holds for the DSH version it was verified against. On a newer DSH, run the command above first: if upstream changes the skill interface it names the exact break instead of letting skills disappear quietly.

Skills

How it works

• Bundle layer — cordis.patch.yml inserts one row (- id: superpowers-dsh, name: superpowers-dsh) over the dsh-base layer. Later layers (the profile's cordis.patch.yml, --patch overlays) can still address that row by id.
• Provider — lib/index.js calls ctx.skills.registerProvider(...) with a provider that:
  • list() scans the package's skills/ directory for <name>/SKILL.md bundles and returns candidates parsed from YAML frontmatter (name, description, whenToUse).
  • get() reads the winning candidate's body on demand and returns a full skill definition with resourceBase pointing at the skill's directory, so relative references (scripts, prompt templates) resolve.
• Zero runtime dependencies — the plugin imports only Node built-ins and consumes the injected ctx.skills service interface.

Upstream sync

Currently synced upstream version: obra/superpowers v7.0.1 (recorded in package.json as dsh.superpowersUpstream).

skills/ is generated output — do not hand-edit it. The sync lives in two places; change those and re-run:

• scripts/sync-from-upstream.mjs — copies the upstream skill tree and replays every DSH adaptation. Each adaptation is an asserted string rewrite, so if upstream rewords the anchor the run fails loudly instead of silently dropping an adaptation.
• port/overrides/ — DSH-only files (using-superpowers/references/dsh-tools.md) copied over the synced tree.

# 1. Fetch the upstream release (git-over-https is blocked on some networks;
#    codeload works)
mkdir -p .upstream/superpowers
curl -L https://codeload.github.com/obra/superpowers/tar.gz/refs/tags/v7.0.1 \
  | tar -xz -C .upstream/superpowers --strip-components=1

# 2. Replay the sync
node scripts/sync-from-upstream.mjs .upstream/superpowers

# 3. Verify (provider lists every skill, frontmatter is valid, no dangling refs)
node scripts/verify-skills.mjs

# 4. Compatibility (replays the contract and the real-registry mount against
#    the DSH you have installed)
node scripts/check-dsh-compat.mjs

What this sync brought in from upstream (v7.0.1, 2026-10-21; still 15 skills, 68 → 78 files):

• brainstorming retuned after feedback (#2560 / #2571): v7.0.0's opening — offer to skip the questions, then ask a generic "the moment you wished this existed" — felt formulaic fast, so two things changed. ① It digs for context before it asks anything: pointed at an existing project, a spec, a plan, or files, it reads them before its first message and does not ask what they already answer. ② Its questions build on your answers: once you've said what you want, it plays your request back with what it found in the project and asks about the one thing still open; later questions build on your answers and say what the answer would change. The skip offer now appears only when it started on its own — invoking brainstorming by name or /brainstorming no longer offers to skip.
• The design doc can no longer be skipped: it presents two or three ways to build the thing, recommends one for you to pick, writes the design doc, and builds nothing until you approve it. Upstream measured 24 of 24 runs skipping the doc without asking before this change, 3 of 24 after.
• Three long skills were split so they survive compaction (#2563 / #2564 / #2565, from #2481): after a compaction Claude Code re-attaches each skill cut off at 20,000 characters, so anything past that point is gone for the rest of the session — one reported session lost subagent-driven-development's five-round fix limit and ran 18 fix rounds on a single task.
  • subagent-driven-development: the fix loop, final review, report handling, resuming, preflight, batching, and cannot-verify guidance move into references/ (7 new files) and are read from disk at the step that needs them. SKILL.md 32,510 → 19,470 bytes.
  • writing-skills: supporting docs, the SKILL.md template and discovery guidance, bulletproofing, and flowchart conventions move into references/ (new discovery.md, bulletproofing.md, flowcharts.md; the rest are existing files renamed into references/). 26,615 → 16,754 bytes.
  • executing-plans: drops its Example Workflow, which repeated rules stated above it. 20,454 → 18,164 bytes.
  • Upstream also added tests/skill-size/test-skill-size.sh, which fails when any SKILL.md reaches 20,000 bytes. All 15 SKILL.md files in this port are now under 20,000 bytes (the largest is subagent-driven-development at 19,470).
• Not applicable to DSH: the issue and PR templates now require who filed, what the human partner asked for, and a human-written summary under 200 words (#2569); diagnosing-superpowers adds those two sections and switches to the Bug Report template; 18 historical plan docs under docs/superpowers/plans/ were deleted. All of it lives outside skills/ and never reaches this port.

DSH adaptation: v7.0.1 renamed writing-skills/references/CLAUDE_MD_TESTING.md into references/, which brought it into the shipped tree. The whole file is scenario fixtures for testing how skill docs get discovered, and 14 of its lines send the agent to ~/.claude/skills/ — a directory that does not exist on DSH, so the fixtures would test nothing. The sync script gained a sweep transform that rewrites them all to $DSH_HOME/skills/.

The previous release (v7.0.0, 2026-10-10), kept for reference:

• brainstorming was rebuilt from scratch (#2463 / #2482 / #2483): the first message offers to skip the questions, then asks one open question about a real moment; it plays each part back in 200–300 words for correction, sizes the work in plain words once it understands (do it / agree it in chat / write a design document) with your override, and finds out which how-it-gets-made choices you want to own (platform, language, libraries, medium).
• A builder check replaces the spec-document reviewer: adds skills/brainstorming/builder-check-prompt.md (a fresh subagent reads the design as the person who'll build it and lists what it still needs to ask) and removes skills/brainstorming/spec-document-reviewer-prompt.md. One round of questions only.
• subagent-driven-development's scripts/sdd-workspace: no longer overwrites a repo's own .superpowers/sdd/.gitignore (it writes the default only when none exists), and on Windows/Git Bash plan markers stay repo-relative instead of recording a machine-specific absolute path.
• executing-plans's scripts/task-done: a test command that passes silently now records the task in the ledger as → (no output); previously the empty grep|tail exited 1 and a finished task looked unfinished.
• requesting-code-review: the base-SHA example uses cut -d' ' -f1, because Claude Code substitutes $1 in a skill body with an argument word.
• systematic-debugging: the multi-layer diagnostic example no longer prints the secret value it checks for.
• Visual companion scripts/server.cjs: fixes String.replace treating $' / $& as replacement patterns; content is now inserted literally.
• Everything else in the release is Antigravity / Hermes / Claude Code hook work, which does not apply to DSH (it has no hook system).

Porting notes

• Namespace prefixes removed: superpowers:brainstorming → brainstorming (DSH skills are addressed by bare name).
• using-superpowers now documents the DSH skill tool and points at skills/using-superpowers/references/dsh-tools.md, a full Claude-Code → DSH tool mapping (pwsh, subagent, workflow, goal, ...). Upstream's per-harness reference list (Claude Code / Codex / Gemini / Copilot / Pi / Antigravity / Hermes / Muse) collapses to the DSH file; the other references/*-tools.md files are not shipped.
• Subagent references map to DSH's subagent / subagent_fork. Upstream's named agent (superpowers:code-reviewer) does not exist here; dispatch the skill's own prompt template instead.
• Upstream's <SUBAGENT-STOP> gate is not kept: DSH subagents must follow the skills too (an implementer subagent has to run TDD).
• Cross-harness paths become DSH paths: ~/.claude/skills/ → $DSH_HOME/skills/, ~/.superpowers/... → $DSH_HOME/... (default ~/.dsh).
• diagnosing-superpowers gains DSH session-storage facts ($DSH_HOME/sessions/<cwd-slug>/session-<uuid>/session.*.jsonl.zstd, concatenated zstd frames that need frame-by-frame decompression).
• brainstorming's visual companion adds a Windows note: the Node server (scripts/server.cjs) runs everywhere; the .sh helpers are bash-only.
• After the v7.0.0 rewrite, upstream itself names the companion as a bare visual-companion.md, so this port's old rewrite of skills/brainstorming/visual-companion.md is gone (the sync script carries a NOTE; re-add it if a future release regresses to the path form).
• writing-skills/references/CLAUDE_MD_TESTING.md entered the shipped tree with v7.0.1's rename (it used to sit under examples/, which upstream never treated as shipped content). It is kept because it is the scenario suite for "how do you write skill docs so agents actually find them" — but 14 of its lines send the agent to ~/.claude/skills/, a directory that does not exist on DSH, so the fixtures would test nothing. The sync script therefore rewrites them all to $DSH_HOME/skills/ with one sweep transform. Provenance lines in the same file that describe where a framework was extracted from (~/.claude/CLAUDE.md) are left alone: those are history, not instructions.

Adding your own skills

list() discovers any skills/<kebab-name>/SKILL.md in the package — it must start with a YAML frontmatter block (name + description, optionally whenToUse). No code change needed.

Note that skills/ is generated by the upstream sync: re-running scripts/sync-from-upstream.mjs rebuilds it wholesale, so a skill dropped there directly is deleted. Two safe places:

• $DSH_HOME/skills/ (user level) or the project's .dsh/skills/ — unrelated to this package and the least effort;
• or port/overrides/<kebab-name>/SKILL.md — copied into skills/ on every sync, so it survives.

License

MIT. Skill content adapted from obra/superpowers (MIT), © Jesse Vincent and contributors.