Skip to content
Skills Library
Programming · Writing

github-issue-writing

/github-issue-writing

GitHub issue body and `[Type] Component:` title — bug/feature templates, repro steps, acceptance criteria. Use when filing a bug or feature request with gh.

Licence
MIT
Last repository change
24.10.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 24.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

GitHub issue body and `[Type] Component:` title — bug/feature templates, repro steps, acceptance criteria. Use when filing a bug or feature request with gh.

Original author description

GitHub issue body and `[Type] Component:` title — bug/feature templates, repro steps, acceptance criteria. Use when filing a bug or feature request with gh.

How it works

  1. When to Use This Skill
  2. Issue Title Format
  3. Bug Report Template
  4. Feature Request Template
  5. Issue Types
  6. Body Content: Use --body-file
  7. CLI Commands
  8. Linking Issues
  9. Quick Reference
  10. Agentic Optimizations
Original SKILL.md headings · 178 lines, 1,037 words
SKILL.md preview
---
created: 2026-01-30
modified: 2026-08-15
reviewed: 2026-04-29
name: github-issue-writing
description: "GitHub issue body and `[Type] Component:` title — bug/feature templates, repro steps, acceptance criteria. Use when filing a bug or feature request with gh."
user-invocable: false
allowed-tools: Bash(gh issue *), Bash(gh label *), Bash(gh repo *), Read, Grep, Glob, TodoWrite
---

# GitHub Issue Writing

Create well-structured, actionable GitHub issues.

## When to Use This Skill

| Use this skill when... | Use the alternative when... |
|---|---|
| Filing a new bug, feature, or chore issue with clear title and acceptance criteria | Use `git-issue` to start working on existing issues end-to-end |
| Structuring an issue body with reproduction steps, scope, and definition of done | Use `github-issue-autodetect` to link existing issues from staged diffs |
| Choosing the `[Type] Component: Description` title format | Use `github-pr-title` to author the conventional title for the PR that fixes it |
| Designing a feature-request issue before implementation begins | Use `git-issue-manage` for transfer/pin/lock/develop-branch admin operations |
| Assembling the GitHub issue itself — title format, templates, `gh issue create` | Use `communication-plugin:ticket-drafting-guidelines` for the What/Why/How prose structure and house tone of the body text |

## Issue Title Format

```
[Type] Component: Brief description
```

| Type | Example |
|------|---------|
| Bug | `[Bug] Auth: Login fails with valid credentials` |
| Feature | `[Feature] API: Add rate limiting support` |
| Docs | `[Docs] README: Add installation instructions` |
| Chore | `[Chore] CI: Update Node.js version` |

**Guidelines:**
- Be specific (not "Bug" but "Login fails with OAuth")
- Include component for triage
- Keep under 72 characters

## Bug Report Template

```markdown
## Summary
Brief description of the bug.

## Steps to Reproduce
1. Go to '...'
2. Click on '...'
3. See error

## Expected Behavior
What should happen.

## Actual Behavior
What actually happens.

## Environment
- OS: macOS 14.0
- Browser: Chrome 120
- Version: 2.1.0
```

## Feature Request Template

```markdown
## Summary
What this feature does.

## Motivation
Why this is needed. What problem does it solve?

## Proposed Solution
Description of desired behavior.

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3
```

## Issue Types

GitHub supports first-class issue types. Use `--type` when creating issues:

| Type | Use For |
|------|---------|
| Bug | Something broken that needs fixing |
| Feature | New functionality request |
| Task | General work item |

Note: Available types depend on repository/org configuration. Use `gh issue create --type "Bug"` to leverage them.

## Body Content: Use `--body-file`

For any non-trivial body — anything containing backticks, code fences, or multi-line content — use `--body-file <path>`, never `--body "<text>"`. This applies to **all** `gh` commands that accept a body: `gh issue create`, `gh issue edit`, `gh issue comment`, `gh pr create`, `gh pr edit`, `gh pr comment`.

### When to use which

