Sublime-Skills

A skill family for agent harnesses, grouped into category directories. Each skill lives in its own directory with a SKILL.md; this file summarizes what each one does. Designed to be adopted by individuals and teams alike.

Skills

architecture-review

Reviews a codebase for architectural friction and proposes concrete refactoring opportunities — turning shallow, leaky modules into deep, testable ones. Explores the code, applies the deletion test to tell pass-through modules from ones earning their keep, presents numbered candidates, then grills the chosen one into a settled design (with a parallel sub-agent pattern for comparing alternative interfaces). Design-only — it stops at an agreed design and doesn't implement the change. Uses a project domain glossary and ADRs if they exist, but requires neither.

ss-workflow-restrict-git-commands

A baseline policy preventing destructive git operations (push, reset --hard, clean -f, branch -D, checkout . / restore .) from being run without explicit user authorization. Works via instruction — load the skill at session start (or whenever about to run git commands) and the agent commits to asking before any irreversible operation, with the exact command and consequence named in each ask. A reference Claude Code PreToolUse hook script is bundled at skills/workflow/ss-workflow-restrict-git-commands/scripts/block-dangerous-git.sh as an optional drop-in for users who want deterministic harness-level enforcement on top of the instruction layer.

ss-workflow-audit

Read-only readiness check for the Sublime-Skills framework. Verifies the install ($SUBLIME_SKILLS_HOME set + on-disk integrity, git, python3 + pyyaml), git repo state, project bootstrap state (.sublime-skills/config.yml present + validates via validate-config.sh, .sublime-skills/.gitignore covering state.json and config-local.yml, orphan state.json detection), SDD artifact directories (docs/specs/, docs/adr/), each declared convention/context file (constitution, architecture, glossary, domain, design), the memory file (config-pinned or auto-detected), and optional tooling (gh for the agile family). Emits one status table per section with PASS / FAIL / WARN / INFO / N/A rows and an overall READY / READY-WITH-WARNINGS / NOT READY verdict plus concrete next-step suggestions when anything is wrong. Never modifies any file — purely a report.

ss-workflow-generating-handoff

Generic session-handoff writer. Reads the current conversation plus light project state (current branch, recent commits, working-tree status) and writes a single self-contained markdown file at ~/.sublime-skills/handoffs/<repo-basename>/YYYY-MM-DD-<short-title>.md so a fresh agent (or human) can pick up the work in a new session. Works for any kind of in-flight work (features, bug fixes, refactors, research) with no SDD pipeline assumptions. Includes a redaction sweep (OpenAI/AWS/GitHub tokens, JWTs, private keys, URLs with embedded credentials, sensitive env-var assignments) before writing. The handoff lives outside the repo by design — never committed.

Agile (GitHub-issue workflow)

A family of skills + slash commands for driving development off GitHub issues, organized into milestones-as-sprints. Coordinator + subagent pattern: an orchestrator picks the next issue from the current milestone and dispatches implementer and polisher subagents to drive it end-to-end, ending in a local merge. Designed to be invoked autonomously (e.g. from a ralph-loop wrapper) until all milestones close — no user-approval pauses in the inner flow.

Loop wrappers live under scripts/: use ralph-loop-claude-code.sh for Claude Code, or ralph-loop-codex.sh for Codex CLI. The Codex wrapper takes the complete codex exec ... command as a quoted argument so the caller controls model, reasoning effort, and other CLI flags per run. Add --tui to either wrapper to show a minimal terminal dashboard via the bundled scripts/ralph-loop-tui renderer (see docs/RALPH-TUI.md).

All gh CLI interaction goes through the ss-agile-managing-issues reference skill, which covers the full gh issue surface plus milestone management (which gh only exposes via gh api).

ss-agile-advancing-milestones

The coordinator. Auto-selects the current milestone (lowest-numbered open one), picks the next logical issue, drives it through implementation + polish + local merge by dispatching subagents. Session scope: one issue per invocation; ends in one of three terminal states (merged-one-issue, all-milestones-closed, milestone-stuck). Designed for repeated invocation by an outer wrapper.

ss-agile-implementing-an-issue

