AgentLayer▸docs
Engineering

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 forPlaybookWhat it holds you to
"How does X work?", "where should this live?"howEntry point to exit, the key types, where things live, the gotchas
"Why is X like this?"whyGit history, PRs, and your own session logs as evidence, every claim labeled direct, supported, inferred, or unknown
A read-only question or a choiceinvestigationA cited answer, verdict first
A bugbug fixReproduce it on the real surface, binary-search the cause, failing test before the fix when it's cheap
New or changed behaviorfeatureName the data shape first; a throughput checkpoint before fan-out
Simplify, clean up, double-checksimplifyAn 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 interrogateThe branch cleaned up, then reviewed the way a PR would be, verified defects fixed uncommitted, a PR description drafted
Refactor, reshaperefactoringPin the behavior first, subtract before adding, keep it only if the code got easier to read
"Why is this slow?"performanceA baseline trace, eight strategy families, one change at a time
Push a metric to a targethillclimbA frozen harness, a stop rule, one commit per accepted win
A leak, spin, or glitchruntime forensicsCapture the live signal and prove the mechanism before believing it
A profile or trace someone capturedtrace forensicsMake it queryable, narrow to the hot frame, attribute it to source
Match two UIs pixel for pixelvisual parityBaseline first, image diff to zero
"What could this break?"blast radiusThe one fact the change is safe because of, proven by running code
Settle a design by lookingprototypeA throwaway behind one switcher, a recommendation
Large or cross-cutting workfigure it outA designed workflow, a falsifiable definition of done, a decision log
"Keep going until done"autonomous runA checkable finish line; a duration doesn't count
"Pause here" / "pick up where it left off"pause safely, session pickupA resume note; the prior trail treated as authoritative
Write a skill; test a skill changeauthoring a skill, evalValidated frontmatter and links; blinded candidates and judge
Give a repo a way to prove the app worksverification skillA 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 sweepVerified 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 simplify

Named with a target, simplify audits it end to end and changes nothing until you pick:

  1. 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.
  2. Checks a list of common smells and hunts dead code, confirming each removal with a search first.
  3. Ranks the findings (critical, worth simplifying, nits), each with its file:line and the concrete change.
  4. Applies what you pick with the refactoring playbook's guardrails: behavior pinned first, removals before reshapes, equivalence proven.
  5. 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.

On this page