home / skills / laurigates / claude-plugins / github-issue-writing

github-issue-writing skill

safe

This skill helps you craft clear, actionable GitHub issues with precise titles, structured bodies, and acceptance criteria.

npx playbooks add skill laurigates/claude-plugins --skill github-issue-writing

Review the files below or copy the command above to add this skill to your agents.

Files (1)

skill.md

2.8 KB

---
model: haiku
created: 2026-01-30
modified: 2026-01-30
reviewed: 2026-01-30
name: github-issue-writing
description: |
  Create well-structured GitHub issues with clear titles, descriptions, and
  acceptance criteria. Use when filing bugs, requesting features, or structuring
  issue content.
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

| Use this skill when... | Use X instead when... |
|------------------------|----------------------|
| Creating new issues | Processing existing issues (`git:issue`) |
| Writing bug reports | Auto-detecting issues (`github-issue-autodetect`) |
| Filing feature requests | Creating PRs (`git-pr`) |

## 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
```

## CLI Commands

```bash
# Create issue
gh issue create --title "[Bug] Auth: Login fails" --body "..."

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

# With assignee
gh issue create --title "..." --body "..." --assignee "@me"

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

## Linking Issues

```markdown
## Related Issues
Blocks #123
Blocked by #456
Related to #789
```

## Quick Reference

| Action | Command |
|--------|---------|
| Create | `gh issue create --title "..." --body "..."` |
| Search | `gh issue list --search "keyword"` |
| View | `gh issue view N` |
| Edit | `gh issue edit N --title "..."` |
| Labels | `gh label list` |

## Agentic Optimizations

| Context | Command |
|---------|---------|
| Create issue | `gh issue create --title "..." --body "..."` |
| 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` |

Overview

This skill creates well-structured, actionable GitHub issues with clear titles, concise descriptions, and measurable acceptance criteria. It standardizes bug reports, feature requests, and chores so maintainers can triage and act quickly. The output is formatted for immediate use with the GitHub CLI or web interface.

How this skill works

It builds a recommended title using a [Type] Component: Brief description pattern to aid triage. It generates body sections tailored to the issue type (bug, feature, docs, chore), including reproduction steps, environment details, motivation, proposed solution, and acceptance criteria. It can produce CLI-ready titles and bodies and suggests labels, assignees, and related issue links.

When to use it

Filing a new bug report with reproducible steps and environment information
Requesting a new feature or enhancement with motivation and acceptance criteria
Creating documentation updates, chores, or CI changes that need concise scope
Preparing an issue for the GitHub CLI (gh) or for quick triage by maintainers
Before opening an issue, after searching to ensure it isn’t a duplicate

Best practices

Follow the title format: [Type] Component: Brief description and keep it under ~72 characters
For bugs include Summary, Steps to Reproduce, Expected vs Actual Behavior, and Environment
For features include Summary, Motivation, Proposed Solution, and clear Acceptance Criteria
Search existing issues before creating a new one to avoid duplicates and link related issues
Add relevant labels and an assignee when known to speed triage

Example use cases

Bug: Reproduce login failure with steps, OS/browser, and failing behavior for the auth team
Feature: Request rate limiting for API with motivation and a checklist of acceptance criteria
Docs: Add installation instructions to README with examples and expected outcomes
Chore: Update CI Node.js version with migration notes and verification steps
Triage prep: Create an issue with links to logs and related issues before an on-call handoff

FAQ

How do I pick the right Type for the title?

Choose Bug for defects, Feature for new capabilities, Docs for documentation changes, and Chore for maintenance. Be specific about the component to help triage.

What belongs in Acceptance Criteria?

List measurable, testable conditions that define when the issue is complete. Use checklist items that a reviewer can verify.

Should I include environment details for every bug?

Include environment when it affects reproducibility (OS, browser, version). If the bug is environment-independent, a brief note stating that is fine.