| Body shape | Pattern |
|---|---|
| Trivially short, single line, no backticks | `--body "Short text"` is fine |
| Contains backticks (inline code, code fences) | `--body-file /tmp/body.md` — required |
| Multi-line | `--body-file /tmp/body.md` — required |
| Contains shell metacharacters (`$`, `"`, `'`, `\`) | `--body-file /tmp/body.md` — required |

### Why

Shell-quoted `--body` strings escape backticks (`` ` `` becomes `` \` ``), breaking inline code spans and triple-backtick code fences in the rendered issue. Bash heredocs interact unpredictably with the agent's argument escaping. Writing the markdown to a file with the `Write` tool sidesteps shell quoting entirely — the file content is preserved byte-for-byte.

### Pattern

```
1. Write tool → /tmp/issue-body.md   (markdown body, no shell escaping)
2. gh issue create --title "..." --body-file /tmp/issue-body.md
```

The same `--body-file <path>` form is supported by every `gh` command that accepts a body.

## CLI Commands

```bash
# Create issue with a body file (preferred for any non-trivial body)
gh issue create --title "[Bug] Auth: Login fails" --body-file /tmp/issue-body.md

# Trivially short body — inline --body is acceptable
gh issue create --title "[Chore] Bump dep" --body "See renovate PR"

# With labels
gh issue create --title "..." --body-file /tmp/body.md --label "bug" --label "priority: high"

# With assignee
gh issue create --title "..." --body-file /tmp/body.md --assignee "@me"

# With issue type
gh issue create --title "..." --body-file /tmp/body.md --type "Bug"

# As sub-issue of a parent
gh issue create --title "..." --body-file /tmp/body.md
gh api repos/{owner}/{repo}/issues/{parent}/sub_issues -f sub_issue_id={new_id}

# Search before creating
gh issue list --search "login error" --state all
```

## Linking Issues

Pick the mechanism that matches the relationship — GitHub surfaces each one
differently and only the native APIs trigger "Blocked" badges on project boards.

| Relationship | How to record | Why |
|--------------|---------------|-----|
| Hard dependency (must happen before) | Native `dependencies/blocked_by` API — see `/git:issue-hierarchy --blocked-by N` | Sidebar "Relationships" entry + Blocked badge on boards |
| Composition (part-of scope) | Sub-issue API — see `/git:issue-hierarchy --add N` | Progress bar on parent, tracked separately from dependencies |
| Soft reference ("related to") | Plain markdown `Related to #789` in the body | Cross-link only; no lifecycle coupling |
| Auto-close on merge | `Fixes #N` / `Closes #N` footer in commit or PR body | Closes issue when the PR merges |

Do **not** write `Blocks #123` or `Blocked by #456` in issue bodies any more —
those strings used to be GitHub's workaround for missing dependency APIs, but
they are no longer parsed. Call `/git:issue-hierarchy` (or the REST endpoints
at `issues/{N}/dependencies/blocked_by`) so the relationship shows up in the
sidebar and on project boards.

## Quick Reference

| Action | Command |
|--------|---------|
| Create | `gh issue create --title "..." --body-file /tmp/body.md` |
| Create with type | `gh issue create --title "..." --body-file /tmp/body.md --type "Bug"` |
| Search | `gh issue list --search "keyword"` |
| View | `gh issue view N` |
| Edit body | `gh issue edit N --body-file /tmp/body.md` |
| Comment | `gh issue comment N --body-file /tmp/comment.md` |
| Labels | `gh label list` |

## Agentic Optimizations

| Context | Command |
|---------|---------|
| Create issue | `gh issue create --title "..." --body-file /tmp/body.md` |
| Create with type | `gh issue create --title "..." --type "Bug" --body-file /tmp/body.md` |
| List labels | `gh label list --json name` |
| Search issues | `gh issue list --search "keyword" --state all --json number,title` |
| View issue | `gh issue view N --json title,body,labels` |

Versions

The database has no other skills named github-issue-writing.

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

  • 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-creation
    Generate issues following repository templates for GitHub or GitLab. Use when creating bug reports, feature requests, or other issues. Triggers: "create issue", "bug report", "feature request", "new issue".
  • 100github-cr-issue
    Drafts the body of a well-formed, self-contained GitHub issue for the current repository from a per-type template — feature, component, task, bug, or spike — searching existing issues for duplicates before any drafting, and saving the result as an ephemeral draft ready for…
  • 100create-github-issue
    Create GitHub issues using GitHub CLI with support for templates, labels, assignees, milestones, and draft issues. Use when the user asks to create a GitHub issue, file a bug report, submit a feature request, or open an issue in a GitHub repository.
  • 100create-issue
    Use when asked to file, report, open, or raise a GitHub issue for a bug, feature, audit, or review finding.
  • 100implement-github-feature
    Design and implement a new feature or component from a GitHub issue. Use for net-new functionality, not bug fixes.

Feedback and reports

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