skill-mesh

Agent skills for planning, building, reviewing, and shipping software — run as a gated pipeline where every build step clears independent, calibrated reviewers, and the same skills run on Claude Code and GitHub Copilot from one behavior contract.

• Gated pipeline — plans are reviewed before they become issues; builds run autonomously but every step is gated; acceptance is evidence-based.
• Independent, calibrated review — verdicts come from fresh-context reviewers that must cite file:line, aggregated deterministically; the judges themselves are calibrated against gold fixtures, not trusted on faith.
• Real & provider-neutral — ~50 skills actually used day to day, extracted from a personal workspace; one behavior contract runs on Claude Code and GitHub Copilot (47 portable; 3 Claude-native).

Swap the placeholders (<workspace>, <project>, <your-org>) before use — see Adapt before use.

Workflows

How these skills chain together in practice — every sequence below is a workflow run in production, with copy-pasteable commands. Detailed write-ups are collapsed; click a heading to expand.

• /goal, /loop, /schedule, and /deep-research are Claude Code built-in commands (not skills in this repo) that several skills emit or arm — substitute your host's equivalent or skip on Copilot.
• Pipeline skills are autonomous by default (no mid-run "(y/n)?" prompts); conversational skills (plan-init, plan-feature, plan-merge, plan-trim, the user-* ideation skills) stop and ask by design.

The core pipeline

Plan → sync → build → ship. Everything else supports this spine.

plan-expedite collapses the middle — plan-review → plan-redline → plan-wrap → repo-sync → handoff — into one autonomous command, ending by printing the /goal + /build-phase pair to paste next.

Order is load-bearing twice. plan-review before repo-sync: a gap caught after issues are minted means editing the plan plus N issue bodies (the "N+1 edit" trap). repo-sync before build-phase: build-phase posts live progress to those issues, so blank Issue: lines kill the audit trail.

Inside one build step: the review gate

The core pipeline's BUILD box is a gated loop, not a straight line:

What the diagram can't show: independence is engineered — reviewers run in fresh, isolated context (the producer never grades itself), and every finding must cite file:line or it is dropped; and the verdict is a deterministic reducer, not a model — the same findings always yield the same result, written after all ship/cleanup gates to a durable, run-bound, HMAC-authenticated verdict.json sidecar. Missing, stale, malformed, or tampered verdicts fail closed on both Claude and GPT.

Lanes scale the scrutiny: auto (tests only) → code (5 lenses) → deep (review-deep + audit trail) → runtime / full (evidence on a running app).

The routing web

Every operator fragment — a bug report, a half-formed feature idea, a "does this even work?" — lands on one of 8 rails, and /user-gateway is the intake front door that sorts a whole brain-dump across them, one ledger row per fragment (full table and all 9 re-route edges: _shared/skill-pipeline.md).

The graphic shows where each rail goes; the table shows what a fragment sounds like to land there:

Rail	Sounds like	Routes to
bug	"X is broken / erroring"	/user-debug
do	"just do X" — small, resolved	/goblin-do
plan	"add / build capability X"	/plan-feature (existing) · /plan-init (new) → build
investigate	"what's true / why does X happen?"	/deep-research · Explore sweep
verify	"does X actually work?"	/review-uat · /user-uat · /user-shakedown · /user-walkthrough
trim	"plan feels bloated / what to cut"	/plan-trim
decide	"should we do A or B?"	surfaced, then parked
draft	"here are rough thoughts"	/user-draft → /goal

What's inside

50 skills across planning, building, review, shipping, and skill/workspace maintenance

Core pipeline — plan → build → review → ship:

Stage	Skills
Planning	plan-init · plan-feature · plan-review · plan-redline · plan-wrap · plan-merge · plan-trim · plan-expedite
Building	build-step · build-phase · build-queue
Review	review-deep · review-gauntlet · review-proof · review-uat · judge-ui · judge-motion
Repo & docs	repo-init · repo-sync · repo-update

Supporting:

