AGENT SKILL

hitl

A human is looking at the work right now and talking while they look. Re-read the tree before answering, treat every observation as a finding to be captured rather than a task to start, and do not touch anything until they say go. Use for /hitl, and whenever the user is walking through recent changes, reviewing a diff, checking a running service, or firing off several reactions in a row — 'what is this', 'why did that change', 'that looks wrong', 'hold on'. Ends by proposing one plan for approval, never by having quietly acted.

License 许可
MIT
最近更新
2026-09-29
Stars
★ 0
Forks
0

01 前言 Front Matter

name
hitl
license
MIT
description
A human is looking at the work right now and talking while they look. Re-read the tree before answering, treat every observation as a finding to be captured rather than a task to start, and do not touch anything until they say go. Use for /hitl, and whenever the user is walking through recent changes, reviewing a diff, checking a running service, or firing off several reactions in a row — 'what is this', 'why did that change', 'that looks wrong', 'hold on'. Ends by proposing one plan for approval, never by having quietly acted.

02 资源文件 9

03 SKILL.md 正文

/hitl — a person is in the loop, and they are still talking

Vendor-neutral and machine-wide: this lives in ~/.agents/skills/, the cross-tool location Codex, Grok and Kilo read themselves; Claude Code gets a one-line pointer to it. It is written to be followed by any coding agent — Codex, Grok, Claude, Kilo, Cursor, Gemini, Copilot — or by a person. A project may append its own section below the end marker: the commands that re-read its state, or the place its deferred findings are expected to land.

The user is reviewing. They are looking at a diff, a running service, a screen of output, or a pile of recent commits, and they are reacting as they go. That is the situation this skill is for, and it has two failure modes that are both expensive.

Failure one: you act on the first thing they say. They point at something odd, you start fixing it, and by the time they have finished looking you have edited three files they had not got to yet, abandoned the thing they actually called you in for, and turned a five-minute review into a rabbit hole they now have to supervise.

Failure two: you let their observations evaporate. They notice four real problems while scrolling, you answer each one conversationally, and then the session moves on. The findings were the valuable part of the review and none of them survived it.

So: capture everything, act on nothing, until they say go.

Triggers

/hitl, and the shape of the conversation itself: the user is walking through recent work, pasting output, asking "what is this", "why did that change", "that looks wrong", "hold on", "wait" — several reactions in a row, without a clear instruction to change anything.

Ambiguity resolves toward capture. If you cannot tell whether something is an instruction or an observation, it is an observation. Ask at the end, not now.

1. Re-read before you answer anything

You are probably stale. Other sessions commit, the user edits in their editor, services restart. Answering a review question from what you remember is how you confidently describe code that no longer exists.

Before the first substantive answer, and again whenever the user implies something changed:

  • git status --short and git log --oneline -5 — the branch may have moved under you, possibly from another agent.
  • git diff / git diff --cached for what is actually uncommitted.
  • Re-read the specific file being discussed. Not from memory. Not from a summary you wrote earlier in the session.
  • If a running service is under discussion, confirm it is the one you think: check the port actually answers and that it is your service and not something else already on it.

Then make it current, before they look at anything. Compare the process start time to the newest commit touching the code it serves. If the process is older, restart it and say so. Do not ask permission for this and do not defer it: a review of a service running last hour's build produces findings about code that is already gone, and every one of them has to be re-derived later.

This is the single most repeated failure of this skill in practice. The symptom is always the same — the agent reports the staleness as a finding and carries on reviewing anyway. Reporting it is not enough. Making the running service match HEAD is a precondition of the review, not an observation within it.

Verify the restart took. A restart that silently failed is worse than no restart, because you now believe the opposite of what is true. On a single-port service the old process keeps the port and the new one exits; you read the old build's output and conclude the change is missing. So: stop the process that holds the port (find it by port, not by matching a command name — a pattern like pkill -f "myapp serve" also matches your own shell), confirm the port is free, start one instance, and confirm the new build is answering. Measured cost of skipping this: three restarts in a row that never bound, and a confident wrong conclusion drawn from each.

Then make the browser current too, if the review is of a web page. This is the half that gets missed, and it produces the most confusing possible symptom: the user says the feature is not there while the server is serving it.

A page reloads its HTML and reuses its scripts. If assets are referenced by a plain path — /static/app.js with no hash and no ?v= — a tab that already holds the module in memory can reuse it without asking the server anything, so a shipped change simply does not run. Before a sitting:

  • check the response headers on the app's own JS and CSS. cache-control: no-cache (revalidate before reuse) or a hashed/versioned filename means you are safe. An ETag alone is not enough — it only helps once the browser decides to ask.
  • if neither is present, fix it (one header on the static handler) rather than telling the user to hard-reload. A workaround they have to remember every time is a defect with extra steps.
  • either way, ask them to hard-reload once at the start. It costs a keystroke and removes the whole question from the sitting.

And confirm the fix is visible, not merely served. "The bytes contain it" is not the same claim as "a person can see it". Load the page the way they will, at their window size, and check the element is on screen and not covered — a correct component painted underneath a button is indistinguishable from a missing one.

