Skip to content
Skills Library
Management & product · Writing

issue

/issue

Create a need-only, minimal-scope issue on the current project's GitLab or GitHub. Use when the user asks to create an issue from a description, a finding, or a doc.

Repository
skillhead ↗
Licence
MIT
Last repository change
08.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
5
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

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

Licence

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

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: hooks/guard_issue_create.py

What it does and when to use it

Create a need-only, minimal-scope issue on the current project's GitLab or GitHub. Use when the user asks to create an issue from a description, a finding, or a doc.

Arguments

/issue <free-text description of the issue>
Original author description

Create a need-only, minimal-scope issue on the current project's GitLab or GitHub. Use when the user asks to create an issue from a description, a finding, or a doc.

How it works

  1. Your role
  2. Session cache
  3. Steps
  4. Body template
Original SKILL.md headings · 159 lines, 1,099 words
SKILL.md preview
---
name: issue
description: >-
  Create a need-only, minimal-scope issue on the current project's GitLab or
  GitHub. Use when the user asks to create an issue from a description, a
  finding, or a doc.
argument-hint: <free-text description of the issue>
---

# /issue — create an issue on the project's forge

Create an issue for the current project from this description:

> $ARGUMENTS

An issue states the NEED, never the how. Three qualities gate creation:

- **Minimal** — the smallest change that closes the acceptance criteria;
  every implication the ask carries is kept with its impact or cut with
  its reason.
- **Durable** — no file path, no line number, no pattern to mirror: the
  repo moves before the implementer reads the issue. Types, signatures
  and observable behaviour survive; paths don't.
- **Decided** — no open tension in a published body; the user rules on
  the draft in chat before anything is created.

## Your role

You route, validate with the user and never draft yourself. The
scoping and the draft run in an opus subagent (`skillhead:issue-scoper`); a
opus subagent (`skillhead:issue-reviewer`) judges the draft, cap 3 rounds;
both load `skillhead:ponytail` as their only skill. Forge reads and the repo
check run in subagents pinned `model: "opus"`, forge writes in the
`skillhead:issue-publisher` agent. You never read the repository, never load a skill
and never call the forge yourself.

Report routing: a subagent writes its report to a scratchpad file and
ends with ONE line — verdict + path. You read the file; never recopy a
report into the conversation, except the draft body at step 3.

## Session cache

`<scratchpad>/issue-cache.md` — forge, project path, label list, issue
language. The recon agent writes it on first run and reads it on later
ones.

## Steps

### 0. Guard

Empty `$ARGUMENTS` → stop and ask what the issue is about. Never invent
a topic.

### 1. Recon — opus, one agent

Spawn ONE recon agent (`model: "opus"`, read-only) with `$ARGUMENTS`,
the cache path, a report path, and `RECON.md` (path). It ends
`RECON <duplicate-verdict> <repo-verdict> <path>`.

Rule on the verdicts yourself:

- **duplicate-open** → stop, report the existing URL, ask whether to
  extend it instead. Do not create.
- **duplicate-closed** → proceed; the scoper prompt carries
  `> **Previously #N** — <one line: fixed or rejected, when>`; a fixed
  bug resurfacing is a regression — say so.
- **related** → the scoper prompt carries `> **Related to #N** — <one
  line how>`.
- **contradiction** (feature already there, bug not reproducible, ask
  conflicts with an ADR) → stop and surface it; never write around it.

### 2. Scope, draft, review — `skillhead:issue-scoper` ‖ `skillhead:issue-reviewer`, cap 3

Spawn ONE `skillhead:issue-scoper` (`subagent_type: "issue-scoper"`, never with
`model`) — it loads `skillhead:ponytail` and weighs the ask on its ladder —
handed: `$ARGUMENTS`, the briefing path, a drafts dir, the
project language from the cache, and `SCOPER.md` (path). It ends
`DRAFTED <dir>` (one file per draft, `split.md` when it proposes a
split, `group.md` when it gathers several needs of the ask into one
issue, `variantes.html` to print by its `file://` link when a need changes the UI notably),
`CONTEST <path>` (a config change, an existing feature, a doc
fix, doing nothing or a direct fix under 15 lines covers the need) or `FAILED <path>`.

- **CONTEST** → print the file, ask the user; on "draft anyway",
  respawn with the ruling.
- **split** → `AskUserQuestion` with the titles, scopes and
  parallelism costs of `split.md`; a refused split → respawn with
  the ruling.
- **group** → an ask carrying several needs is never handed to the
  scoper as "one issue each": the count is the scoper's to weigh.
  Print `group.md` (which needs share an issue, which stay alone,
  why, the implementation cycles saved) and ask the user; a refused
  grouping → respawn with the ruling.
