Skip to content
Skills Library
Programming · Writing

create-issue

/create-issue

File a GitHub issue on the current repo with a plain two-sentence summary on top, the six-section body written for its two readers and run through the hemingway and humanizer skills, and the required labels. Use whenever asked to file, create, or open an issue (a bug, a feature, a decision, or a task), or to convert findings into issues.

Repository
ai-config ↗
Licence
GPL-3.0
Last repository change
12.11.2026

Assessment and security

100/ 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.
Content35 / 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 12.11.2026, without references to retired models or APIs.

Licence

GPL-3.0, otwarta.

What it does and when to use it

File a GitHub issue on the current repo with a plain two-sentence summary on top, the six-section body written for its two readers and run through the hemingway and humanizer skills, and the required labels. Use whenever asked to file, create, or open an issue (a bug, a feature, a decision, or a task), or to convert findings into issues.

Original author description

File a GitHub issue on the current repo with a plain two-sentence summary on top, the six-section body written for its two readers and run through the hemingway and humanizer skills, and the required labels. Use whenever asked to file, create, or open an issue (a bug, a feature, a decision, or a task), or to convert findings into issues.

How it works

  1. Step 1: confirm the request
  2. Step 2: keep technical names exact
  3. Step 3: open with a plain summary
  4. Step 4: use the six sections, in this order
  5. Step 5: write for the reader, then cut, then strip the AI tells
  6. Step 6: title
  7. Step 7: labels
  8. Step 8: verify before you write
Original SKILL.md headings · 153 lines, 1,112 words
SKILL.md preview
---
name: create-issue
description: File a GitHub issue on the current repo with a plain two-sentence summary on top, the six-section body written for its two readers and run through the hemingway and humanizer skills, and the required labels. Use whenever asked to file, create, or open an issue (a bug, a feature, a decision, or a task), or to convert findings into issues.
---

# Creating an issue

The flow is the same in every repo. What differs by repo lives in that repo's
`CLAUDE.md`, under its "Issues" (or "Filing issues") section:

- **The reader**: who reads the summary on the board, for example "a hiker who
  does not read code".
- **The gates**: the CI and review gates every Acceptance Criteria list
  includes.
- **The constraints**: the guardrails an implementing agent must know.
- **The areas**: the area labels, and what each one covers.

Read that section before you write. If the repo has none, ask the maintainer
for the four, and offer to add the section to its `CLAUDE.md`.

## Step 1: confirm the request

Never file an issue the maintainer did not ask for. If the idea is yours,
propose it and get an explicit yes first. This includes follow-up issues
discovered mid-task.

## Step 2: keep technical names exact

- File paths, functions, API names, env vars and label names are technical
  names. Write them exactly as they appear in the code.
- Quote UI strings, commands, and code verbatim.
- Use one name for one thing. Do not alternate synonyms.
- Use no em dashes.

## Step 3: open with a plain summary

The body opens with a `## Summary` heading, the summary, and a horizontal
rule (`---`) that closes it off from the six sections below. It is the only
part of the issue most readers see on the board, so it carries the whole point.

- Two sentences, three at most. No bullets, no file paths, no line numbers,
  no code spans.
- Sentence one: what is wrong, in words the repo's reader would follow.
  Sentence two: what changes when the issue is closed. An optional third: why
  it matters now.
- Write it last, after the six sections, so it summarizes what is actually
  in the issue. Then place it first.
- The summary is the one place plain language beats precision: say "the app
  shows the browser's own error text" rather than naming the exception.

Example, for an issue about a bare `fetch`:

```markdown
## Summary

When the server cannot be reached, the app shows the browser's own error
text instead of one of ours. After this change every network failure shows
an approved message, and one shared helper handles every request.

---

## Problem
```

## Step 4: use the six sections, in this order

This list is the skeleton; write the sections from it directly. Every issue
carries at least:

1. **Problem**: what is wrong or missing, with verified facts. State what
   was measured or observed, and how.
2. **Proposed Solutions**: lettered options, each with Good and Bad bullets,
   ending in one recommendation line. State a settled decision as settled,
   with who decided and when.
3. **Implementation Plan**: numbered imperative steps. Name the file and the
   function for each step.
4. **Acceptance Criteria**: plain bullets a reviewer can verify. Include the
   repo's gates that apply.
5. **Notes for an AI agent**: the guardrails and traps an implementing agent
   must know, starting from the repo's constraints.
