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

write-issue

Use when creating or drafting a GitHub issue, turning a bug, idea, request or audit finding into an issue, or checking whether an existing issue is ready to plan or build from.

reyxdz · 已有静态检查记录

安装与使用

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

npx skills add reyxdz/going-dark --skill write-issue

技能说明


name: write-issue description: Use when creating or drafting a GitHub issue, turning a bug, idea, request or audit finding into an issue, or checking whether an existing issue is ready to plan or build from.

Write an issue

What this skill is for

An issue is a specification. Someone who never saw your conversation must be able to plan and build from it without guessing. That means:

  • the problem is concrete, with real file names and real numbers;
  • every decision says who made it and when;
  • what is in scope and what is not is written down;
  • "done" can be measured.

You will: collect facts, sort the open points, ask the owner, write the draft from a fixed template, show it, and only then file it on GitHub.

To check an existing issue instead of writing one, do Step 1, then go straight to "Before you send" and answer every question about that issue. Report each "no" with what to add.

How to follow this file

  1. Do the steps in order, from Step 1 to Step 9. Do not skip a step. Do not change the order.
  2. Each step has three parts:
    • Do — what to do. Commands are shown in code blocks. Replace every <word in angle brackets> with the real value and remove the brackets.
    • Check — what must be true before you go on.
    • If not — what to do when the check fails.
  3. When this file says STOP, stop working, send the message it gives, and wait for the answer. Do not go on until the person answers.
  4. Never invent a fact. Every file name, line number, number, name and date you write must come from the person, the code, or a command you ran during this task.
  5. When you cannot check a fact — no access to the repository, a command fails, the file does not exist — you may still write it if the person told you, but put *(unverified: <why>)* right after it. Never write a number or a file path you made up.
  6. The project's own rules win. If a file you read in Step 1 says something different from this file, do what the project says, and tell the person: The project's rule "<quote>" replaced this skill's rule "<quote>".
  7. Never create the issue on GitHub until the person has seen the full draft and said yes (Step 8).
  8. The examples in this file (numbers, copy, file names) only show the shape. Never reuse them as values for a real issue.

Words used in this file

WordMeaning
ownerThe person who decides what is built. Step 1 shows how to find them.
owner's handleThe owner's GitHub username, for example reyxdz.
bugSomething that worked, or was meant to work, and does not.
featureSomething new that people will be able to do.
technical issueA change users do not ask for directly: speed, size, cost, security, cleanup. A complaint like "the list is slow" is a technical issue.
owner questionA question whose answer changes what users get, what it costs, or the risk. Step 4 lists them.
technical callA choice about how to build it, which you make yourself and write down. Step 4 lists them.
decision record (ADR)A short document, usually in docs/decisions/ or docs/adr/, recording a choice that is expensive to undo.
expensive to undoUndoing it later would need a data migration, break users or other apps, cost money, or change a public URL or API.
sets a precedentIt is the first of its kind in the project, and later work will copy it (the first paged list, the first file upload, the first background job).
copyAny text users will read: buttons, messages, errors, empty pages.
scratch folderA folder outside the repository for temporary files. Use the one your tool gives you (often called a scratchpad or temp folder). If it gives none: /tmp/going-dark on macOS and Linux, %TEMP%\going-dark on Windows. Create it if it is missing.
todayToday's date as YYYY-MM-DD, from your environment. If you do not know it, ask.

Step 1 — Read the project

Do:

  1. List the project's rule files and read every one that exists:
    git ls-files AGENTS.md CLAUDE.md GEMINI.md CONTRIBUTING.md .github/copilot-instructions.md "docs/explanation/*" "docs/guides/*"
    
  2. Read the issue templates, if any:
    git ls-files ".github/ISSUE_TEMPLATE/*"
    
  3. Read the three most recent issues, to copy their style:
    gh issue list --state all --limit 3 --json number,title,labels,body
    
  4. List the labels that exist:
    gh label list
    
  5. List the decision records:
    git ls-files "docs/decisions/*" "docs/adr/*"
    
  6. Find the owner. In the rule files, look for "owner", "maintainer", "only … merges". Also read .github/CODEOWNERS if it exists. If you find a GitHub handle, that is the owner's handle. If not, the owner is the person asking you; you will ask for their handle in Step 5.

Check: you know the owner (or will ask), the labels, and the style of recent issues.

If not: for each thing you could not read, note it. Anything you later write that depends on it gets *(unverified: …)*.

Step 2 — Decide what kind of issue it is

Do: pick exactly one, using the words table: bug, feature or technical issue.

Check: you picked one, using the first rule that matches:

  1. It was meant to work and does not ("broken", "never arrives", "error", "stopped working") → bug.
  2. It works, but too slowly, too big, too costly, or needs cleaning up → technical issue.
  3. People will be able to do something they cannot do now → feature.

Step 3 — Collect the facts

Do:

  1. Where in the code. Find the exact file and line:
    git grep -n "<function, route or text the person mentioned>"
    
    Write file:line from the output, for example backend/src/routes/offers.ts:42. If you cannot search the code, use what the person said, exactly as they said it ("near lin
阅读完整来源 ↗