The exception is a service the user has deliberately pinned to an old build, and they will have said so.

State it plainly when the ground moved: "Two commits landed since I last looked — abc1234 and def5678, both touching this file. Restarted; the service is now on def5678." That single line prevents a long argument about what the code says.

2. Every observation becomes a finding

Keep a running list, in the conversation, updated as they talk. Each finding:

  • What they observed, in their words where possible.
  • What you verified, if anything — and mark it clearly when you have not checked yet. A finding may legitimately sit unverified while the review continues.
  • Where it lives — file.py:42, a commit, a service.
  • Size, roughly: a one-line fix, a contained change, or something that needs its own session.

Re-state the list when it grows past about three items, or when the user pauses. That is the artifact of the review, and it is what makes it safe to say "not now" to any individual item.

Findings that turn out to be non-issues stay on the list, marked as checked and clear. The user asked about them for a reason and will otherwise ask again.

3. Answer, but do not start

While the review is running you may: read files, run read-only commands, check logs, look at a database, run existing tests to confirm a claim, and explain what you find.

You may not: edit files, write new ones, commit, install anything, restart a service for any reason but the staleness check in section 1, or start the fix for something they just pointed at — however small and however obvious. "That is a one-line fix" is not permission to make it.

Two exceptions, and they are narrow. Something actively destructive in progress (a bad command still running, data being overwritten) — say so immediately and loudly. And an explicit, unambiguous instruction to do a specific thing now ("fix that typo, then keep going") — do exactly that thing and return to reviewing.

If they interrupt the work you were doing before the review, that work is paused, not cancelled. Say what state you left it in, in one line, so nobody has to reconstruct it later.

4. Do not follow the interesting thread

Reviews generate tangents, and the tangents are often genuinely more interesting than the thing being reviewed. That is exactly why they are dangerous: you will have a good reason each time.

When something turns out to be deeper than it looked, it becomes a finding with "needs its own session" on it. You do not explore it now, even to "just check one thing" — checking one thing is how the review ends.

5. Converge — one plan, and wait

When the user signals they are done looking (they stop reacting, or say something like "okay", "so", "what do you think"), propose one plan. Not a menu of options, not a list of everything possible.

  • Findings, ordered by what you would do first, with the size of each.
  • What you propose doing now — usually a small subset, and often just one.
  • What you propose deferring, and where it will live so it is not lost: a TODO, an issue, a note in the project's own docs. Say which.
  • What you are not going to do, if you think something they raised is not worth acting on. Say why, once, without arguing.

Then stop and wait for approval. The whole point of the skill is that the human decides what happens next.

If several rounds of feedback contradict each other — and they will, because they were reacting in real time — surface the conflict rather than silently picking: "Earlier you wanted X; the last comment implies Y. Which?"

6. After approval

Once they approve, the skill is over — do the work normally. Two carry-overs:

  • Deferred findings must actually land somewhere durable before the session ends. A finding that exists only in scrollback did not survive the review.
  • If the approved work is significant, /handoff afterwards to sync docs and commit.

What this is not

Not a code review — you are not hunting for defects on your own initiative. Not an approval gate for routine work. And not a reason to be timid once permission is given: the caution is about when, not about how much.

04 同仓库更多 Skills

maxjbarfuss
maxjbarfuss/max_llm

train

Launch a new max_llm training run on both GPUs (RTX 4090 + RTX 3090 Ti) through torchrun DDP, resolving the TOML config by name or path. Use only when the user explicitly asks to start, launch or begin a run — "resume", "continue" or "keep training" mean the existing run; takes an optional config name or path.

★ 0
maxjbarfuss
maxjbarfuss/max_llm

serve-live

Before a person looks at a running service, make sure what is running IS the code in the checkout. Restart the services your change actually touched — not every service — and verify each is serving the current commit rather than merely answering; check the remaining dependencies are up without bouncing them. Use whenever you finish work a person will view in a browser or client, whenever you say a page or service is ready, after any commit that changes served code, and when asked to 'restart', 'refresh the services', 'is it live', or 'serve the latest'. Also covers waiting for lazy warm-up before calling a service ready.

★ 0
maxjbarfuss
maxjbarfuss/max_llm

review

Review a local change, branch, pull request, or stack for correctness, regressions, security, tests, and unnecessary complexity. Use when asked to review rather than implement.

★ 0
maxjbarfuss
maxjbarfuss/max_llm

regression-coverage

Reshape a slow or brittle test suite around observable user journeys and published contracts. Use when pruning tests, repairing weak smoke coverage, or addressing repeated feature regressions.

★ 0
maxjbarfuss
maxjbarfuss/max_llm

pr-babysit

Monitor selected pull requests and report or safely act on review, CI, mergeability, and stack state.

★ 0
maxjbarfuss
maxjbarfuss/max_llm

keel

Use a project's local keel code graph to assess change impact, find callers and reuse candidates, validate a plan, or check an edit. Applies only in a repository with a .keel/ directory; skip it for prose-only work.

★ 0