6. **Notes for a human**: the decisions that are the maintainer's, the
   provenance (review finding, TODO, conversation, a run's log), the risks,
   and any open questions.

Optional extra sections (for example, Out of scope or Measured) go between
Acceptance Criteria and the Notes.

## Step 5: write for the reader, then cut, then strip the AI tells

An issue has two readers: a person on the board who may not read code, and
the agent that implements it. The body is done when each follows their part
on one read. Three things get it there, in this order.

**Write every section to the reader checklist.**

- Each section opens with its conclusion. The evidence follows it.
- One idea per sentence, and no sentence much past 25 words.
- A term, an acronym or a module name is explained the first time it
  appears. The second time it stands alone.
- The Problem says what a reader would see before it says how that was
  measured.
- Notes for a human reads on its own, without the Implementation Plan
  beside it.

**Run two passes over the whole body, summary and all six sections, once
the summary is placed first.** Both change prose only, and short issues take
them too.

1. `hemingway` first. It cuts words, and shorter is the biggest lever on
   comprehension. Take its trimmed version. Put back any cut that dropped a
   fact, a number or a qualifier that changes the meaning.
2. `humanizer` second, in embedded mode, on the trimmed text. It strips the
   AI tells from what survived. Apply every fix it returns.

After both, check the technical names against the draft: file paths,
function names, quoted UI strings, commands, code spans, label names and
issue numbers stay exactly as Step 2 wrote them. Wording the maintainer
dictated stays as dictated; both skills exempt quotations and proper names.

**Read it back as each reader before filing.** Read the Summary and the
Problem as the repo's reader, and the Implementation Plan and the agent notes
as the implementing agent. If either reader would have to look something up,
fix that before filing.

An edit to an existing issue takes the same three steps before
`gh issue edit`.

## Step 6: title

One short statement of the problem or the task, with no
conventional-commit prefix. Example: "A caller can defeat the per-client rate
limit with one header".

## Step 7: labels

Always add labels when you create the issue. Create any that don't exist yet
with `gh label create`.

- Exactly one priority: `P1` (do next), `P2` (soon), or `P3` (someday). Add
  one every time, also when the maintainer asks for `PM`.
- `PM` means Priority Manual. Add it only when the maintainer asks for it in
  the request. It is one more label, not a replacement for the priority.
- The current Claude Code session ID, always. The ID is the UUID directory
  above `scratchpad` in the session's scratchpad path. Create the label first
  when it does not exist (the description must stay under 100 characters):
  `gh label create <uuid> --color 5ec3f7 --description "Filed in Claude Code session <uuid> (<date> <topic>)"`.
- Every area from the repo's list that applies.
- One type: `bug`, `enhancement`, `documentation`, or `question`. A decision
  the maintainer has to make is a `question`.

## Step 8: verify before you write

- Verify file references and measured numbers against a fresh clone before you
  state them. Write "near line N" only when just verified; otherwise name the
  file and the function.
- Name related issues by number, and state a blocking relation explicitly.

Versions

RepositoryScoreLicence
This page · zimmertr/ai-config100GPL-3.0
tony/skills100MIT
fcakyon/claude-codex-settings100Apache-2.0
alexander-kastil/copilot-harness100MIT
glnds/glnds-cc-marketplace100Apache-2.0
nateslabach/skills100MIT
uta2000/feature-flow100MIT

Database snapshot: 13.11.2026 · package version 472e1f9394f3 (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

  • 100gh-create-issue
    Use when asked to file, report, open, or raise a GitHub issue for a bug, feature, audit, or review finding.
  • 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.
  • 100issue-create
    Create a GitHub issue with a structured body (Context, What, Why, Scope, Solution) and curated labels via the gh CLI. Use when filing new issues, or when invoked from other skills.
  • 100arn-code-create-issue
    This skill should be used when the user says "create issue", "file issue", "arness code issue", "arness code create issue", "arn-code-create-issue", "report bug", "request feature", "add to backlog", "create GitHub issue", "create Jira issue", "file a bug", "submit issue", "log…
  • 100open
    Open a ticket — turn an idea, a bug or an improvement into a GitHub issue, or with `tickets: files` a ticket file under `.10x/`, grounded in the codebase, classified with the repo's own labels or issue types, ready for /10x:work. Use when the user runs /10x:open with something to file.
  • 90issue
    Create a well-formed GitHub issue in the same format as the repo's issue forms, and optionally group it with labels, a project and a milestone, creating any that do not exist yet. Use when the user wants to raise, log or file an idea, request, feature, bug or task as a GitHub issue.

Feedback and reports

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