fix(skill-authoring): make goal-first the default when authoring and reviewing skills

[tmchow]

Summary

Agents authoring or reviewing skills in this repo kept needing the same reminders: state the condition instead of the command, don't build a state machine in a skill that delegates the work, and stop patching a block case by case. The doctrine already existed — in portable-agent-skill-authoring.md, and as step 5 of "Applying Feedback to Skills" — but it did not fire at the moment of authoring or review. #1385 is the measured cost: six prescribed-command revisions of one ship gate, each wrong for some git configuration, none of 22 review threads finding the intent unclear.

This PR moves the idea to where it fires, and makes "delete the commands" a legitimate review outcome. It adds no new rules beyond what #1386 recorded; it replaces placement.

What changes

• AGENTS.md "Cross-Model Skill Authoring" now opens with one posture sentence — a skill hands the agent the goal, the done condition, the safe failure direction, and the non-derivable facts; when you find yourself adding cases to make a block hold, name the condition they proxy for — followed by two citable rules: prescribe a mechanism only where it is owned and repeated case-specific repair is the defect signal, the latter with an explicit reviewer clause. The old accretion step in "Applying Feedback" collapses to a pointer, so the region ends smaller, not larger.
• ce-code-review reviewer template — a deletion or restatement is now an admissible concrete suggested_fix when a prescribed step in agent-instruction prose fails under some state and the mechanism belongs to a component the prose delegates to. Previously the "always propose a concrete fix under imperfect information" rule pushed reviewers toward the next corrected command — the loop fix(ce-debug): stop asking at the handoff, stop shipping unoffered work #1385 ran.
• Authoring guide compact review prompt — item 5 carries the ownership clause for people who load the guide instead of AGENTS.md.
• git-workflow-skills-need-explicit-state-machines.md — Prevention is scoped to skills that own git mechanics, with an explicit negative for delegators. docs(solutions): record why skill gates state conditions, not git commands #1386 records this doc being cited against the ship-gate simplification; left unscoped it beats the new posture the next time someone greps "state machine".

Deliberately not done: a PR-template checklist (templates are prompts, not gates, and gh pr create --body bypasses them) and a mechanical state-machine detector (it cannot tell an owned mechanism from a leaked prescription).

Validation

• Behavioral check, fresh contexts on Claude Code and Codex CLI with the revised AGENTS.md section as instructions: a delegating-skill fixture (ship gate, "@{u} errors with no upstream" finding) produced a stated condition plus safe failure direction on both hosts and refused the corrected command; an owning-skill fixture (ce-commit-push-pr PR detection, fork-collision finding) kept and refined the mechanism on both, citing ownership. 4/4.
• Independent cross-model review of the diff (Codex, Grok): both proceed after two edits, both applied — the posture clause was categorical ("enumerating cases") and could license deleting legitimate coverage menus, so it now triggers on repair rather than enumeration; a stale "Three rules" count in the reviewer template became four.
• bun run test 3102 pass / 0 fail; release:validate clean.

Related: #1385, #1386.

Security Disclosure

No security-relevant changes.

Agent Disclosure

• Model: Claude Code · claude-fable-5

[cursor]

PR Summary

^{Cursor Bugbot is generating a summary for commit 3791bbe. Configure here.}

[tmchow]

Îf