The engineer skill
One skill routes every kind of code task to a playbook, pull requests included, applies the engineering principles, and runs a comment pass before you see the diff.
engineer fires on its own when you ask for code work in a repo: "fix the duplicate write", "why is startup slow", "refactor the parser", "how does billing retry work". It reads the repo's AGENTS.md first, matches the task to a playbook, and copies that playbook's steps into its todo list, so a skipped step stays visible with its reason.
engineer help prints the whole menu in your terminal: every playbook grouped by what you're doing, an example ask and what you get for each, the principles you can steer by name, and the checks that run every time.
Playbooks
| You ask for | Playbook | What it holds you to |
|---|---|---|
| "How does X work?", "where should this live?" | how | Entry point to exit, the key types, where things live, the gotchas |
| "Why is X like this?" | why | Git history, PRs, and your own session logs as evidence, every claim labeled direct, supported, inferred, or unknown |
| A read-only question or a choice | investigation | A cited answer, verdict first |
| A bug | bug fix | Reproduce it on the real surface, binary-search the cause, failing test before the fix when it's cheap |
| New or changed behavior | feature | Name the data shape first; a throughput checkpoint before fan-out |
| Simplify, clean up, double-check | simplify | An audit against nine criteria, with findings ranked before anything changes. See Simplify |
| "Simplify and interrogate this branch", "get this ready for a PR" | simplify, then interrogate | The branch cleaned up, then reviewed the way a PR would be, verified defects fixed uncommitted, a PR description drafted |
| Refactor, reshape | refactoring | Pin the behavior first, subtract before adding, keep it only if the code got easier to read |
| "Why is this slow?" | performance | A baseline trace, eight strategy families, one change at a time |
| Push a metric to a target | hillclimb | A frozen harness, a stop rule, one commit per accepted win |
| A leak, spin, or glitch | runtime forensics | Capture the live signal and prove the mechanism before believing it |
| A profile or trace someone captured | trace forensics | Make it queryable, narrow to the hot frame, attribute it to source |
| Match two UIs pixel for pixel | visual parity | Baseline first, image diff to zero |
| "What could this break?" | blast radius | The one fact the change is safe because of, proven by running code |
| Settle a design by looking | prototype | A throwaway behind one switcher, a recommendation |
| Large or cross-cutting work | figure it out | A designed workflow, a falsifiable definition of done, a decision log |
| "Keep going until done" | autonomous run | A checkable finish line; a duration doesn't count |
| "Pause here" / "pick up where it left off" | pause safely, session pickup | A resume note; the prior trail treated as authoritative |
| Write a skill; test a skill change | authoring a skill, eval | Validated frontmatter and links; blinded candidates and judge |
| Give a repo a way to prove the app works | verification skill | A generated verify-<app> skill with a feature map, proven once before handover |
| "Review PR 142", "reply to the comments on my PR", "prep my PR for standup", "github sweep" | pr review, pr replies, pr walkthrough, github sweep | Verified findings and code-checked replies on one page, each with a Copy button. See Pull requests |
Every time
- The data shape is named before logic is written.
- A question you could answer by running something gets run, not asked.
- Every claim carries its evidence or a label: measured, inferred, or guess.
- "Done" means proven on the real artifact, with how far it was proven stated.
- Before any diff reaches you, a separate reviewer strips narrating comments and flags workarounds for a proper fix.
Simplify
you > engineer simplify the webhook handler
you > is this over-engineered?
you > engineer simplifyNamed with a target, simplify audits it end to end and changes nothing until you pick:
- Audits against nine criteria: elegance, simplicity, conciseness, accuracy, robustness, reliability, best practices, not over-engineered, and no regressions. The last one runs the repo's build and full test suite and checks every caller of what changed.
- Checks a list of common smells and hunts dead code, confirming each removal with a search first.
- Ranks the findings (critical, worth simplifying, nits), each with its
file:lineand the concrete change. - Applies what you pick with the refactoring playbook's guardrails: behavior pinned first, removals before reshapes, equivalence proven.
- Runs the host's built-in simplify pass over the applied diff, where the host ships one (Claude Code's
/simplify). Any edit it makes that doesn't trace to one of the criteria is reverted.
A bare engineer simplify (or "review the changes") takes this session's own work: the uncommitted diff plus its commits, re-read from disk. There it fixes the critical and worth-simplifying findings itself before reporting, and holds judgment calls and anything that changes intended behavior for you.
Explainers
An explanation worth more than a chat reply (an architecture walkthrough, a research note, how a subsystem works, a design an architect pass settled) ends in one HTML page beside a short markdown card in reports/. The page has a sticky top bar, a contents dropdown that follows the section in view, and the Auto / Light / Dark switch.
Every drawn diagram has a corner button that opens it full-window, with zoom (the buttons, + - 0 1, pinch, or ⌘-scroll) and drag to pan. The page can also carry pieces you click through: walkthroughs, UI mocks, reveal cards, rails and accordions.
The skill writes only the page's body, and a script checks it before wrapping it in the page: no scripts, styles, forms, event attributes or javascript: links, exactly one <h1>, every section opening with an <h2>, every diagram parsed, and no card or rail item without its panel. With scripts off, every panel shows.
Work that starts from a GitHub issue
An issue labelled accepted, on a repo a helpdesk queue raises its cards to, follows the default bug lifecycle. The skill offers to move it to in progress before the first edit. Once the fix is proven, it offers to set the issue's milestone to the release it ships in, and writes Fixes #<n> into the commit or PR.
Issues on any other repo are left to whoever runs them: no relabel, no milestone, and no Fixes #<n> unless you ask.
How to ask
you > the export writes two rows after a retry. repro first, then fix and verify.
you > architect the import pipeline before writing code. i care most about how callers use it.
you > blast radius of this diff
you > engineer help
you > review PR 142
you > engineer walkthrough 142 --rehearse
you > keep going until the checker reports zero old callers. log your decisions.Say the goal and what done means. Naming a sequence of skills usually reorders steps the playbook already sequences. "Don't change any code yet" keeps a request read-only.
Overview
How your agent works on code. A playbook per kind of task, 23 named principles, and review, verification, and release loops that never touch your remote on their own.
Principles
Twenty-three engineering principles, each a short rule with a test the agent runs on its own work. Name one to steer.