pstack

this is a CLI-agnostic port of cursor/plugins/pstack by poteto, reworked to install with npx skills and run in Claude Code, Codex, Hermes, and Grok Build. the workflows are poteto's; PORTING.md records the port changes.

This repository is an independent community port. It is not affiliated with, maintained by, or endorsed by Poteto. It aims to stay in sync with her upstream work while adapting it to these CLIs.

The introduction below is reproduced from upstream in Poteto's voice.

i'm poteto. i'm not a president or ceo, but i've worked with millions of lines of code at Meta, Netflix, and Cursor. i'm also on the react core team where i help build and maintain react compiler.

there's a growing sense that ai writes too much slop code. i agree. i don't want to ship like a team of twenty slop artists. throughput without quality is not a goal i aspire to. if you want to go fast, go deep first.

pstack is my answer. these are the same skills i use every day to ship high quality code. this turns your coding agent into a real engineering team. the goal is not to maximize loc, in fact it's the opposite. pstack helps you write less, but higher quality code.

pstack gives you fearless parallelism. when you can go deep on one agent and trust it to write good, verifiable code, you can truly parallelize with confidence. start multiple agents up with poteto-mode and trust that they'll apply rigorous engineering principles to their work.

every frontier model has its strengths and weaknesses. use any model with pstack. in fact, many of my skills use multi-model workflows to take advantage of each model's unique strengths (in CLIs that can switch models per subagent; elsewhere the panels keep their arm count on your session model).

fork it. improve it. make it yours. PRs are welcome!

install

npx skills add mdsmithaustin/pstack

pick the targets you use at the prompt, including hermes-agent for hermes. -g installs user-level instead of per-project. hermes project skills require project trust; confirm discovery in your installed version. for global hermes use, install into its native skills directory or configure skills.external_dirs to include the shared ~/.agents/skills directory. the installer may skip a project hermes symlink when .hermes does not exist.

get started

two steps:

1. run /setup-pstack to check the bundled personas, optionally register native agents, set claude code's skill listing, pick a reasoning budget, and choose which models you want. until the listing step runs, claude code shows every pstack skill's description and can load one on its own, so rerun it after npx skills update.
2. use /poteto-mode whenever you're doing anything that requires rigor.

new here? the pstack guide walks you through a first real task, from setup and prompting through verification and overnight runs. stuck, or unsure which skill fits? ask /poteto-help.

that's it. the other skills are situational, and the mode skill uses them for you as needed. out of the box the mode splits work by model strength (using claude code's subagent model aliases): code delegates (feature, refactoring, bug fix, perf, hillclimb) go to sonnet, while the hardest changes, prose, and judgment go to opus. the default panel is fable / opus / sonnet. the models config reference defines alias translation, model fallbacks, and reasoning effort for each CLI. Spawn a role explains how each CLI applies those choices. /setup-pstack changes any of it.

usage

use /poteto-mode at the start of a task. it reads your request, picks from a set of playbooks, and runs the other skills as the steps need them.

just use /poteto-mode

this skill is the main shortcut. i use it whenever i need the agent to do rigorous engineering work. it comes with twenty-five playbooks:

/poteto-mode this pr has a subtle bug where the scroll drifts every 750ms even when idle. repro
first, then fix and verify.

/poteto-mode i'm going to bed. land the stack even if ci flakes. i want everything merged by
morning.

the twenty-five playbooks