Subagent skill. Implements a single GitHub issue on an already-checked-out feature branch — coordinator briefs with the issue body and acceptance criteria; implementer codes, commits locally, reports back. Does not pick issues, open PRs, or merge.

ss-agile-polishing-an-issue

Subagent skill. Polishes the implementer's diff — naming, comments, structure, error messages, dead-code removal — within the scope of the existing diff. Has NO veto power, NEVER blocks the merge; "no changes" is a valid outcome. Also does a lightweight acceptance-criteria sanity check and flags possibly-unmet items as info.

ss-agile-managing-issues

Pure reference skill for the gh CLI's gh issue surface plus milestone management via gh api. Loaded by autonomous agile skills; insists on non-interactive flags (--title, --body, --body-file -, --yes), never --web.

Spec-driven development

A 16-skill family for running structured, spec-driven feature development end-to-end (plus a separate 9-skill skills/project-bootstrap/ family for one-time project setup — see below). The pipeline: preflight → discover → spec → auto spec-review → ADRs → spec approval → plan → settle branch → per-task implementation + final review → optional feature testing → optional memory file → finish. Coordinated by ss-sdd-coordinator, which is the only entry point the user invokes — every other skill is loaded by the coordinator or dispatched as a subagent. Designed to be self-contained (no dependencies on external skill families), driven end-to-end in a single conversation via a gitignored state file at .sublime-skills/state.json (the data-carrier between stages, not a resume mechanism), and configurable via .sublime-skills/config.yml (context paths, branch pattern, memory file path/limit). Specs and plans live at docs/specs/NNN-short-name/; ADRs at docs/adr/.

Shared scripts at skills/spec-driven-development/framework/:

• discover-context.sh — reads project convention file paths from .sublime-skills/config.yml (the six context.*_path artifacts — CONSTITUTION.md, ARCHITECTURE.md, TESTING.md, GLOSSARY.md, DOMAIN.md, DESIGN.md — plus prior ADRs and SDD state) and verifies each file exists, so skills can load relevant context from a single source of truth.
• get-config-value.sh — reads a single scalar value from .sublime-skills/config.yml (with config-local.yml overlay applied).
• validate-config.sh — validates .sublime-skills/config.yml end-to-end (YAML shape, required keys, context-path resolution, enum values). Used by ss-bs-bootstrapping-project's fix-and-retry loop and by ss-sdd-preflight (Stage 0 of the SDD pipeline) to halt if the config is missing or invalid.
• coherence-check.sh — runs Tier 1 structural checks across the 7 bootstrap artifacts (unresolvable pointers, missing memory-file links, DOMAIN-vs-GLOSSARY vocabulary gaps, ARCHITECTURE-vs-TESTING coverage, constitution-evidence-file existence, principle contradictions, stale suggestion-pass provenance). Invoked by ss-bs-bootstrapping-project at end of run and by ss-bs-auditing-project at start of run.
• validate-spec.sh, validate-plan.sh — schema-check the artifacts each writer skill produces. Catch gross format violations (missing sections, placeholders, forbidden diagram syntax) before the artifact is committed.

ss-sdd-coordinator

Entry point for SDD runs. Thin state machine + dispatcher — knows the 12-stage pipeline, starts at Stage 0 on a fresh user invocation and picks up from current_stage on re-entry within the same conversation (no test-and-ask resume ceremony — the conversation context already says where the pipeline is). Loads phase-skills inline for interactive stages, dispatches subagents for fresh-context stages (spec review, ADR maintenance, per-task implementation, final review, testing, memory file). Holds state updates atomic at stage boundaries, never mid-stage. Surfaces user-gated optional stages (feature testing, memory-file maintenance). Critically: never tests the feature itself — if the tester subagent reports MCP unavailability, the coordinator surfaces a manual test plan rather than improvising.

ss-sdd-preflight

First stage of an SDD run. A permissive validation gate that confirms .sublime-skills/config.yml is valid, the current directory is inside a git repo, and HEAD is attached to a named branch. Dirty working trees are allowed (with a one-time warn-and-confirm) — SDD's commits are path-scoped to its own artifacts, so the user's pre-existing dirty files stay untouched. Once every check passes, creates .sublime-skills/state.json as a minimal shell (silently removing any orphan state file from a dead prior pipeline first); on abort, no state file is written. Does NOT create branches: that decision happens later at Stage 7 (ss-sdd-choosing-feature-branch), right before implementation.

