file-issue
Skill48 starsChanged 2 days agoApache-2.0View on GitHub
Use when filing a GitHub issue for Spool with gh, retitling one, or splitting one into sub-issues; before the gh issue create call, not after the guard has flagged it.
13 other projects use a version of this.
Adopted by
Most recently taken up by
- Sma1lboy/rovetheir own version, first seen Nov 14, 2026
- rome-os/rometheir own version, first seen Nov 12, 2026
- pushprove-max/Commandecktheir own version, first seen Nov 8, 2026
- Termherd/termherdtheir own version, first seen Nov 8, 2026
- ultimatile/development-skillstheir own version, first seen Oct 20, 2026
- open-thoughts/OpenThoughts-Agenttheir own version, first seen Oct 8, 2026
Other versions13 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 13
- marin-community/marin★ 4.1ksame name
- rilldata/rill★ 3ksame name
- levy-street/world-of-claudecraft★ 2.3ksame name
- rome-os/rome★ 904same name
- open-thoughts/OpenThoughts-Agent★ 309same name
- Sma1lboy/rove★ 187same name
- mlz11/ClaudeNotifier★ 36same name
- pushprove-max/Commandeck★ 3same name
- bhagyamudgal/skills★ 2same name
- gssajith/claude-skills★ 2same name
3 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- amend-adrSkill
- code-review-and-qualitySkill
- credential-incidentSkill
- prove-event-workflowSkill
- releaseSkill
- review-fixSkill
- review-prSkill
- security-and-hardeningSkill
- security-reviewSkill
- visual-pr-shotsSkill
The file
We split this skill into the rules it gives an agent
2 rules. 0 are common, 0 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 12 edited versions we read keep these.
0
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 105
Keep the Part of line, because search reads it.
- Very specific: line 131
If needs-rewrite or needs-type is there, the comment names the rule.
“Common” is measured: kept by at least 6 in 10 of the 12 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
/file-issue — filing a typed issue
The rules are in docs/CONVENTIONS.md (issues and milestones, epic
children, one PR one issue, the issue standard, acceptance scenarios) and
ADR-0014. They hold whether or not this skill is loaded. This is the order
to apply them in. Each step names the check it keeps you out of, so a red
label is never the first time you hear of a rule.
1. Search first
gh issue list --state all --search "<two or three words>", and once more
with the words the operator would use. If an open issue covers it, comment
there instead of filing. For a security alert, search for its GHSA ID: an
advisory edit withdraws an alert and raises it again under a new number.
Prevents: a duplicate issue, which splits the history in two.
2. One responsibility
One issue carries one deliverable. If you need "and" to name what it delivers, file two. Work that needs several PRs is split into typed sub-issues before the first PR opens, each with its own owner and acceptance bar.
Prevents: the "one deliverable" rule of scripts/issue-rewrite.sh
(needs-rewrite), and a PR that Closes half an issue.
3. Pick the type, then use that form's headings
Choose one form in .github/ISSUE_TEMPLATE/. When you file with gh, add
that form's label yourself (exactly one type label), copy its ###
headings in order, and add a severity:* label too for a bug: gh
applies none of them. Feature: Problem statement, Coupling points,
Seams / ADRs touched, Proposed shape, Acceptance scenarios, Open questions,
Out of scope. For any other type, read the form; don't go from memory.
Prevents: needs-type from issue-guards, which flags an issue with no
type label, or one without its form's required headings or, for a bug,
its severity:* label (scripts/issue-headings.sh). The repo's hook
refuses such a gh issue create before it runs.
4. Title: one sentence in the operator's words
- At most 100 characters.
- The type decides what the title names (#1433):
- Feature or improvement: what the operator can now do or see, once it ships. "A loop in a team sees its team in its prompt", not "A loop in a team isn't told which team it is in", which reads as a bug.
- Bug: the broken behaviour, as the operator meets it. "A paused loop still answers in the group".
- Either way, the body still opens with what's wrong today (section 5).
- A product issue names no team process. Among what issue-guards flags:
an ADR number, slice, PR, "part of", item number,
#n, backticked symbol, snake_case name, or "web/hub/ui/backend/frontend/server/Go half". The full list is rule 1 ofscripts/issue-rewrite.sh. - One deliverable: no ", and", ", plus", ", then", "; " or " & ". If the
"and" stays inside one phrase, a maintainer can add the
one-deliverablelabel. Don't add it yourself. - A team-only issue (CI, tests, docs of record, repo guards) may open with
a Conventional
type(scope):and name its workflow or test. The length rule still applies.
Prevents: the title rules of scripts/issue-rewrite.sh. Before you file,
run it locally on the title and body:
bash scripts/issue-rewrite.sh [--scenarios] "<title>" < body.md.
5. First sentence: what is wrong today
The line under the first heading says what the operator sees or can't do
now, and names each surface that changes. It must not open with a
reference. Among what issue-guards refuses: Part of #n, ADR-, Split
out of, Follow-up to, Epic:, Parent:, slice N of, web half of
(and its kin), or a bare #n; the full list is rule 4 of
scripts/issue-rewrite.sh. Those go further down.
Prevents: the "opens with a reference" rule (needs-rewrite).
6. Acceptance scenarios for a feature or an improvement
Under the ### Acceptance scenarios heading, write one line per behaviour
the operator can check:
WHEN <situation> THEN <what is seen> (check: <tier-2 test | web test or screenshot | manual check the reviewer runs>).
The feature form requires them. The improvement form offers them, so
write them whenever the change is visible.
Prevents: the --scenarios rule (needs-rewrite on a new feature with
none), and a review finding on the PR for a scenario with no check.
7. Milestone and parent
Set --milestone to the ladder rung the work belongs to. For an epic
child, put Part of #n in the body (not first) and attach it natively:
gh issue create … --parent n, or later gh issue edit <child> --parent n.
Keep the Part of line, because search reads it. Part of #n names an
epic or a split parent, never an unsplit issue.
Prevents: an issue with no rung on the ladder, and a child that doesn't show in the epic's sub-issue list.
8. Body hygiene
Name people and loops without an @, and end the body with
— Name · Role. Write the body to a file and pass --body-file. Never
copy text from a community issue, and never write a credential (at most
8 characters, then …).
Prevents: the repo's PreToolUse hook (gh-body-guard.sh), which refuses
the call, and the fleet-mention label from issue-guards.
9. Re-read the labels after every filing or retitle
The guard runs on every issue event, edited included, so a retitle or a
body edit is judged again. A few seconds after the call:
gh issue view <n> --json labels,comments \
--jq '[.labels[].name], (.comments[-1].body // "" | .[0:200])'If needs-rewrite or needs-type is there, the comment names the rule.
Fix it with gh issue edit. The fixing edit clears the label, so check
once more.
Prevents: an issue left flagged that nobody answered.
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.

