ai-draft
Skill1 starsChanged 4 months agoMITView on GitHub
Draft the 1–2 sentence PR replies for review items already worked to a checkpoint by /ai-next — both the AI queue and the human queue: one reply per resolved item, written in the PR author's voice from the item's Resolution line, saved into the state file for review — never posted. Use when the user says "/ai-draft", "draft the replies", or "write up the responses to the review comments".
In this repository21 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- ai-commentsSkill
- ai-nextSkill
- ai-postSkill
- call-traceSkill
- draft-prSkill
- dto-mappingSkill
- handoffSkill
- hum-commentsSkill
- jira-dcSkill
- meeting-summarySkill
- plan-from-issueSkill
- plan-nextSkill
- plan-reviewSkill
- plan-saveSkill
- pr-commentsSkill
- pr-statsSkill
- review-sessionSkill
- skill-builderSkill
- validator-generatorSkill
- templateSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 47
Find the state file(s): If a path or queue name (ai / hum) was passed, use it.
- Distinctive: line 101
1–2 sentences per reply. Hard cap: If it needs more, the Resolution line is doing too much — flag the item instead of writing a paragraph.
- Distinctive: line 103
Ground every reply in the item's Resolution: No claims that aren't in it.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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.
Files
AI Draft: write the replies for resolved review items
Review items — AI queue, human queue, or both — have been worked to their checkpoints; each carries a Resolution line saying what was done, the settled answer, or why not. Your job is to turn each resolved-but-undrafted item's resolution into a 1–2 sentence reply the PR author would post, save it into its state file, and show the batch for review. A draft is a draft: nothing gets posted here, and the decision in the Resolution is settled — you write it up, you don't re-argue it.
Configuration (set per adopter — must match the comments skills)
| Key | Default |
AI_STATE_DIR | docs/plans/ai-review/ |
HUM_STATE_DIR | docs/plans/hum-review/ |
When to use this skill
- "/ai-draft" after /ai-next has taken items to their checkpoints
- "Draft the replies" / "write the responses to the review comments"
When NOT to use this skill
- Items are still OPEN and undecided — work them with
/ai-nextfirst (drafting for an unresolved item is guessing). - Actually posting the replies, running the test gate, or watching CI — that's
/ai-post. - Free-form PR comments unrelated to the triaged AI items.
Steps
- Find the state file(s). If a path or queue name (
ai/hum) was passed, use it. Otherwise check bothAI_STATE_DIRandHUM_STATE_DIRfor files matching the current repo/PR and take every match — drafting covers both queues in one pass. None → say to run /ai-comments or /hum-comments and stop. - Read each file. Collect every item whose Status is FIXED, ANSWERED, DEFERRED, or
DECLINED and which has no
Draft reply:line yet. If there are none, report that (either nothing is resolved yet → point to /ai-next, or everything is already drafted → point to /ai-post) and stop. - Draft one reply per item — 1–2 sentences, hard cap, in the PR author's voice:
- Lead directly with the substance — what changed, the answer, or the reason — never a status prefix like "Done —", "Fixed —", or "Good catch —". A deliberate defer/decline may still open with the intent ("Keeping this as-is intentionally: …") since that IS the substance.
- FIXED items: state what changed, concretely ("switched to
import type { ComponentProps } from 'react', matching the shared components"). - ANSWERED items (human questions): the reply IS the settled answer from the Resolution — direct and code-accurate, pointing at the file/ticket/doc that settles it when one exists.
- DEFERRED/DECLINED items: state the real reason from the Resolution and, if the Resolution names one, when/where it will be handled instead.
- Plain first person, no AI attribution, no thanks-for-the-feedback filler. Replies to humans are replies to colleagues — same brevity, collegial register ("You were right — …" over "Declined.").
- Save each draft into its item as
- **Draft reply:** <text>. Touch nothing else in the file. - Show the batch in the format below and stop. If any OPEN items remain, note the count. Do not post anything.
Output format
Drafted 5 replies — 3 AI, 2 human (1 item still OPEN — /ai-next)
AI queue (<AI_STATE_DIR>/repo-pr-123.md):
1. [FIXED] paging guard never fails fast (Copilot)
→ "The loop now tracks seen page tokens and throws on a repeat instead of spinning to MAX_PAGES."
2. [DEFERRED] ChipButton type prop ordering (Copilot)
→ "Intentionally deferring this one: the page is read-only today so ChipButton never renders inside a form; the upcoming create-flow story will move `type` after the spread."
Human queue (<HUM_STATE_DIR>/repo-pr-123.md):
3. [ANSWERED] why a separate endpoint for selections? (jsmith)
→ "There's already a dedicated `/v1/selections` endpoint with BE-side filtering — the include on the category fetch couldn't sort, so I switched to it."
...
Review the wording, then /ai-post when ready.Rules
What to do
- 1–2 sentences per reply. Hard cap. If it needs more, the Resolution line is doing too much — flag the item instead of writing a paragraph.
- Ground every reply in the item's Resolution. No claims that aren't in it; if a Resolution is too vague to draft from, ask the user rather than embellishing.
- Match the register of the reviewer's finding — technical, specific, direct.
What NOT to do
- NEVER prefix a reply with a status word ("Done", "Fixed", "Good catch") — the reply text is the outcome; state it directly.
- NEVER post. No
ghcalls exist in this skill on purpose — /ai-post owns posting. - NEVER draft for an OPEN item — that's deciding the resolution by stealth.
- NEVER re-litigate the decision. The checkpoint said DEFERRED; you don't argue it back to FIXED in the wording.
- Don't overwrite an existing Draft reply unless the user asks for a re-draft.
Format discipline
- Output is the numbered draft list, nothing else — no restating each finding's history, no posting plan. Stop after showing the batch.
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
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.

