跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

write-ai-ready-issue

Use when the user wants to turn the current discussion into a GitHub Issue, wants a task done without watching it, asks whether an Issue is clear enough for an AI agent to deliver, or wants to split a big task into several Issues. Reads the repository read-only first, drafts only what the person asked for, runs an independent fidelity pass, and hands the Issue to Orbi when Orbi already delivers the target repository.

orbi-build · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add orbi-build/orbi --skill write-ai-ready-issue

技能说明


name: write-ai-ready-issue description: Use when the user wants to turn the current discussion into a GitHub Issue, wants a task done without watching it, asks whether an Issue is clear enough for an AI agent to deliver, or wants to split a big task into several Issues. Reads the repository read-only first, drafts only what the person asked for, runs an independent fidelity pass, and hands the Issue to Orbi when Orbi already delivers the target repository.

Write an ai-ready Issue

Turn the person's request into a GitHub Issue an AI agent can deliver without supervision: grounded in the code that exists today, and asking for exactly what the person asked for. This works for anyone, whether or not they use Orbi; only the final hand-off step needs Orbi. The bar for a written Issue is the 12 factors at https://aiready.sh/.

Prior art this skill borrows from: superpowers brainstorming (size the task before writing), mattpocock grilling (sharpening a request with pointed questions), Spec Kit specify (at most three clarifications, assumptions written down), OpenSpec (WHEN/THEN acceptance), cc-sdd kiro-discovery (choose the route before writing).

Fidelity comes first

  • The User outcome restates the request in observable terms: what happens, for whom, when. It never grows the request.
  • Acceptance holds only the requested behaviour, plus at most one failure path of that same behaviour (what the person sees when it fails). Everything else — hardening, adjacent cleanup, "while we are here" — goes under Not included (suggestions), one line each.
  • A repository observation is evidence, never a requirement. How many lines the file has today, or which line the new one would become, is at most a line under Current state. For a preserve-and-append request (append one line, keep the existing content, change no other file), express the relative change — the sentence appended and the existing content untouched — not a total line count the person never named. A quantity the person stated ("exactly 17 lines") is their requirement and stays.
  • A request with two readings does not become the bigger reading. Take the smallest reading and record that reading under Assumptions (see Draft first).
  • Behaviour that already exists is reported as existing under Current state. Never write an acceptance item for making something work that already works.
  • Never widen the scope to make the Issue look complete.

Read before writing, read-only

Read the repository before drafting. Read-only means: no branch, no edit, no commit, no test run. Read the files the change would touch and their callers, the related tests, AGENTS.md, the docs that describe the current behaviour, and the open Issues and PRs that may already cover the request.

With a checkout, read the files directly. Without one, read through the GitHub API and search the tracker:

gh api repos/<owner>/<repo>/contents/<path> \
  -H "Accept: application/vnd.github.raw"
gh issue list --limit 200 --state all --search "<keywords>"
gh pr list --limit 200 --state all --search "<keywords>"

Never ask the person for a fact the code, docs or open Issues can answer, and never ask which of several reasonable options to take — that is a decision: take the default and record it under Assumptions (see Draft first).

Route first, in one line

Before drafting, state the route in one line, then follow it:

  • Already covered — an Issue, PR or docs page already does this: link it and stop.
  • No repository change needed — the request is about how the person works, not the repository: say so and stop. A docs or config change is a repository change, so it is not this route.
  • Small — one observable behaviour in a handful of files: short form.
  • Normal — everything else: full form.
  • Too big — more than one independently mergeable result: propose the vertical slices and draft EVERY slice, one Issue each, with their order (after) recorded. A request drafted as one Issue whose acceptance list covers independent deliverables is stopped by Orbi's pre-work check as "more than one outcome"; several Issues with an order is the deliverable shape.

Draft first

If reading the code shows the request cannot be done as asked (the file it is about is empty or missing, or the thing it would change does not exist), draft the nearest version of the request that the code can actually deliver, and make the first line of the Issue's Assumptions section say what you changed and why. Never write a draft whose only possible delivery changes no file.

Draft the Issue before asking anything. A disagreement the agent can settle itself is not a question — it is a line under Assumptions.

Every other disagreement — which library, font or place to use, what to leave out, how to word that deliverable version — is the same: choose the most reasonable default, write one line under Assumptions in each Issue saying what you chose and why, and draft.

Ask the person only when, after reading the code, the request itself still does not say what to build — it is empty or contradicts itself — and no deliverable default version can be written. Then ask at most three questions in one reply. Each question carries a header of one to three words naming the decision and 2 to 4 options, every option a label of one to five words plus one sentence of what it means or its trade-off. When one option is the reasonable default, it comes first and its label ends with (Recommended). Never add an "Other" option: the person's own answer is always allowed. Never say the person chose the recommended option.

Q1 — <question>
  - <label> (Recommended): <one sentence of what it means>
  - <label>: <one sentence of what it means>

A person answers them in their own words; the agent drafts from those answers.

Full form

Sections, in this order:

  • Request — the person's words, quoted verbatim.
  • `Current sta
阅读完整来源 ↗