Area	Skills
User & session	user-brainstorm · user-debug · user-draft · user-gateway · user-learn · user-orient · user-pm · user-project · user-shakedown · user-uat · user-walkthrough · user-wrap · user-lavishify · session-wrap · task-handoff · research-prospect
Skill tooling	skill-eval-setup · skill-evolve · skill-iterate · tier-offload · tier-escalate
Maintenance & hygiene	test-prune · lesson-harvest · memory-distill · context-slim · user-afterparty · observatory-doctor
Project improvement	goblin-suggest · goblin-do — reference only; needs a private second-brain store + the goblin CLI, see _shared/goblin-second-brain.md
Reference	claude-oauth-auth

_shared/ holds resources referenced by several skills — the judging doctrine (judge-core.md), the skill routing web (skill-pipeline.md), the intake-ledger contract (intake-engine.md), the skill-role taxonomy the tier-* skills share (skill-role-taxonomy.md), a guide to rebuilding the goblin-* second brain (goblin-second-brain.md), and the skill-scoring harness.

Links point to each skill's core.md behavior contract; the 3 Claude-native skills link to their providers/claude.md. Full capability and exclusion matrix: documentation/providers/.

Pick your entry point

Start with	What it's for
/plan-init	Brand-new project — gated to greenfield; any existing commit redirects to plan-feature.
/plan-feature	Add a feature to existing code — plan-review finds gaps, plan-wrap proves self-containment.
/build-step	One well-scoped change, no plan — three orthogonal knobs (isolation, reviewers, UI).
/user-debug	Stuck circling a bug — forces an independent repro before any code change.
/review-gauntlet	Review a diff or PR — lean profile over review-deep's engine, terser verdict.
/review-uat	A build needs human acceptance — agent runs the mechanical tier, escalates judgment calls with evidence.
/build-queue	Run several phases overnight — every halt parks as a GitHub issue; nothing retries at 3am.
/user-wrap	Sitting back down / "where were we?" — one skill makes the wrap/continue/clear call.
/user-gateway	A head full of half-formed observations — sorts the brain-dump across 8 rails, one row each.
/user-pm	Survey or challenge the plan — prescribes but never executes; plan-trim writes.
/skill-evolve	Improve the skills themselves — A/B variants; prints the PR, never opens it.
/user-brainstorm	Explore an idea or learn a topic — deliberately conversational.

1. New project → shipped v1

/plan-init                          # structured conversation → plan.md
/repo-init                          # first time only: git init, GitHub repo, README, plan → issues
/plan-expedite --plan plan.md       # autonomous: plan-review → plan-redline → plan-wrap → repo-sync → handoff

plan-expedite finishes by printing a ready-to-paste pair — arm the goal, then build:

/goal "<completion condition it emitted>"
/build-phase --plan plan.md

Then wrap the phase:

/repo-update                        # README, plan doc, memory, commit, posterity issue, push

• plan-init is gated to greenfield: if the project has any commit it stops and redirects to plan-feature.
• build-phase reads ### Step N: blocks from the plan, spawns one build-step per code step, posts progress to the GitHub issues, and only halts for five legitimate reasons (quality-gate hard fail, wait-type step, merge conflict, bad conditional predicate, stop-and-audit).

2. Feature on an existing project

Same spine, different front door:

/plan-feature <one-liner>                                   # reads the codebase, asks about the delta
/plan-expedite --plan documentation/<feature>-plan.md
/goal "<emitted condition>"
/build-phase --plan documentation/<feature>-plan.md
/repo-update

Prefer the à-la-carte version when you want to inspect between stages:

/plan-review documentation/<feature>-plan.md    # technical gaps, risks (autofix on by default)
/plan-redline --plan documentation/<feature>-plan.md   # operator-facing proposal + P/D feedback fold-in
/plan-wrap documentation/<feature>-plan.md      # self-containment for a fresh-context model
/repo-sync --plan documentation/<feature>-plan.md
/build-phase --plan documentation/<feature>-plan.md

