Skip to content
Skills Library
Management & product · Writing

file-issue

/file-issue

Turn a request or a discovered bug into a GitHub issue in this repo's format - interview the person until the intent is well defined, check for duplicates, then file. Use when asked to file, open, create or write up an issue, when someone describes a feature they want, or when you hit a bug you should not fix in the current change.

Repository
cordierite ↗
Licence
MIT
Last repository change
21.10.2026

Assessment and security

95/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content30 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 21.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Turn a request or a discovered bug into a GitHub issue in this repo's format - interview the person until the intent is well defined, check for duplicates, then file. Use when asked to file, open, create or write up an issue, when someone describes a feature they want, or when you hit a bug you should not fix in the current change.

Original author description

Turn a request or a discovered bug into a GitHub issue in this repo's format - interview the person until the intent is well defined, check for duplicates, then file. Use when asked to file, open, create or write up an issue, when someone describes a feature they want, or when you hit a bug you should not fix in the current change.

How it works

  1. 1. Pin the intent down
  2. 2. Check for a duplicate
  3. 3. Write it
  4. 4. Size it and create it
  5. Report
Original SKILL.md headings · 100 lines, 698 words
SKILL.md preview
---
name: file-issue
description: Turn a request or a discovered bug into a GitHub issue in this repo's format - interview the person until the intent is well defined, check for duplicates, then file. Use when asked to file, open, create or write up an issue, when someone describes a feature they want, or when you hit a bug you should not fix in the current change.
model: sonnet
effort: medium
---

# File an issue

Never file an issue for something you can fix inside the change you are already making.
Note it in the PR instead. If told not to create the issue, print the title, labels and body
in the format below instead of running `gh issue create`.

Load `cite-evidence`; what the issue says about a dependency is cited or marked unverified.

Read the `file-issue` section of `.agents/memory/LESSONS.md` before starting, plus General.

## 1. Pin the intent down

An issue is the spec that tests get written from, so a vague issue produces the wrong
feature. Before writing anything, check whether you can fill every field below from what you
have. For each one you cannot, ask the person one question at a time, with your best guess
as the suggested answer, and wait. Stop asking when the fields are filled or after five
questions; then write what you have and mark the rest "open".

- **Feature.** Why (the cost today, who pays it, when), expected outcome (what you can observe
  once it exists), constraints and non-goals, and how we will know it is done (criteria a
  test can check). Ask about the edge the person has not mentioned: the unhappy path, other
  platforms, what happens to existing users.
- **Bug.** Reproduction from a clean state, expected state, platform and version. If you
  found the bug yourself, you have these; do not interview yourself.

Skip the interview when the request came from an agent report, a triage comment or an
approved design that already answers everything.

## 2. Check for a duplicate

Two searches: distinctive words from the symptom or outcome, then the literal identifier
involved (a file name, command, error type).

```bash
gh issue list --limit 1                                   # non-empty, so gh works
gh issue list --state all --search "<three or four words>" --limit 10
gh issue list --state all --search "<literal identifier>" --limit 10
```

If one exists, comment on it with what you have and report its number.

## 3. Write it

The body mirrors the issue form in `.github/ISSUE_TEMPLATE/` field for field, as `###`
headings with the form's labels, in the form's order. Style from `AGENTS.md`: outcome first,
plain English, nothing that does not help someone act on it.

**Bug**, title describes the symptom, not the fix (`pnpm showcase fails: script file
missing`):

```
### What happens
### What should happen
### Reproduction          exact commands from a clean state and their output; how often if intermittent
### Appduct version       the installed version, or the commit sha when running from this repo
### Platform              iOS, Android, React Native, or None (daemon, CLI, MCP, repo tooling)
### Environment           OS, Xcode or Android SDK, simulator or device, Node
### Root cause            only what you traced in code, with path:line; otherwise "not investigated"
```

**Feature**, title is imperative (`Let apps declare read-only resources`):

```
### Why                       the problem or cost today; who hits it and when
### Expected outcome          observable behaviour once it exists
### Constraints and non-goals what must not change; security or compatibility limits; out of scope
### How we know it is done    numbered acceptance criteria, each observable by a test
### Alternatives considered   one line each, or "none"
```

Write the body to the session scratch directory, not into the repo.

## 4. Size it and create it

A bug is always `status:needs-triage`; the `triage-issue` skill finds the root cause.

A feature is `status:ready` when it fits one PR: one package, no new public API beyond what
the criteria name, no wire or protocol change. Otherwise it is `status:needs-design`, and
the `design-feature` skill turns it into slices. When unsure, `needs-design`; a design pass
on a small feature costs minutes, skipping it on a big one costs a rewritten PR.

```bash
gh issue create --title "<under 70 chars>" \
  --label type:feature,status:ready,area:mcp \
  --body-file <scratch>/issue.md
```

Labels, from `.github/labels.yml`: exactly one `type:`, exactly one `status:`, `platform:`
only when platform-specific, `area:` when one fits (`area:tooling` covers repo scripts, CI
and workspace config).

## Report

```
Issue: #N (new) | #N (existing, commented) | not created (dry run)
Type: bug | feature   Status: needs-triage | ready | needs-design
Open: <fields left open after the interview, or "none">
```

Versions

RepositoryScoreLicence
This page · callstackincubator/cordierite95MIT
sma1lboy/rove100MIT
rowdybard/whetstorm-art100MIT
Er2oneousbit/claude-code-game-kit86MIT

Database snapshot: 13.11.2026 · package version ee5c47c42c55 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 91issue-create
    Creates a GitHub issue from the project's issue form templates. Use when the user asks to open an issue, not to fix a bug.
  • 100gh-issue
    Turn a user's complaint, bug observation or request into a well-formed GitHub issue and file it with the gh CLI. Use when the user wants to file, open, create, report or raise an issue, bug report, feature request or docs problem on a GitHub repository, including "report this…
  • 100create-github-issue
    Create GitHub issues using the gh CLI. Use when the user wants to create a new issue, report a bug, request a feature, or create a task in GitHub. Trigger keywords - create issue, new issue, file bug, report bug, feature request, github issue.
  • 84github-issue
    Use when opening a GitHub issue, bug report, feature request, or discussion in any repository, including one the user has no local checkout of.
  • 9004-issue-create
    Create an issue in the configured ticketing tool. Use when the user wants to file a bug, open an issue, or report a problem. Not for committing, opening a pull request, or commenting on an existing issue.
  • 95issue-create
    Create a tracked issue in this repo end to end — duplicate check, v2 label, type label, server-scope label, milestone, board card, Status and Priority. Use when asked to file, create, open or raise an issue; when picking its labels or its milestone; when checking whether one…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.