playbook	for
investigation	a read-only question about current code or its history. how does x work, why was y built this way, are we sure.
research (port addition)	external, domain, or dependency evidence for a decision, with sources and explicit gaps.
code review (port addition)	review someone else's pr, branch, or diff for design and correctness before it merges, with the review lens and no edits to their branch.
bug fix	reproduce a defect, root-cause it, and fix with runtime evidence.
perf	trace a measured slowness and improve it against a baseline.
hillclimb	sustained, scientific improvement of one metric against a target, looping hypotheses with before/after measurement and one commit per accepted win.
runtime forensics	diagnose a live symptom (leak, idle-cpu spin, glitch) from instrumentation.
trace forensics	diagnose a captured profiling artifact (cpuprofile, trace, spindump, heap snapshot).
feature	new or changed behavior, built from a named data shape.
refactoring	a behavior-preserving change to structure or shape.
prototype	a throwaway sketch to make a design or behavioral decision cheaply, or to settle an empirical fork by observing it.
visual parity	pixel-exact ui equivalence between two implementations.
authoring a skill	writing or editing a SKILL.md.
eval	test how a skill or prompt change affects agent behavior, blinded.
babysit	drive a pr or a stack to merge-ready: conflicts, review threads, ci.
shipping	independently verify a green stack, then land the contiguous verified run bottom-up through github by default or origin when available.
autonomous run	drive a long task to completion without stopping.
orchestrate	a standing project handed to one coordinator chat: multi-day, many stacked prs, fleets of subagents.
autopilot-full	run independent prs to merged with one owner per pr. a swarm verifies each code-ready head, and every later change to the patch gets a fresh check.
autopilot-stack	build and verify one linear base-branch stack for the operator to review and land.
session pickup	resume or take over a prior agent's in-flight work.
pause safely	suspend in-flight work cleanly so it can be resumed later.
multi-phase plan	work that spans phases or stacked PRs.
worktree cleanup	reclaim disk by pruning merged or abandoned worktrees and stale ios simulators, safety-gated.
opening a pr	open a ready pr from small ordered commits with a conventional commits title and a briefing-style body, when the matched playbook produces a pr.

when invoked it:

1. matches your task to a playbook and opens a todo list whose first items are its opening prose and its steps, copied in verbatim.
2. routes to the other skills as the steps fire.
3. writes unslopped replies framed for the consumer and the maintainer.

the full rules and playbooks live in skills/poteto-mode/SKILL.md.

/poteto-mode is also a sticky mode: once entered it stays on across turns, applying itself when a playbook matches or the task needs rigor and staying out of the way otherwise. opt out any time by saying so. after known compaction or truncation, the agent follows the mode's recovery rule to continue the current task. runtime retention varies; see the dated evidence. if the mode stops applying, type /poteto-mode again.