ss-sdd-discovering-requirements

Four-phase discovery conversation: Context (load conventions, scope check, classify work type) → Framing probe (F1 driver / F2 alternatives / F3 substitute behavior / F4 concrete walkthrough) → Targeted dimension walk (9-dimension coverage checklist; every dimension ends with a stated answer or signal-cited N/A) → Synthesis (stop-and-summarize gate, section-by-section approval, structured end-of-stage summary). Four cross-cutting rules (CC-1 playback gate, CC-2 contradiction watch, CC-3 adjacent-scenario invitation, CC-4 mid-conversation scope re-check) apply throughout Phases 2–4. Output is shared understanding in the coordinator's context plus a fixed-shape structured summary in the agent's final message; no files written to disk — ss-sdd-writing-specs renders the spec next.

ss-sdd-writing-specs

Renders the agreed understanding from discovery into spec.md at docs/specs/NNN-short-name/spec.md. Opinionated structure: user stories with P1/P2/P3 priorities + Given/When/Then acceptance scenarios, FR-### functional requirements with story traceability, measurable SC-### success criteria, key entities, edge cases, assumptions, out-of-scope. EARS format allowed where precision matters. Initializes the state file. Forbids Mermaid/C4/PlantUML/ASCII diagrams. Includes automated schema validation (validate-spec.sh) followed by an inline fresh-eyes pass before handing off to ss-sdd-reviewing-specs.

ss-sdd-reviewing-specs

Subagent skill. Independent fresh-eyes review of a spec before plan writing. Detection passes: completeness, internal consistency, clarity/ testability, constitution / ADR alignment, scope, YAGNI, vocabulary drift. Findings categorized CRITICAL / HIGH / MEDIUM / LOW. Strict read-only — does not modify files. Calibrated to approve unless there's a real CRITICAL/HIGH finding (noisy reviewers get ignored). This is the single spec-review pass.

ss-sdd-maintaining-adrs

Subagent skill. Reads the spec and existing ADRs, identifies decisions that warrant new ADR records (architectural, with real alternatives, where the reasoning matters), and writes them in a locked format (Title / Status / Date / Spec link / Context / Decision / Consequences / Alternatives Considered). Avoids duplicates against existing ADRs; marks supersession explicitly when applicable. Returns 0 ADRs as a valid outcome — not every spec needs new ADRs.

ss-sdd-writing-plans

