Issue Writing

Issue Writing Skill

What I do

• Create concise, actionable GitHub issues that are easy to triage.
• Standardize issue structure for bugs, enhancements, and questions.
• Improve collaboration with clear reproduction steps, expected vs actual behavior, and impact.
• Add prioritization guidance (labels, milestones, assignees).

Core principles

1. Clarity first: The title and first paragraph should explain the problem immediately.
2. Reproducibility: Anyone should be able to reproduce the issue from the steps.
3. Context over noise: Include relevant logs/screenshots/env details; avoid vague text.
4. Actionability: State desired outcome and acceptance criteria.
5. Triage-friendly: Use labels, priority, milestone, and ownership.

What to include in every issue

• Descriptive title
• Example: Bug: App crashes when clicking Login without credentials
• Problem statement
• What happened, where, and why it matters.
• Expected vs actual behavior
• Steps to reproduce (numbered)
• Environment
• OS, browser/runtime, app version/commit, relevant config
• Evidence
• screenshots, stack traces, logs, request IDs, recordings
• Impact
• who is affected, severity, workaround if any
• Triage metadata
• labels, priority, milestone, assignee

Templates

1) Bug report template

## Description

## Steps to Reproduce
1. 
2. 
3. 

## Expected Behavior

## Actual Behavior

## Environment
- OS: 
- Browser/Runtime: 
- App Version/Commit: 
- Config/Flags: 

## Evidence
- Logs/Stack trace:
  ```
  
  ```
- Screenshot/Video: 

## Impact
- Severity: 
- Affected users/scope: 
- Workaround: 

## Suggested Fix (optional)

2) Enhancement template

## Problem

## Proposed Change

## Alternatives Considered
- 
- 

## Acceptance Criteria
- [ ] 
- [ ] 

## Impact
- User impact: 
- Technical impact: 

## Dependencies

3) Question / clarification template

## Question

## Context

## What you tried
- 
- 

## Desired outcome

Prioritization & triage guidance

• Add labels such as: bug, enhancement, question, needs-triage, priority:high|medium|low.
• Assign milestones for release planning.
• Assign an owner when someone starts work.
• Keep one issue = one problem.

Good vs weak issue examples

Weak

• Title: Login broken
• Body: Doesn't work on my machine.

Good

• Title: Bug: Login button triggers 500 when username is empty
• Body includes: exact reproduction, expected/actual behavior, logs, environment, and impact.

Quick checklist before submitting

• [ ] Title is specific and searchable
• [ ] Repro steps are complete and deterministic
• [ ] Expected vs actual behavior is explicit
• [ ] Environment details included
• [ ] Evidence attached (logs/screenshots)
• [ ] Labels/priority/milestone set
• [ ] Issue is scoped to one problem

When to use me

Use this skill when creating or refining GitHub issues so maintainers can triage quickly and contributors can implement with minimal back-and-forth.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Jonathan0823
• Source: Jonathan0823/opencode-config
• License: MIT

Install and usage instructions live in the source repository linked above.