agentleFS
tstraub89tstraub89/canon-ai/.claude/skills/canon-inline-review/SKILL.md

canon-inline-review

Skill3 starsChanged 9 days agoMITView on GitHub

Use when the human wants an independent cross-review of below-pipeline work - uncommitted changes, one commit, or a whole branch before a PR. Triggers on "/canon-inline-review", "review my uncommitted changes", "codex review this", "cross-review before I commit", "review the last commit", and "review my branch". Not for spec compliance (use canon run / --reroute) or the pipeline's own code_review phase.

The file

We split this skill into the rules it gives an agent

12 rules. About 0 are common, 6 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill to drive an independent second-model review of below-pipeline work.

    line 10
  2. Distinctive:

    Before committing or before opening a PR

    line 16
  3. Distinctive:

    Follow this as a guided procedure.

    line 26
  4. Very specific:

    Read operator intent first from the request, the conversation, and $ARGUMENTS.

    line 28
  5. Very specific:

    Target — specific commit: if intent names a commit SHA, "last commit", HEAD, or a HEAD~N reference, resolve it to a SHA with git log -1 …

    line 29
  6. Very specific:

    Target — whole branch: if intent names a branch or says "whole branch" / "pre-PR", use --base <branch>.

    line 30
  7. Very specific:

    If the request is still genuinely ambiguous after reading intent, use AskUserQuestion rather than guessing.

    line 36
  8. Distinctive:

    Run one read-only guard only: git status --porcelain.

    line 37
  9. Very specific:

    If the resolved target reviews the uncommitted tree — literal --uncommitted or prompt-only mode (which defaults to the uncommitted tree) — …

    line 39
  10. Very specific:

    Treat codex exec review --help as the version-pinned source of truth for the live flag set.

    line 42
  11. Distinctive:

    If there are findings, report the important ones first and keep the summary short.

    line 68
  12. Distinctive:

    If there are no findings, say so in one line.

    line 69

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

canon-inline-review

Use this skill to drive an independent second-model review of below-pipeline work. It is for correctness and quality bugs in inline edits and trivial fixes that are too small for a canon task.

When to use

  • Non-trivial inline edits
  • Trivial fixes too small to justify a canon task
  • Before committing or before opening a PR

Claude never self-reviews its own inline code. Use this skill to invoke Codex as the independent reviewer.

This skill needs the Codex CLI. If the project runs CANON_PROVIDER=claude and has no Codex, review below-pipeline work in a separate Claude session (fresh context, diff only) instead.

Scope bound: this catches correctness and quality bugs across models. It is not a spec-compliance gate; anything with acceptance criteria goes through canon run / --reroute, not this skill.

Target-selection contract

Follow this as a guided procedure. The skill determines the target from operator intent; it does not infer intent from git history.

  1. Read operator intent first from the request, the conversation, and $ARGUMENTS. Resolve the target and any steering text as two separate things — for the default (uncommitted) target they are not mutually exclusive, and dropping the steering is the most common way this skill goes wrong.
    • Target — specific commit: if intent names a commit SHA, "last commit", HEAD, or a HEAD~N reference, resolve it to a SHA with git log -1 --format=%H <ref> or git rev-parse <ref>, then use --commit <SHA>.
    • Target — whole branch: if intent names a branch or says "whole branch" / "pre-PR", use --base <branch>. Resolve the repository's default branch from git symbolic-ref --short refs/remotes/origin/HEAD and strip the origin/ prefix; if that command exits non-zero (e.g. fresh clone or no origin/HEAD set), fall back to main.
    • Target — uncommitted tree (the default): use this when intent says "uncommitted" / "before commit" or gives no other target signal.
    • Steering text: any instruction about what to look for (e.g. "verify no behavior change", "watch for stale-closure risk") rather than which diff to review. It must reach the run:
      • For the uncommitted target, pass the steering as the positional PROMPT — prompt-only mode defaults to the uncommitted tree, so a bare prompt covers both the target and the steering. Do not fall back to bare --uncommitted when steering exists; that silently drops it and produces a cold review.
      • For a --commit or --base target, the selector and a prompt cannot be combined (see Mutual exclusivity). Keep the selector for scope correctness and state in your summary that the steering could not be passed to this run.
    • With no steering text and an uncommitted target, use bare --uncommitted.
  2. If the request is still genuinely ambiguous after reading intent, use AskUserQuestion rather than guessing.
  3. Run one read-only guard only: git status --porcelain.
    • This check exists only to prevent an empty working-tree review. It must not be used to infer whether the operator meant a commit or a branch.
    • If the resolved target reviews the uncommitted tree — literal --uncommitted or prompt-only mode (which defaults to the uncommitted tree) — and the tree is clean, do not run an empty review. Reconcile from the conversation or ask which target the operator wants.
  4. State the chosen target and the scope it covers before running, then run the review.

Treat codex exec review --help as the version-pinned source of truth for the live flag set. Do not freeze the flag list in this skill when the installed CLI can tell you the current forms.

Mutual exclusivity

A target selector (--uncommitted, --commit <SHA>, or --base <branch>) and a positional PROMPT cannot be combined. The CLI rejects that pair with cannot be used with '[PROMPT]'.

The practical consequence: the only target you can steer is the uncommitted tree. Prompt-only mode (codex exec review "<PROMPT>") defaults to the uncommitted tree, so a bare prompt steers and targets the working tree at once — never add --uncommitted alongside it. A --commit/--base review cannot carry steering; if intent asks for both, the selector wins and you note the steering was dropped.

Running the review

codex review is the shorthand for codex exec review. Use the shorthand when you want the concise form; treat codex exec review as the documented form.

Run non-interactively with the chosen selector, and always add -o <path> (a fresh path from mktemp) to capture the agent's final response in isolation. Raw stdout is the full exec transcript — a session banner, config block, and every shell command the review itself runs, with the actual review text buried somewhere inside — not just the final message. -o writes only that final message, cleanly:

  • codex exec review --uncommitted -o <path>
  • codex exec review --commit <SHA> -o <path>
  • codex exec review --base <branch> -o <path>
  • codex exec review "<PROMPT>" -o <path> to steer an uncommitted review (prompt-only; do not add --uncommitted)

Do not pipe stdin into the command. The review subcommand already runs non-interactively. A successful review always produces text in the -o file — even a clean result is a summary sentence, never nothing. Treat an empty or missing -o file as a failed invocation, regardless of exit code: check exit status and stderr for the cause, surface the failure, and stop. Never read empty output as "no findings."

Reporting findings

Only proceed here if <path> (the -o file) is non-empty. Read it for the review content. Do not grep, parse, or otherwise inspect raw stdout — it's the full transcript, not the result, and findings can be anywhere inside it. Summarize the file's content concisely. Group findings by severity, then stop. Do not dump raw output into the session.

  • The -o file is already formatted prose, not JSON: a summary line, then each finding as Review comment: - [P0]-[P3] <title> — <file>:<line> with its body below. Relay the existing [P0]-[P3] tags and summary line as-is — don't re-derive severity from wording.
  • If there are findings, report the important ones first and keep the summary short.
  • If there are no findings, say so in one line.

Gotchas

  • --commit <SHA> reviews only that commit's diff, not the cumulative branch state.
  • There is no multi-SHA or commit-range form.
  • --uncommitted excludes already-committed work.
  • A clean working tree makes --uncommitted a no-op.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.