Renders the approved spec into plan.md at docs/specs/NNN-short-name/plan.md. Tasks are organized into phases by user story (Setup → Foundational → Phase per story in priority order → Polish), with [T###] IDs, optional [P] parallel markers, [US#] story labels, exact file paths, and **Requirements:** FR-### traceability. Each task has bite-sized TDD steps (2-5 min each) with actual code, exact test commands with expected output, and commit messages. [NO-TDD] opt-out marker is allowed ONLY for strict categories (docs-only, config-only, asset-addition, dependency-bump, mechanical-rename, lint-only); the writer's own self-review flags misuse as CRITICAL. Forbids placeholders, Mermaid/C4/PlantUML/ASCII diagrams, and references to things not defined in the plan or codebase. Includes automated schema validation (validate-plan.sh). There is no separate plan-review or plan-approval stage — the plan is a mechanical rendering of the already-approved spec, so the writer's self-review is its only check.

ss-sdd-choosing-feature-branch

Stage 7: branching decision + batch commit. After the plan is written, settles the feature branch via an opinionated rule — silent when on main (creates feat/<short-name> from branching.branch_pattern) or already on the derived branch, with a prompt only when the current branch is ambiguous. Then batch-commits all SDD planning artifacts (spec, plan, ADRs) in two thematic, path-scoped commits on the chosen branch. Path-scoping protects the user's pre-existing dirty files.

ss-sdd-implementing-plans

Per-task orchestration loop. For each task in plan order: dispatch implementer subagent → handle status (DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT) → mark task complete. There are no per-task reviews — the implementer's own TDD and self-review carry per-task discipline. After all tasks: a single mandatory final cross-cutting code-quality review on the full branch diff (driven by a self-contained prompt template; no skill loaded). Continuous execution between tasks — no needless check-ins. Includes two prompt templates as separate files (implementer-prompt.md, final-review-prompt.md).

ss-sdd-implementing-task

Protocol skill loaded by implementer subagents when dispatched per task. Covers scope discipline (with concrete in-scope vs out-of-scope examples), TDD-by-default + strict [NO-TDD] handling, commit hygiene (one task → one commit, Conventional Commits style with task ID reference), the four-status reporting protocol (DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT), self-review checklist, and a rationalizations table calling out the most common scope-creep traps. Includes the "your work will be reviewed" priming that measurably improves output quality.

The final cross-cutting code review (end of Stage 8) is driven by the self-contained final-review-prompt.md template — no skill is loaded. It runs once over the whole branch diff with a six-dimension rubric (readability, correctness around edges, idiom, security, performance, maintainability), prioritizing cross-cutting concerns (inter-task inconsistency, integration drift) over isolated per-task nits. Severity: Critical (correctness/security/data) / Important (idiom/readability) / Minor (style). Style is never Critical.

ss-sdd-testing-implementation

Optional feature-level testing stage (user-gated, default yes). Asks the user how deep the testing should go — quick (P1 golden paths only, no edge cases) or standard (P1 + listed edge cases, P2/P3 if cheap; default) — then dispatches a tester subagent that chooses strategy based on the feature type (UI / backend / library / mixed) and available MCPs (browser automation for UI, DB MCP for data verification, project test runners always). Three possible results: PASS, FAIL (triggers fix-loop with hard cap of 3 iterations before escalating), MCP_UNAVAILABLE (coordinator surfaces a manual test plan + code-review findings to user; explicitly forbidden from testing itself). The tester and fixer subagents load full protocol skills (ss-sdd-testing-feature and ss-sdd-fixing-test-failures respectively); the prompts in this directory are dispatch envelopes only.

ss-sdd-testing-feature

Protocol skill loaded by the tester subagent. Strategy selection by feature type (UI / backend / library / mixed), coverage scoped by the dispatcher-provided DEPTH (quick = P1 golden paths only; standard = P1 + listed edge cases, P2/P3 when straightforward), explicit tool inventory (browser MCPs / DB MCPs / project test runners / HTTP), per-story execution against acceptance scenarios, three-status output (PASS / FAIL with per-failure structure / MCP_UNAVAILABLE with manual test plan + code-review fallback). P1 golden paths are the mandatory floor at both depths. Hard rule against fabricating results — if you can't run real tools, return MCP_UNAVAILABLE.

ss-sdd-fixing-test-failures

Protocol skill loaded by the fixer subagent. Narrow-scope fix discipline (no adjacent refactors, no spec/plan edits), per-failure diagnose → fix → verify via the tester's exact reproduction. Four-status protocol (DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT) with the strict rule that any unverified failure = BLOCKED, never DONE. One commit per failure when separable, grouped by root cause when shared.

ss-sdd-finishing

Final stage. Reads the state file, prints a structured summary of what the pipeline produced (feature_id, spec/plan paths, ADRs, tasks, test status, branch info), then closes the loop: git checkout main && git merge --no-ff <branch_name> and safe-delete the feature branch on success. Last step is rm .sublime-skills/state.json via plain rm (no commit; the file is gitignored throughout). Local-only — no push, no PR. If the merge fails (conflicts, hook rejection), the skill halts and leaves the working tree as-is; re- invocation is naturally idempotent once the merge is resolved.

ss-sdd-maintaining-memory-file

Subagent skill. After each SDD run, decides whether the project's agent memory file (CLAUDE.md, AGENTS.md, GEMINI.md, .agents.md — auto- detected or config-pinned) needs updating based on what was produced. "No update needed" is the most common outcome — most features don't change project-level truth. When an update IS warranted (a new ADR that introduces a project-wide rule, a new convention, a hard constraint), the skill writes one-line rules into the appropriate section, respecting a configurable character cap (default 40000). Strict filters keep memory files from accreting cruft: no timestamps, no narrative, no duplicates of code-self-evident truths, no entries that need a paragraph to explain. Includes a substantial Best Practices section on what memory files are for, what they're NOT for, healthy size ranges, update cadence, pruning, and anti-patterns to avoid.

ss-sdd-receiving-review-findings

Inline skill loaded by the coordinator when the spec-review subagent returns findings (Stage 3). Borrows from superpowers' receiving-code-review: no performative agreement, verify before fixing, push back with technical reasoning when the reviewer is wrong, track push-backs in state file, surface to user when findings need human judgment.

project-bootstrap (separate family)

One-time project setup — a coordinator plus seven inline conversational discovering-X skills. Lives under skills/project-bootstrap/, separate from the SDD family. Invoked manually by the user, not by the SDD coordinator.

For the full bootstrap walkthrough (steps, decision tree, re-run semantics, troubleshooting), see docs/bootstrap.md.

ss-bs-auditing-project

Re-evaluates an already-bootstrapped project for drift, incoherence, and improvement opportunities. Sibling to ss-bs-bootstrapping-project; re-uses the discovery skills via MODE=audit with SUGGEST=on. Commits stage-by-stage so the user can accept some changes and decline others. Run cases: quarterly health checks, post-refactor sweeps, doc-staleness investigations.

ss-bs-bootstrapping-project

The coordinator. Walks the user through each convention file: detect existing → ask Skip / Extend / Replace (or Create if missing) → load the matching ss-bs-discovering-<topic> skill inline → the skill handles its own scan, conversation, and atomic write. Then creates docs/adr/, docs/specs/ with stub READMEs; copies the canonical config scaffold at skills/project-bootstrap/scaffolds/config.yml to .sublime-skills/config.yml; sets context.<name>_path to null for skipped files; runs validate-config.sh in a fix-and-retry loop until PASS; commits. Pipeline now covers 7 artifacts (constitution → architecture → testing → glossary → domain → design → memory file) and runs a cross-artifact coherence check before commit. Supports an opt-in prescriptive 'suggestion pass' (SUGGEST=on) that flags anti-patterns and missing-but-typically-valuable patterns, cited from evidence.

ss-bs-discovering-architecture

Per-artifact inline conversational skill — loaded into the coordinator's own context (NOT dispatched as subagent). Does a silent code scan (build files and infra config), announces findings to the user, then asks targeted questions about anything the code can't reveal (system boundaries, service interactions, API composition, ownership rules). Drafts, refines via a tweak loop (cap 3), and atomically writes its file. Supports an opt-in prescriptive 'suggestion pass' (SUGGEST=on) that flags anti-patterns and missing-but-typically-valuable patterns, cited from evidence.

ss-bs-discovering-constitution

Per-artifact inline conversational skill for project principles. Does a silent code scan (linter / CI / source patterns), announces findings, then asks targeted questions about any implicit principles the code reveals. Drafts, refines via a tweak loop (cap 3), and atomically writes its file. Supports an opt-in prescriptive 'suggestion pass' (SUGGEST=on) that flags anti-patterns and missing-but-typically-valuable patterns, cited from evidence.

ss-bs-discovering-design

Per-artifact inline conversational skill for the visual design system. Unique among the seven for offering an Import path in addition to the standard Build path — the user can supply a path to an existing DESIGN.md (from styles.refero.design, Specify, Tokens Studio, or hand-authored) and the skill verifies + previews + atomically copies it. Build path runs a code scan (Tailwind config, CSS custom properties, theme/token files, component libraries) plus targeted user questions about theme intent, brand vibe, color role rules, and do's-and-don'ts. Uses one-question-at-a-time structured prompts with recommended options. Supports an opt-in prescriptive 'suggestion pass' (SUGGEST=on) that flags anti-patterns and missing-but-typically-valuable patterns, cited from evidence (Build path only; Import path skips diagnose).

ss-bs-discovering-domain-model

Per-artifact inline conversational skill for the domain model. Does a silent code scan (schemas and model files), announces findings, then asks targeted questions about conceptual entities, relationships, and lifecycle. Drafts, refines via a tweak loop (cap 3), and atomically writes its file. Supports an opt-in prescriptive 'suggestion pass' (SUGGEST=on) that flags anti-patterns and missing-but-typically-valuable patterns, cited from evidence.

ss-bs-discovering-glossary

Per-artifact inline conversational skill for domain vocabulary. Does a silent code scan (source identifiers and inline comments), announces findings, then asks targeted questions about aliases and canonical term choices. Drafts, refines via a tweak loop (cap 3), and atomically writes its file. Supports an opt-in prescriptive 'suggestion pass' (SUGGEST=on) that flags anti-patterns and missing-but-typically-valuable patterns, cited from evidence.

ss-bs-discovering-memory-file

Discovers, drafts, and writes the project's agent memory file (CLAUDE.md / AGENTS.md / GEMINI.md / .agents.md). Runs last in the bootstrap sequence so it can synthesize pointers to the other six artifacts rather than duplicate them.

ss-bs-discovering-testing

Discovers, drafts, and writes the project's testing convention file at docs/TESTING.md. Scans test directories, runner configs, CI commands, coverage tooling, and mocking patterns; optionally proposes improvements when SUGGEST=on.

Slash commands

Slash commands live as flat .md files under commands/ — one file per command, no per-command directory. Claude Code reads them from ~/.claude/commands/<name>.md, so installation is a symlink loop (see docs/SETUP.md). Each command file is named identically to how it'll be invoked: e.g. commands/ss-agile-populate-issues.md → /ss-agile-populate-issues in any session.

/ss-agile-advance-milestones

Zero-argument command — auto-picks the current milestone and advances it by one issue end-to-end (implement, polish, local merge). Loads the ss-agile-advancing-milestones skill. Designed for ralph-loop re-invocation until all milestones close.

/ss-agile-populate-issues

Three-argument command (<repo-url> <num-sprints> <path-to-goals-file>) that plans and pre-populates N sprints' worth of GitHub issues from a goals document. Distributes work across milestones in a logical order. Loads the ss-agile-managing-issues skill for all gh interaction.

Setup

What each skill needs before its tools will run:

spec-driven-development + project-bootstrap

The SDD pipeline and the bootstrap workflow both invoke shared scripts under skills/spec-driven-development/framework/ and copy the canonical config scaffold from skills/project-bootstrap/scaffolds/config.yml. Those invocations resolve via the SUBLIME_SKILLS_HOME environment variable, which must point to the directory containing this README.md — i.e. wherever you've placed this repo.

Export it once per machine. For fish (the recommended setup, since Claude Code is typically launched from a fish terminal), the cleanest option is a universal variable:

set -Ux SUBLIME_SKILLS_HOME ~/.claude/skills/sublime-skills

(Adjust the path to match where you cloned / copied this repo.)

Alternatives if you launch Claude Code from outside a fish session (.desktop launchers, systemd units, other shells):

# ~/.config/fish/conf.d/sublime-skills.fish — runs on every fish startup
set -gx SUBLIME_SKILLS_HOME ~/.claude/skills/sublime-skills

# ~/.config/environment.d/sublime-skills.conf — systemd user-environment, shell-agnostic
SUBLIME_SKILLS_HOME=%h/.claude/skills/sublime-skills

The skills fail loudly if SUBLIME_SKILLS_HOME is unset — the scripts won't silently look in the wrong place. If you see an error like SUBLIME_SKILLS_HOME is not set; see Sublime-Skills README for setup, the variable isn't exported in the shell that's running the skill.

The scripts themselves locate sibling helpers via $0 and the user's project via git rev-parse --show-toplevel, so neither the script directory layout nor the project's location matters once SUBLIME_SKILLS_HOME is set.

To expose the skills globally, run the installer — one command covers both Claude Code (skills + slash commands) and Codex (skills only):

$SUBLIME_SKILLS_HOME/scripts/install.fish

The script is idempotent — re-run it after a git pull, a local skill rename, or any other change that might have drifted the symlinks. A matching uninstall.fish removes every Sublime-Skills symlink from both harnesses.

See docs/SETUP.md for the personal machine setup, symlink targets, and uninstall notes.