• plan-review and plan-wrap check different things: review finds technical gaps; wrap checks the doc is self-contained for a model with zero conversation history (issue bodies and autonomous builds depend on that). plan-redline sits between them, turning the corrected plan into an operator-facing proposal and folding P/D feedback back in.

3. One-off change, no plan

/build-step --problem "<what to build or fix>" [--issue N]

One skill, three independent knobs:

• --isolation worktree|docker — where the developer agent works (worktree default).
• --reviewers auto|code|deep|runtime|full — auto = quality gates only; code = 5 parallel review-gauntlet agents; deep = one review-deep call; runtime = 3 evidence-based reviewers; full = all eight (5 code + 3 runtime).
• --ui --start-cmd "<cmd>" --url <url> — Playwright evidence capture for frontend steps.

4. Getting unstuck on a bug (user-debug)

/user-debug --symptom '<exact error / log line / misbehavior>'

• Reach for it when a bug keeps circling between you and the agent — command-paste back-and-forth that isn't converging. It forces primary-source investigation and an independent reproduction before any code change, then delegates the fix to build-step and re-runs the original repro to prove the symptom is gone.
• It's operator-invoked when you're stuck, not a plan-driven step — which is why it lives with the user-* skills rather than the build-* pipeline. (It still writes real code via build-step.)
• --triage investigate-only stops after the diagnosis block — root cause without the fix.
• If investigation concludes the "bug" is really designed, multi-step work, it re-routes to a /plan-feature seed instead of forcing a fix (the routing web's bug→plan edge — see _shared/skill-pipeline.md).

5. Reviewing a diff on its own

Both review skills also run standalone, outside build-step:

/review-gauntlet <prompt> <diff>     # routine diffs: lean profile over review-deep's engine (5 code lenses, terse verdict)
/review-deep --prompt '<intent>' --diff <PR# | git diff | paste>    # high-stakes: 6 lenses + JSON audit trail

• review-gauntlet is a thin profile over review-deep's engine — the same code lenses (correctness, bugs, security, test quality, style) and deterministic aggregation, but positional args, a terse PASS / NEEDS-WORK verdict, and no JSON sidecar. Reach for review-deep on substrate/schema/key-shape changes and producer→consumer chains; --plan-step <plan>:<step> adds a plan-conformance lens.
• Inside the pipeline, build-step --reviewers deep dispatches review-deep directly for high-stakes steps, and plan-review (§27) routes those steps at plan time by rewriting the step's Flags line from --reviewers code to --reviewers deep.
• review-proof is the cross-cutting discipline both lean on: findings must cite file:line or be dropped. Invoke it directly for "are you sure?" moments — audits, debugging, architecture claims.

6. Acceptance testing (UAT)

After a build, human-facing verification splits by whether a test script exists.

A script exists (a plan M-step, a commands+expectations table):

/review-uat plan.md#step-M          # refine: explicit prereqs, observable pass criteria, agent/human split
/user-uat plan.md#step-M            # execute: agent runs the mechanical tier, auto-judges with evidence

No script — explore the built thing directly:

/user-walkthrough <feature>         # attended: you drive, agent answers from source, fixes small things live
/user-shakedown <feature>           # autonomous: closes every open ledger item (verify / quick-fix / log)

• Walkthrough and shakedown share one ledger, so you can explore attended and then hand the remainder to shakedown, armed under a mechanically checkable goal: /goal "shakedown ledger for <slug> has zero open items".
• Anything needing human judgment is escalated with evidence, never guessed.
• review-uat --exec is refine-then-delegate: it hands the refined script to /user-uat for execution rather than running anything itself.
• Finish with /repo-update to commit the fixes and file the logged issues.

7. Unattended overnight runs

/build-queue --queue <path>         # one line per phase plan

• For each queue item it runs plan-expedite then build-phase, each phase in its own worktree, strictly sequential.
• Any halt is parked — a GitHub issue with halt context — and the queue moves on; nothing retries at 3am. A kill-switch file (.build-queue-killswitch) is the only mid-run control.
• You get a morning summary; run /repo-update per shipped phase over coffee.

8. Session & context management

These session skills assume Claude Code's context harness — auto-compaction, a SessionStart hook that re-injects current.md, and /clear / /compact. On hosts without it, they degrade to plain checkpoint/handoff files.

One skill (session-wrap) makes the wrap/continue/clear decision; everything else is a library it calls or a mode it delegates to.

/session-wrap                       # the front door: triages (context, task boundary, git, armed /goal), announces ONE route, acts
/session-wrap --advise              # read-only verdict: KEEP GOING / RECYCLE WINDOW / WRAP & CLOSE / SAFE TO CLOSE + loss report
/user-wrap                          # the return moment ("sitting back down — keep going or close?"): orient, delegate to --advise, act
/task-handoff --loop                # checkpoint library: durable current.md write mid-task (~5s)
/task-handoff --next-task <label>   # durable task-boundary save, keep working
/task-handoff                       # bare = --resume: orientation block from the last checkpoint
/user-project <name>                # pin the session's active project so pipeline skills target the right repo
/user-orient                        # session-axis re-orientation: verified vs not, asides, recommendation (read-only)
/user-orient --quick                # ~150-word thread refresh: problem / tried / still to do (no lookups)
/user-gateway <topic> <vent>        # pre-work intake: convert a brain-dump into routed, ledger-backed work
/user-draft <rough thoughts>        # polish a rough idea into a reusable prompt or a /goal condition
/context-slim [--apply]             # audit auto-loaded context files; prune per-turn token cost

• session-wrap makes the call. Invoked bare at any transition moment, it scores mechanical signals (context utilization, task-boundary state from current.md, git state, armed /goal), announces one route, then acts: continue (checkpoint + one line), clear-next (durable state → rendered handoff prompt → git verb → emit /clear), or end-window (full wrap: memory/docs passes + a Pick-up-here block). --advise is the read-only variant — a verdict banner + two-line loss report, never acts.
• user-wrap serves the return moment — sitting back down after lunch or overnight. Despite the name, the most common verdict is KEEP GOING. It owns zero triage logic of its own: it orients from current.md + git, delegates the verdict to session-wrap --advise, re-presents the banner + loss report front and center, then acts per verdict.
• task-handoff is the checkpoint library orchestrators call (build-phase, build-step, plan-expedite, user-draft); operators usually want /session-wrap.
• user-gateway converts a brain-dump into routed work: one ledger row per voiced fragment, routed by consulting the routing web, each with a ready-to-paste seed — it converts what you said and never proposes work of its own.

See the routing web map near the top for how /user-gateway sorts a vent across all 8 rails.

• The underlying doctrine is native context management first: auto-compaction and goal-arming handle most sessions, so the default is to keep working in one window and reach for the front door only at genuine transition moments.
• user-draft is the authoring helper — it turns rough thoughts into a clean prompt or a checkable /goal string and checkpoints via task-handoff --loop so a window pivot loses nothing.

9. Plan & portfolio maintenance

/user-pm [--cut|--goal|--overnight|...]   # read-only PM snapshot: shipped / outstanding / next / cuttable
/plan-trim                                # the write path: propose 3-8 cuts, execute on confirm
/plan-merge <plan-1> <plan-2>             # reconcile overlapping plans into one spine
/research-prospect                        # survey all active projects → menu of /deep-research topics to farm out

• user-pm prescribes, never executes — its Build/Overnight moves print the ready /plan-* or /build-phase command with prerequisites. plan-trim is its writing companion.
• research-prospect is the cross-project sibling of user-pm: read-only, it surveys every active project and emits a prioritized menu of research topics to farm out to other windows.
• After a merge, re-run /plan-review + /plan-wrap on the merged plan and /repo-sync to re-cut issues. Originals are archived, never deleted.

10. Improving the skills (and the workspace's memory)

Two independent tracks operate on the skills themselves and on the workspace's feedback memory.

# improve a skill
/user-brainstorm <skill or problem>              # candidate strategies / framings to try
/skill-eval-setup <skill>                        # bootstrap evals.json + scenarios + golden corpus
/skill-evolve --skill <name> --variants <file>   # A/B N variants in parallel; pushes winner, prints gh pr create
/skill-iterate                                   # overnight serial hill-climb (1h or 12 iters per skill)

# codify a lesson
/lesson-harvest --dry-run                        # scan git history + run logs for un-codified regressions → draft PR
/memory-distill                                  # human gate: distill drafts into durable principles (the only memory writer)

• The improve track is explore-then-exploit: brainstorm framings, A/B them with skill-evolve, then hill-climb the winner with skill-iterate. (In steady state the two loop — skill-iterate runs nightly and hands plateaued skills back to skill-evolve; see each skill's core.md.)
• skill-evolve and skill-iterate both require the evals folder skill-eval-setup creates.
• Nothing self-approves: skill-evolve prints the PR command instead of opening it, lesson-harvest only drafts, and memory-distill keeps a human at the write gate.

11. Ideation & learning

/user-brainstorm <topic>            # 10 seed topics + gap-fill rounds → tiered doc set under docs/investigations/
/user-learn <topic>                 # hands-on learning ramp: runnable notebooks, exercises, tracker

These are deliberately conversational — they keep you in the loop instead of running the pipeline.

Quick start

Install & prerequisites

Install for your host — the installer and runtime are PowerShell on Windows:

powershell -File tools/install-skill-mesh.ps1 -Provider claude -Home <install-home>   # Claude Code
powershell -File tools/install-skill-mesh.ps1 -Provider gpt    -Home <install-home>   # GitHub Copilot

Then run a skill to try one — in Claude Code that's a slash command (/plan-init); on GitHub Copilot the same skill is discovered from its installed folder. Skills ship with placeholders — swap <workspace> / <project> / <your-org> before running (see Adapt before use).

Prerequisites: Windows with PowerShell. Windows PowerShell 5.1 is the floor the tooling is written for and the executable the test suites shell out to, so the blocks above are spelled powershell. If PowerShell 7+ is also installed you may substitute pwsh — but never the other way round, since pwsh is absent on a 5.1-only machine. Also: an authenticated gh CLI for the repo-* and build-* skills (they create repos and post to issues); Playwright for the --ui and judge-* skills.

Providers & installation

Each skill has one provider-neutral behavior contract (skills/<name>/core.md) plus a thin per-host adapter; installing binds one adapter into that host's discovery layout. 47 of 50 skills run on all three hosts; 3 are Claude-native (claude-oauth-auth, context-slim, judge-motion).

Provider	Host	Install target
Claude	Claude Code	<install-home>/.claude/skills/<skill>/
GPT	GitHub Copilot CLI	<install-home>/.github/skills/<skill>/
Codex	OpenAI Codex CLI	<install-home>/.agents/skills/<skill>/

• GPT discovery roots — GitHub Copilot CLI discovers project skills from .github/skills/, .agents/skills/, and .claude/skills/ (personal: ~/.copilot/skills/); this package installs the GPT profile to .github/skills/, and every generated SKILL.md leads with a YAML frontmatter block (name, description). The originally-assumed project-relative .copilot/skills target is retired — it is not a Copilot discovery root (proven in Step 43).
• Codex — the full portable catalog: all 47 portable skills carry a providers/codex.md adapter (grown from the five-skill pilot across the Phase CP cohorts) and install to .agents/skills/. That is the same literal path Copilot already scans as an active alternate, so the root's presence is not evidence of which host wrote it. tools/probe-codex-skills.ps1 is a read-only bring-up probe (effective home, root state, ledger). Because a third provider is now declared, -Provider both (claude+gpt, still the release default) is no longer a complete legacy-migration source — see documentation/migration.md.
• Install — see Quick start. Flags: -Uninstall, -Force, -Home/-Destination, -Provider/-Profile.
• Auth (a separate axis from selection) — Claude uses the host's own model (no key); GPT via GitHub Copilot sign-in (gh auth login), no OPENAI_API_KEY needed.
• Deep dive — router auto-detection, the full auth/capability/exclusion matrices, and the selection/transport contract: documentation/providers/, architecture.md §5.

Status & adapting

Current status

• ~50 skills; 47/47 skills are GPT-capable behind the shared Claude/GPT behavior contract; 3 additional skills are Claude-native.
• Shipped: the canonical skills/<name>/{core.md,providers/} source tree, the provider-neutral router, and the distribution builder, installer, and release tooling (reproducible SHA-256 checksums over a git ls-files stage). Measured test counts are deliberately NOT restated here — they live in documentation/phase-75-baseline.md, the one owner of the pytest gate contract, because a count copied into a second document is a count that drifts.
• Phase 7 complete — issues #62–#63 closed. Real Claude Code and GitHub Copilot CLI acceptance verified a generated plan-review profile from each host-native discovery root; the live coding-root cutover installed 50 Claude and 47 GPT generated entries, preserved consumer-only material, retained an external rollback backup, and kept the legacy router callable through the generated compatibility shim. Step 48 is DONE; its reusable operator handoff remains at documentation/coding-root-cutover-handoff.md. See documentation/host-native-discovery-cutover-plan.md.
• Phase CP pass 1 — Steps 1–5 complete; issues #118–#122 closed. Codex is a third provider on the generation, install, and inspection rails: a five-skill pilot with its own discovery root (.agents/skills), a read-only bring-up probe, and a temp-home install/inspect/uninstall round-trip proving zero writes outside the disposable home. The legacy migrator carries zero Phase CP delta by an explicit decision — a partial-distribution migration fails loud (MISSING_PROFILE) rather than risking orphaned bytes, and that hardening is tracked separately. The remaining cohorts were gated on the operator bring-up verdict — delivered as milestone M1 (next bullet). See documentation/codex-parity-delivery-plan.md.
• Phase CP milestone M1 complete — issues #130 closed. The pilot's live bring-up on a real host: the installed Codex CLI (0.147.0) discovers all five pilot skills from .agents/skills, both exercised skills honored their contracts (plan-review rendering its verdict through the single-context fallback), and the first live consumer-home write touched only the codex root and its ledger. GitHub Copilot CLI 1.0.77 was observed enumerating the shared root's codex packages; the accept decision and its reason are recorded with the rest of the evidence in documentation/parity-deltas.md. The conditional cohort steps are released.
• Phase 8 is superseded by Phase CP's additive, cohort-based rollout (course change 2026-08-16). Step 47b remains the separately scheduled containment-gate hardening follow-up and is off the completed cutover path.
• The original 46 top-level <skill>/SKILL.md packages remain as a compatibility surface during a deprecation window — not the canonical source, and not updated by this migration; see documentation/migration.md.
• Full contract: documentation/architecture.md.

Adapt before use

• Replace placeholders (<workspace>, <project>, <your-org>) with your own values.
• Skills that reference a "control plane" or a memory index assume conventions from the source workspace — read the skill's core.md and adjust, or skip those skills.
• Some skills need adapting to your setup. A few carry assumptions from the source workspace: the goblin-* pair ships as reference only — it needs a private "second-brain" atom store and a separate goblin CLI, both omitted, so rebuild your own from _shared/goblin-second-brain.md; tier-offload emits a config for a local-model router and tier-escalate a model-tiering escalation map (adapt to your own models, or skip if you run neither); judge-ui needs a per-project browser adapter (server bring-up, auth, test IDs); observatory-doctor assumes a "dev-observatory" control-plane convention from the source workspace; and user-lavishify drives an annotatable-HTML rendering step. A handful of workspace reference files stay unpublished (shakedown-engine.md, task-state-schema.md, the docs/investigations/ corpus); published skills may point at them — treat those as adaptation points, not missing files.
• No secrets or credentials are included.

Contributing

Issues and suggestions welcome: github.com/aberson/skill-mesh/issues. Shared as an extracted personal toolkit — read Adapt before use before filing.

License

MIT — see LICENSE. Built by Abraham Robison (github.com/aberson).