/poteto-mode works extremely well with a loop mechanism (claude code's /loop, or any re-invoking heartbeat). you can make your agent work for many hours without sacrificing rigor.

skills

/poteto-mode runs most of these for you when a step needs them (how, why, architect, arena, swarm, interrogate, deslop, unslop, no-comments, technical-writing, poteto-tdd, and the principles). the table below is for when you want one directly:

/how do we cancel runs? do we have an n+1 when we look up every run to cancel?

/interrogate review this pr.

all skills

skill	use it when
/poteto-mode	default entry point for any non-trivial task.
/poteto-help	you're new to pstack, or unsure which skill, playbook, or principle fits. finds out what you're trying to do, answers that part, and hands you a prompt to type. it doesn't load from its description (on claude code, once /setup-pstack sets the skill listing), so type /poteto-help.
/in-your-own-words	you want the agent to play back your goal and the problem before it starts. it doesn't load from its description (on claude code, once /setup-pstack sets the skill listing), so type /in-your-own-words.
/sharpen	you want a prompt made deeper, not bigger, before you send it: what a top professional would do that you didn't ask for, the raw material they'd start from, their methods and tools, and an outside check that the result is right. hands back the rewritten prompt and leaves your choices open. doesn't do the task. it doesn't load from its description (on claude code, once /setup-pstack sets the skill listing), so type /sharpen.
/how	you want a walkthrough of how a subsystem works.
/why	you want to know why something was built this way. discovers available MCPs at run time and queries each evidence category in parallel (source control, issue tracker, long-form docs, real-time chat, infra observability, error tracking, analytics warehouse).
/recall	you're starting or resuming work and want your recent context on a topic rebuilt from your own chat history and the shared record, handed back as a tight current-state brief.
/ketchup	you want what changed in this chat since your last message, in plain words and small visuals, with every item waiting on you listed and decidable from the reply alone, even when that makes the reply long.
/blast-radius	you have a small-looking change and want to know what else it could break, with the one fact it's safe because of proven by running code, not asserted.
/architect	you're about to write code that crosses a function boundary and want the caller's usage, types, and module shape settled first.
/arena	you want N parallel attempts at the same thing, then to grab the best parts of each.
/swarm	you want N parallel workers across different slices or races, then one aggregated report.
/interrogate	you have a diff and want different models to try to break it, including a strict code-quality lens.
/automate-me	you want your own -mode skill, drafted from how you've actually worked.
/make-bot-ui	you want a page or dashboard whose buttons wake a Grok Bot over a webhook, including the sender-key handoff and Tailscale.
/setup-pstack	you want to configure pstack models or repository PR templates. full setup preserves existing templates and installs poteto defaults when none exist.
/pstack-harness	(port addition) maps spawning, per-subagent models, parallelism, and transcript access to claude code, codex, hermes, and grok build. the fan-out skills read it when a mechanic differs by CLI.
/reflect	a long task landed and you want the recipe captured as a skill edit.
/correct	you keep correcting agents for the same mistakes. mines history for mistake classes, fixes each at the highest level that works (architecture, then types, lint, and ci, then tests, with docs last), and keeps a table pairing each rule with what enforces it.
/poteto-teach	you want to actually understand a change or subsystem, not just have it summarized. runs how + why and weaves one plain explanation, built up diagram by diagram.
/poteto-tdd	you're fixing a bug and there's a cheap local test path. write the failing test first, then the fix.
/benchmark-checklist	you ran a benchmark or measured a speedup or regression. vets the number (limiter, tuning, errors, repeat runs, end-to-end relevance) before you report or act on it.
/no-comments	strip comments before review; spawns Comment Sicko, fixes accepted findings, offers encodings for claimed constraints.
/deslop	(port addition) you're about to commit and the diff reads padded. removes narrating comments, guards on impossible states, dead compatibility paths, one-caller wrappers, and unrelated edits from the changed hunks, then reruns the touched tests. a comment its rules don't settle goes through /no-comments in the same pass, and the report says what that review did. code only; /unslop is for prose.
/typescript-best-practices	you're reading or editing typescript. grounds the type-system-discipline principle in syntax.
/figure-it-out	no bundled playbook fits. designs a rigorous, auditable playbook for the task.
/show-me-your-work	you want a reviewable decision trail. owns the logging and evidence-retention rules.
/create-verification-skill	your project has no scripted way to prove app behavior. generates a project-local verify skill with a feature map, for any language or platform.
/maintain-verification-skill	your verify skill's feature map has drifted from the app. source wave + one live pass, at most one PR of proven corrections.
/create-formal-verification-skill	tests can't reach the case that breaks a race, retry, state machine, parser, or unsafe code. verifies one property with the tool that fits and generates a project-local skill to recheck it on every change.
/maintain-formal-verification-skill	code your formal verification covers has changed since it was last checked. updates the model, harness, or properties to match the code, reruns, and says whether each failure is drift in the verification or a bug in the code.
/spec-probes	(port addition) you're writing a spec, acceptance criteria, or tickets. surfaces the data-shape edges and the must-nevers before any code exists.
/verify-commands	(port addition) you're writing or reviewing a completion check, or reporting an upgrade, deployment, migration, or install as successful. catches the shapes that pass green while measuring nothing.
/documentation-impact	(port addition) a change may affect user, operator, or developer instructions. updates affected docs or independently reviews them, including an evidenced no-change result.
/runtime-probes	(port addition) you want a live product, feature, or pr probed for unreported defects, or a source-grounded probe handoff while its target is unavailable. only findings a real caller can reach get promoted.
/unslop	you're cleaning up writing. removes AI tells.
/bro	you want the last message restated in plain human language, no jargon.
/technical-writing	layered doc standard (Diátaxis + Google developer style + STE + Global English) for docs, RFCs, readmes, PR descriptions, commit messages.

examples

mostly i type /poteto-mode at the start of a task and let it route to a playbook. the other skills fire as the steps need them. a few i reach for directly.

all the examples

bug fix:           /poteto-mode this pr has a subtle bug where the scroll drifts every 750ms even
                   when idle. repro first, then fix and verify.
perf:              /poteto-mode a big list takes a second or two to load even though we virtualize.
                   run a cpu trace and tell me why.
feature:           /poteto-mode build a small feature behind a feature flag. verify it really works.
prototype:         /poteto-mode build two prototypes of the markdown renderer so we can compare.
                   spawn an agent for each.
multi-phase:       /poteto-mode open source these skills as a plugin. nothing internal leaks, work
                   in a temp dir, show me the dependency graph first.
overnight run:     /poteto-mode i'm going to bed. land the stack even if ci flakes. i want
                   everything merged by morning.
babysit:           /poteto-mode check on pr 123. anything outstanding?
visual parity:     /poteto-mode the row spacing is too tall when this flag is on. the second image
                   is correct. repro and fix until it matches.
figure it out:     /poteto-mode i'm stepping away. migrate every caller from the synchronous store
                   to the new async one, keeping behavior identical. i want to trust it was done
                   right when i'm back.
how:               /how do we cancel runs? do we have an n+1 when we look up every run to cancel?
why:               /why is this feature flag not on yet?
architect:         design this instrumentation to be high signal with no false positives. /architect
                   this first.
arena:             /arena take my prompt to the arena verbatim. i want to compare their proposals
                   with yours.
swarm:             /swarm check every package under packages/ against its check.sh. one worker per
                   package. one report.
interrogate:       /interrogate review this pr.
tdd:               /poteto-tdd implement
deslop:            deslop it before i commit
unslop:            can we unslop and tighten the new changes?
reflect:           /reflect that took too long. capture what we learned so the next run doesn't
                   repeat it.
correct:           /correct
show-me-your-work: /show-me-your-work keep a decision trail i can review when i'm back.
automate-me:       /automate-me
help:              /poteto-help which skill should i use to review this branch?

the poteto-agent and Comment Sicko subagents

pstack ships both complete personas inside the installed pstack-harness skill. npx skills delivers these payloads with the skills; it does not register native agents. /setup-pstack checks them and can install native registrations into an explicit project or user destination.

poteto-agent is a scoped delegate for one unit of a playbook step. It reads poteto-mode in full, including its inline Principles index, before work. Before each commit or amend, the delegate reads deslop in full, applies its rules to the proposed commit, and returns evidence of cleanup or a justified no-change result. The parent checks that evidence against the commits. The main conversation runs /poteto-mode and owns the plan. It spawns one delegate per unit and does not resume a delegate across phases. Comment Sicko, usually invoked through /no-comments, edits scoped comments and reports application-code refactor targets. it does not write application code.

The persona contract uses the native persona when the live agent catalog lists it, or supplies the complete persona to a generic delegate. Claude uses Markdown registrations, and Codex uses TOML. Hermes receives the full persona through delegation context. The normalized native names are poteto-agent and comment-sicko; Comment Sicko remains a supported logical alias. Model and effort choices still come from pstack's existing model policy.

A ready payload, an installed native file, and an agent loaded in the current session are separate states. Setup reports each separately. A skill's agents/openai.yaml sets its Codex invocation policy and, when it turns implicit invocation off, puts that skill in setup-pstack's claude code name-only listing; it does not register a subagent.

principles

twenty-four short skills, one principle each. poteto-mode indexes them inline and reads that index at task start. the standalone files are there so other skills can reference a principle by name, and so the index can point at the full rule for each.

all twenty-four principles

principle	group	rule
laziness-protocol	core	Bias toward deletion and the smallest change that solves the problem.
foundational-thinking	core	Apply before writing logic: choosing core types and data structures, sequencing scaffold-vs-feature work, asking what concurrent actors share. Get the data structures right so downstream code becomes obvious.
redesign-from-first-principles	core	Redesign as if the requirement had been a foundational assumption from day one, instead of bolting it on.
attack-the-premise	core	Apply when two or more fixes that share one premise have failed the same gate. Write the premise down and test it directly before you write another fix that assumes it.
subtract-before-you-add	core	Remove dead weight, redundant validators, and stub references first, then build on the simpler base.
minimize-reader-load	core	Count layers between question and answer, and hidden state in the reader's head; collapse one-caller wrappers and shrink mutable scope.
outcome-oriented-execution	core	Apply during planned rewrites and migrations with explicit phase boundaries. Converge on the target architecture; don't preserve smooth intermediate states with throwaway compatibility code.
experience-first	core	Choose user delight over implementation convenience; ship fewer polished features over more rough ones.
exhaust-the-design-space	core	Build 2-3 competing prototypes and compare side by side before committing.
build-the-lever	core	Apply to any non-trivial work, not just bulk work: edits, migrations, analyses, checks. Build the tool that does it or proves it (codemod, script, generator, or a skill your subagents follow) instead of working by hand. The tool is the artifact a reviewer can rerun.
model-the-domain	architecture	Encode the domain in a structure instead of scattered conditionals.
boundary-discipline	architecture	Concentrate guards at system boundaries (CLI, config, network, external APIs); trust internal types and keep business logic in pure functions.
type-system-discipline	architecture	Make illegal states unrepresentable, brand semantic primitives, parse external data at boundaries, refuse to lie to the compiler, exhaust variants, derive from authoritative schemas.
make-operations-idempotent	architecture	Converge to the same end state regardless of partial prior runs.
migrate-callers-then-delete-legacy-apis	architecture	Migrate callers and delete the old API in the same wave instead of preserving compatibility layers.
separate-before-serializing-shared-state	architecture	Eliminate the sharing first; serialize structurally only when one shared writer is a real invariant.
prove-it-works	verification	Apply after completing a task, before declaring done. Verify against the real artifact (run the feature, read the actual value, inspect the diff), not a proxy, self-report, or 'it compiles.'.
fix-root-causes	verification	Trace each symptom back to the first place the system went wrong and fix it there. A guard is a fix only when the state it handles is legitimate.
sequence-verifiable-units	verification	Apply to multi-step work (sweeps, migrations, runs of similar edits) and to how you stack commits and PRs. Break work into small units that each end in a verifiable state, check each before the next, and order delivery so the sequence proves itself to a reviewer.
test-behavior-not-implementation	verification	Apply when you write, change, or keep a test. Assert what the code's users can observe, so the test fails when that behavior breaks and keeps passing when only the internals change.
explain-the-number	verification	Apply before you trust, report, or act on a number you measured: a speedup, a regression, a throughput, a latency, or an eval result. Find what limits it, and rule out that it measured something other than the work you think.
guard-the-context-window	delegation	Route bulk to subagents; keep summaries in the main thread, not raw payloads.
never-block-on-the-human	delegation	Proceed, present the result, let the human course-correct after the fact; reserve confirmation for irreversible actions.
encode-lessons-in-structure	meta	Encode the rule as a lint, metadata flag, runtime check, or script instead of more text.

differences from upstream

upstream leans on cursor-only pieces. this port swaps them for self-contained equivalents:

• /deslop (upstream's cursor-team-kit) → the port-owned /deslop skill. its rules draw on three MIT-licensed skill sets, credited in skills/deslop/CREDITS.md.

• control-cli / control-ui (also cursor-team-kit) → the project-local verify-<app> skill generated by /create-verification-skill.

• cursor's built-in /create-skill → the authoring-a-skill playbook. if your CLI ships a built-in /babysit, the babysit playbook supersedes it for pr-status requests.

• invocation gating works per-CLI, and no skill under skills/ sets upstream's disable-model-invocation, because claude code's Skill tool then refuses the skill even when another pstack skill names it. every gated skill ships agents/openai.yaml with policy.allow_implicit_invocation: false, which codex honors, so $skill still works and implicit triggering is off. on claude code, /setup-pstack lists the same skills by name only (skillOverrides in ~/.claude/settings.json), so they load when you type /name or a pstack skill tells the agent to use them, never from their description. an agent that lists the skills folder can still open one by its folder name.

PORTING.md has the full substitution map.

why are there no planning skills?

your CLI already has a plan mode which works great with pstack. but personally, i don't believe in planning. the best spec is code. if you do want to make a plan, /poteto-mode covers it, but it's not a default.

make it yours

poteto-mode is my style. you may not want exactly that.

type /automate-me. it mines your recent transcripts, drafts a <your-name>-mode skill from how you've actually worked, and routes through pstack underneath. you keep pstack as the base and end up with your own routing skill alongside poteto-mode.

models are configurable too. type /setup-pstack. it detects the models you have access to and writes a small config file mapping each role (code, judgment, the review panels) to a model, user-level at ~/.agents/pstack-models.md, with an optional per-repo override at .agents/pstack-models.md. every skill resolves the layered config through check-models-config.py --resolve and falls back to sensible defaults when no line matches, so you override only what you want. a role can pin a reasoning effort with model@effort, and ## codex, ## claude-code, ## grok, or ## hermes sections hold per-CLI picks in the same file. for each role the first match wins, in this order: the per-repo section for your CLI, your section, the per-repo flat line, your flat line, then the shipped default. so a per-repo line written for claude never overrides your ## codex line for that role. one config serves every CLI. a model a harness can't use just means inherit-parent there, and a claude alias becomes a gpt-6 model on codex and grok-4.7 on grok build.

a config written before the panels shrank to three entries still lists four panel entries. delete those panel lines, including any under ## codex, or delete the file, then run /setup-pstack again. a rerun keeps any role you changed, whether its model, effort, panel list, alias, or harness section.

automations

pstack also ships a dormant benny automation pack. benny triages slack issue reports, then reproduces confirmed bugs with real ui evidence and may prepare a small draft fix. its files are not registered as slash skills.

to set it up, point your agent at FOR_AGENTS.md. setup copies the pack into the target repository at .agents/automations/benny/, enables pstack there for shared skills, and keeps user configuration outside the copied pack. benny needs a scheduled agent runner (claude code scheduled agents, or any cron-driven job that invokes your CLI).

contributor checks

CI uses Python 3.12 and Bun 1.4.0. For the git hooks, create the local virtual environment in the main checkout, install the skill-ci command, and install the hooks. The gate selects its interpreter separately, as described below.

python3 -m venv .venv
uv tool install git+https://github.com/mdsmithaustin/skill-ci.git
lefthook install

Run the local gate tiers from the repository root:

tools/gate-check.sh lint
tools/gate-check.sh test

The lint tier checks cross-suite references, the mode entry byte budget, personal home paths, the generated subagent bundle, the promise ledger, the shipped models config, and skill reference spelling (tools/test_skill_references.py). The skill reference spelling scope and exceptions are documented in PORTING.md. skill-ci check runs the shared skill checks, as described below. The test tier runs the tools, promise, and setup-pstack unit suites, then installs the poteto-mode dependencies with the frozen lockfile and runs its Bun tests and typecheck. Each check belongs to one tier, except skill reference spelling and the repository mode entry byte-budget check, which the tools unit suite also runs. The script runs every check in the selected tier, prints a PASS or FAIL line for each, and exits nonzero if any check fails. Unit suites and Bun tests must report tests, not a zero-test success.

python3 tools/check-personal-paths.py scans the names and current contents of every Git-tracked file for concrete account names below /Users/<account> or /home/<account>. It scans symlink target spelling without following the link, skips contents containing NUL bytes as binary, and decodes other bytes with UTF-8 replacement. Filenames are checked even for binary files. Exact file-scoped content exceptions cover existing synthetic fixtures. An unused exception fails the default working-tree check used by the gate and CI. Index and pushed-tip modes suppress exact known synthetic matches without requiring every fixture to exist in each snapshot. Diagnostics redact account names and identify the file and line without printing source contents. Line 0 identifies a filename finding. Exit 1 means a personal path was found. Exit 2 means file acquisition or exception validation failed, or no tracked text files were inspected. A successful scan exits 0 and reports the number of tracked text files checked. Pre-push exits 0 without scanning when Git supplies no nondeleted local tips. The required CI skills job runs this checker explicitly, alongside the shared skill-ci checks.

The script needs neither mise nor the main checkout's .venv. It selects PSTACK_GATE_PYTHON when set to a Python executable, then $HOME/.local/share/mise/installs/python/3.14.7/bin/python3.14, then uv on PATH with Python 3.12. This gate runner choice uses the environment's HOME. The native evaluators derive their confined runtime paths from the operating system account database, as documented in the promise suite README. The native version pin is deliberate because Python 3.12 fails the native fsmonitor control on the reviewed host. The test tier also needs Bun, rg, jq, gh, and openssl on PATH. mise run gate-lint and mise run gate-test wrap the same script.

.no-mistakes.yaml runs the lint tier and then skill-ci check as the gate's Lint step. It leaves the Test step to the pipeline's targeted checks, because no-mistakes reserves commands.test for targeted validation of the change, not a full suite that mirrors CI. Run the test tier yourself before a large change. GitHub CI remains authoritative and additionally runs the Docker oracle and maintained canon suites, the npx installation probe, and the Linux worktree-audit job. Those checks stay outside the local gate tiers. CI cancels superseded pull-request runs of lint.yml and skill-checks.yml; pushes to main never cancel. The gate fills PR bodies from .github/pull_request_template.md through pr.template, omits intent from them, keeps a minimal appendix with the risk line and head attestation, and protects .github/workflows/** and .github/rulesets/** from automatic repairs.

To reproduce the Docker suites and installation probe manually, use the commands below. Follow the application and grader instructions for their prerequisites.

docker pull python:3.12-slim@sha256:229a2c5bfa27522db7815ea81f9bed70af17ccb9de9fc7ad142b1877b5830d36
(cd evals/verify-commands/oracles && python3 -m unittest -v test_check_plan)
(cd evals/canon && python3 -m unittest -v)
.venv/bin/python tools/probe-subagent-install.py

Each command exits nonzero on failure. Each unittest command must report tests, not a zero-test success.

The pre-commit hook runs the cross-suite-reference and personal-path checks with the main checkout's .venv/bin/python, from any worktree, and skill-ci check --fast, which runs the frontmatter, trigger declaration coverage, content, and staged PII checks. The personal-path pre-commit check uses --source index to inspect staged blobs, even when unstaged edits differ. The pre-push hook uses --source pre-push with Lefthook stdin forwarding to inspect each nondeleted local tip supplied by Git, and runs the full skill-ci check. It scans tip snapshots, not published base history. The default working-tree mode remains the gate and CI interface. For the full skill checks, hook configuration check, and whitespace check:

skill-ci check
lefthook validate
git diff --check

Each command exits nonzero when its check fails.

evals/promises/ checks that the port keeps the user guide's promises on all four harnesses. Its README covers the ledger audit, the live runs, and how to classify a guide sentence that an upstream sync adds.

Behavioral eval manifests and their oracles live at the repository root under evals/<skill>/, never inside a skill directory. npx skills copies a skill directory verbatim to every consumer and offers no exclude mechanism, so eval material placed there would ship to everyone who installs the skill. tools/test_eval_artifacts.py fails if an evals or eval-runs directory appears under skills/. The same reasoning keeps tests out: they live under tests/, mirroring their path under skills/ (tests/skills/poteto-mode/scripts/ and tests/skills/setup-pstack/scripts/), and the same test fails if a tracked file under skills/ matches a test-file pattern. The Bun and typecheck scripts in skills/poteto-mode/scripts/package.json reach into tests/. The .gitignore rules **/evals/**/runs/ and **/eval-runs/ keep raw run transcripts out of git wherever a run writes them.

.skill-ci.toml pins the skill-ci release used by GitHub Actions, the git hooks, the no-mistakes Lint step, the mise tasks, and the manual development comparisons. The skill-ci command reads that pin and runs that version from any checkout or worktree, and it needs uv on your PATH. skill-ci check runs the frontmatter and trigger declaration coverage check, the content check with tools/skill-content-conventions.json, and the whole-tree PII scan. evals_dir points it at the manifests, so for every evals/**/shared-benchmark.json it also runs skill-benchmark validate --strict-leakage and then skill-benchmark audit-manifest --fail-on-blockers --strict-judge, skipping the audit when the manifest has no cases. It runs the harness that the pinned skill-ci release installs, never whatever skill-benchmark is on your PATH.

mise.toml adds a one-line task for each check and run command, such as skill-check for skill-ci check. A mise older than 2026.8.9 asks you to run mise trust once.

mise run skill-lint
mise run skill-validate
mise run skill-audit

Local runs and CI read the same pin, and each run prints skill-ci <version> (<commit>) first, so the two logs show the commit they ran. skill-ci update moves the pin to the newest release tag.

The pinned skill-ci v1.4.0 runner validates declared skill_paths. Both skill-ci validate and skill-ci audit reject a manifest if an entry does not exist inside the manifest's skill root. tools/test_eval_artifacts.py also fails when any manifest under evals/ names a path that is not a file.

skill-audit is stricter than CI on one point. CI skips audit-manifest for a manifest with no cases, and the task audits every manifest it finds, so an empty manifest fails locally and passes in CI. Nothing in this repository has one today.

skill-ci trigger <skill> and skill-ci run <skill> spend model budget on your own logins and never run in CI. Both write to a new directory under <checkout>.eval-runs/<skill>/, beside the checkout. Pass --out to write under evals/ instead. skill-ci refuses an output directory inside the skill package.

skill-ci run skills/unslop --out evals/unslop/runs/$(date +%Y%m%d-%H%M%S)

evals_dir in .skill-ci.toml points every command at evals/. Delete it and check, validate, and audit search skills/, find no manifest, and still exit 0, so tools/test_eval_artifacts.py pins its value.

tools/skill-trigger-cases.json checks deterministic trigger declaration coverage. It confirms that every shipped skill has a realistic request, literal description anchors, and the expected invocation policy. implicit_allowed is false exactly for the skills whose agents/openai.yaml sets allow_implicit_invocation: false. It does not measure model-routing accuracy.

license

MIT