- **DRAFTED** → spawn ONE `skillhead:issue-reviewer` (round `c`, never with
  `model`) handed: `$ARGUMENTS`, the briefing path, the drafts dir,
  `REVIEWER.md` (path). `DRAFT-OK` → step 3. `DRAFT-REWORK <path>` →
  respawn the scoper with that path (it amends the drafts, answers
  each finding in `<dir>/review-response-<c>.md`), then round `c+1`.
  `CONTEST` → as above. After review 3 → step 3 whatever the verdict,
  the open findings printed under the draft.

### 3. Validate with the user

Print the draft(s) in full — the body IS the deliverable. Under it,
list the decisions the draft carries that the user did not state
and would plausibly contest — the ones that change what
the user or a customer sees, or what runs automatically. Each in
plain words a reader understands without the draft: what happens,
then « otherwise: » the alternative. No IDs, no field names, no jargon;
skip the minor ones. Never ask about `ready-for-agent`: it is always
set. None → say so. The user
edits or accepts in chat; apply edits to the draft file without
re-scoping what was accepted. Nothing is created before this go.

### 4. Publish — opus, one agent

Spawn ONE publisher (`subagent_type: "issue-publisher"`, never with
`model`: the issue-creation hook lets only that type create on guarded
repositories) with the draft paths, the cache
path, and `RECON.md` (path — its § Forge commands). It creates in
dependency order from the files, substitutes each `#{<slug>}` with the
number the forge returned, links dependents (blocked-by), always adds
the `ready-for-agent` label when the project has it, and ends
`CREATED <url> [<url> …]` or `PUBLISH-FAILED <path>`. Print the URLs
in dependency order. You never call the forge: the body leaves the
reviewer once, as the file.

## Body template

≤ 40 lines (a grouped issue: ≤ 60, one `Current` / `Desired` line and
its own criteria per need). No file path, no line number, no pattern to mirror, no
ordered steps. A line that doesn't apply is omitted, never filled.
Never quote secrets or env values. A count is never a contract. A flow
the issue changes may carry ONE mermaid diagram of the touched sub-flow
under `Desired behavior`; never a file tree.

```markdown
**Category:** bug / enhancement
**Summary:** <one line: what must happen>

**Current behavior:**
<what happens today, for whom; link the source doc/finding.
Bug: repro steps + expected / observed>

**Desired behavior:**
<what the user observes once done; edge cases and error conditions named>

**Key interfaces:**
- `TypeName` / `functionName()` / config shape — the behaviour that
  changes and why, never "a new method"; the shared mechanism or
  generated type to reuse, by name, never by path

**Constraints:**
- <what a human or an ADR imposes, each line ending on its source:
  "text[] in DB (ADR-4)", "FR only (user)", "<rule> (CLAUDE.md)".
  Unsourced = a disguised how: cut it. Omit if none>

**Acceptance criteria:**
- [ ] <independently verifiable behaviour>

**Out of scope:**
- <implication cut> — <why: no impact today / cost / other issue>
```

Title: imperative, ≤ 70 chars; the type lives in the label, not the
title.
Files in this package (5)
  • RECON.md 3 KB
  • REVIEWER.md 2 KB
  • SCOPER.md 5 KB
  • SKILL.md 7 KB
  • hooks/guard_issue_create.py 7 KB

Versions

RepositoryScoreLicence
This page · cyberyon-official/skillhead100MIT
elalfner/relevo100MIT
ShieldBattery/ShieldBattery100MIT
Paradiddle131/loadout100MIT
chanmuzi/git-claw100MIT
adelrodriguez/skills100MIT
bengous/claude-code-plugins100MIT
egregore-labs/egregore100MIT
andrewBezerra/concordia100MIT

Database snapshot: 13.11.2026 · package version 94b50860ee55 (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-create-issue
    Use when asked to file, report, open, or raise a GitHub issue for a bug, feature, audit, or review finding.
  • 100nxs-gh-create-epic
    Create a GitHub issue from an Epic document. Use when the user wants to create a GitHub issue from an epic.md file, sync an epic to GitHub, or link an epic document to a GitHub issue. The skill extracts the epic title and type from YAML frontmatter, creates an issue via `gh…
  • 100nxs-gh-create-epic
    Create a GitHub issue from an Epic document. Use when the user wants to create a GitHub issue from an epic.md file, sync an epic to GitHub, or link an epic document to a GitHub issue. The skill extracts the epic title and type from YAML frontmatter, creates an issue via `gh…
  • 95file-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…
  • 90github-issues
    Use when filing a bug, requesting a feature, creating an issue, or updating issue details. Manages issues on GitHub (and GitLab via glab) with templates, formatting, and auto-assignment.

Feedback and reports

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