skill
swd-skills
Software development skills for Claude Code, Codex CLI, and Agent Plugins clients: deep planning, root-cause analysis, rigorous PR review, spec-aware rebasing, agent-oriented repo docs
Set up
Skills are installed by placing their folder where your agent loads skills.
The download comes from github.com/korya/swd-skills itself, not from our server, so what you get is exactly what its author published.
Install instructions come from the README
README
synced Oct 27, 2026swd — software development skills
A plugin of skills that covers the full development cycle: spec, plan, build, submit, review, test. Nine are shipped, one is planned. It runs on Claude Code, Codex CLI, and any Agent Plugins client.
| Skill | What it does | When it triggers |
|---|---|---|
| /spec | Turns a fuzzy feature request into a reviewable product spec — goals, non-goals, testable acceptance criteria with stable IDs, invariants — that later skills cite by path and ID. | "/spec", "spec this out", "write a product spec", "turn this idea into requirements". |
| /blueprint | Validation-first planning: tests every load-bearing assumption against reality, cross-checks specs, architecture, and conventions, then delivers a plan a human can accept or reject from its first two sections. | "/blueprint", "blueprint this", "plan this thoroughly", "deep plan" — non-trivial changes where a wrong direction would burn meaningful time. |
| /rca | Root-cause analysis: repro, timeline, evidence-backed 5-whys chain, sibling sweep, then two fix proposals (symptom vs cause) plus prevention for the whole class. | "/rca", "root cause", "5 whys", "why is this failing" — failures you want to learn from, not just patch. |
| /repo-docs | Bootstraps or extends AGENTS.md + docs/ so coding agents find the project's real conventions instead of guessing. | "document the project for coding agents", "set up agent docs", "add AGENTS.md". |
| /rebase | Spec-aware rebasing: replays commits onto a new base while keeping the original intent, invariants, and conventions intact — not just resolving conflicts. | "rebase this branch on X", "move these commits onto the new base". |
| /submit | Ships finished work as a reviewable draft PR: feature branch, well-formed Conventional Commits, pre-push checks, an honest what/why/how description that opens with the side effects a reviewer decides on, and CI gated green. | Whenever completed changes need to become a PR — instead of running git push or gh pr create yourself, once per PR in a stack; also "/submit", "open a PR", "push this up". |
| /examine | Production-risk-first holistic review of a PR, branch, or working tree; the host's built-in review is defect-first, this one also judges intent, approach, and right-sizing. | "/examine", "examine this PR", "review this PR", "review my branch", "check my PR before merge". |
| /revise | Answers PR review feedback instead of obeying it: cross-validates every claim against code, design, and specs; verdicts each finding ACCEPT/PARTIAL/REJECT/DEFER with evidence; fixes accepted items at the root; replies where the feedback lives; re-submits. | "/revise", "address the review", "here's feedback on your PR", "respond to the reviewer". |
| /e2e-test | Tests the product the way its real user uses it — browser for a web app, binary for a CLI, consumer programs for a library — black-box from the change's blast radius, reporting PASS/FAILURE/BLOCKED per case, fixing nothing. | "/e2e-test", "e2e test this", "test it in the browser", "test it as the end user", "manual e2e testing". |
| /implement | Executes an approved blueprint plan with discipline: ordered steps, tests per step, deviations amend the plan instead of improvising. | Not implemented yet — #27. |
Invocation differs per host. In Claude Code the skills fire on /blueprint, /rca, /examine, and so on, or on the natural-language triggers above. In Codex they are namespaced mentions: $swd:spec, $swd:blueprint, $swd:rca, $swd:submit, $swd:revise, $swd:examine, $swd:e2e-test, $swd:rebase, $swd:repo-docs.
Install (from GitHub)
Claude Code, in the session:
/plugin marketplace add korya/swd-skills
/plugin install swd@swd
Codex CLI, in the shell (Codex 0.145 or later):
codex plugin marketplace add korya/swd-skills
codex plugin add swd@swd
The first command points the host at github.com/korya/swd-skills as a marketplace. The second installs the swd plugin from that marketplace (<plugin>@<marketplace>).
The marketplace's internal name is swd (set in .claude-plugin/marketplace.json), which is why the install target is swd@swd even though the repo is swd-skills.
Install (local checkout, for development)
git clone https://github.com/korya/swd-skills.git
Claude Code:
/plugin marketplace add /absolute/path/to/swd-skills
/plugin install swd@swd
After editing a skill, run /reload-plugins to pick up the changes.
Codex CLI:
codex plugin marketplace add /absolute/path/to/swd-skills
codex plugin add swd@swd
Codex copies the plugin into ~/.codex/plugins/cache/, so edits to your checkout are not live. After editing a skill, re-run codex plugin add swd@swd to re-sync the copy, then start a new Codex session.
Update
Claude Code:
/plugin marketplace update swd
Codex CLI:
codex plugin marketplace upgrade swd
This refreshes the Git snapshot and the installed copy under ~/.codex/plugins/cache/. It only works for unpinned Git marketplaces. If you added the marketplace with --ref <sha>, upgrade fails. Re-add it without the ref.
Other hosts
The skills themselves are portable. A SKILL.md with YAML frontmatter is read by OpenCode, pi, Grok Build, and Muse Code too. Only the packaging is host-specific. Outside Claude Code and Codex there is no install command, so clone the repo and point your agent at skills/.
| Host | Reads |
|---|---|
| OpenCode | .opencode/skills/, .claude/skills/, .agents/skills/ (and ~/ equivalents) |
| pi | ~/.pi/agent/skills/, ~/.agents/skills/, .agents/skills/ |
| Muse Code | ~/.agents/skills/, .agents/skills/; also muse skills import --from claude |
| Grok Build | .claude/ skills, AGENTS.md, hooks, MCP |
~/.agents/skills/ is the closest thing to a vendor-neutral location. Symlinking skills/* there covers most of the table.
Layout
plugin.json # Agent Plugins 1.0.0 manifest (Codex + other AP clients)
.claude-plugin/
marketplace.json # marketplace manifest + plugin definition (Claude Code)
skills/
<name>/
SKILL.md # core: under 8 KB, read whole by every host
references/ # depth, read at the step that needs it
hooks/
hooks.json # Claude Code hooks the plugin installs with itself
guard-pr.py # PreToolUse: a bare `gh pr create` is refused unless /submit is running
assets/
writing.md # the writing rules every skill and every document it produces follow
scripts/
validate.py # manifest + budget checks CI runs on every push
prose-lint.py # mechanical check of the writing rules; CI runs it on skills and assets
tests/ # unit tests for the validator and the linter
evals/ # per-skill eval fixtures and benchmarks (skill-creator format)
LICENSE # AGPL-3.0-or-later
One hook, Claude Code only. /submit owns the PR body, the screenshots for rendered changes, and the CI gate. An agent that knows the gh pr create pattern will skip all three unless something stops it. hooks/guard-pr.py is that something.
It refuses gh pr create unless /submit has left its marker and tells the agent to invoke the skill instead. The marker is $GIT_DIR/swd-submit, set in phase 0, removed in phase 6, ignored after four hours. Hosts without hooks get the description alone, which names the same rule.
Two manifests, one package. Claude Code reads marketplace.json and ignores plugin.json. Codex resolves plugin.json first and validates its $schema strictly, so a wrong value makes codex plugin add fail outright. CI runs both hosts' native validators to keep them honest, plus scripts/validate.py for the checks neither host makes. Those are version agreement across manifests, symmetry between the marketplace and skills/, no host-specific tool named in a skill, and every SKILL.md inside Codex's prompt budget.
One writing standard. assets/writing.md holds the rules every skill and every document a skill produces follow: the claim first, short sentences, one term per concept. scripts/prose-lint.py checks the mechanical half of those rules, and CI runs it on the skills and the rule file. Each skill has an eval under evals/ that measures a rewrite against the previous version.
Development
python3 scripts/validate.py
python3 -m unittest discover -s tests
The first command validates both manifests and every skill. The second runs the unit tests for the validator and the prose linter. CI runs both, plus each host's native validator and the prose linter itself.
Skill budgets are enforced. Codex loads at most 8,000 bytes of a SKILL.md, raw file and frontmatter included, and silently drops the rest. It also shortens descriptions past 1,024 characters in the catalog (#10). The validator prints every skill's budget, warns from 90% of either limit, and fails the build past either cap. Keep the core a step skeleton and move depth into references/ files the skill reads at the step that needs them.
Bump the version in both plugin.json and .claude-plugin/marketplace.json (metadata.version and the plugin entry). The validator fails if they disagree. Codex derives the installed version from plugin.json, so a stale value stalls updates for Codex users.