Writing Issues

Encode GitHub issue authoring conventions for titles, bodies, and context.

5|1|Updated Nov 11, 2025

Search Tags:#project management #documentation #writing #developer workflow #github #issues

Ready to run

npx skills add https://github.com/notorious-ai/claude-plugins --skill writing-issues

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: Writing Issues
Source: https://github.com/notorious-ai/claude-plugins/tree/main/github-author/skills/writing-issues
Command: npx skills add https://github.com/notorious-ai/claude-plugins --skill writing-issues

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) and examples (resource) components.

What problem does it solve?

This Skill helps you write clear, actionable GitHub issues by encoding best practices for titles, body content, and context gathering, ensuring issues are well-defined and understood.

Core Features & Use Cases

Present-Progressive Titles: Learn to use titles that reflect ongoing work, not commands.
Outcome-Focused Bodies: Structure issue bodies to explain the "why" and "what," leaving the "how" to the assignee.
Context Gathering: Provides guidance on identifying and surfacing necessary information before drafting an issue.
Use Case: When you need to create a new issue for a bug report or feature request, this Skill guides you to write a title like "Fixing search crash on large date ranges" and a body that clearly explains the problem, its impact, and what a successful resolution looks like.

Quick Start

Draft a GitHub issue about improving API documentation coverage.

Frequently Asked Questions about Writing Issues

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I write a good GitHub issue title?▼

An effective GitHub issue title uses the present-progressive tense to reflect ongoing work, such as "Fixing search crash on large date ranges," rather than framing the task as a command.

What should I include in a GitHub issue body?▼

A strong GitHub issue body is outcome-focused, explaining the problem space and the "why" of the issue, while leaving the "how" and implementation details to the assignee.

How do I gather context before creating a GitHub issue?▼

Gathering context for a GitHub issue involves identifying and surfacing necessary information from conversations and repositories to ensure the problem is well-defined and understood before drafting.

Should I use checklists or prose for GitHub issues?▼

Structuring prose over checklists in GitHub issues helps frame the problem space and define the definition-of-done, ensuring the issue focuses on outcomes rather than reducing the task to a simple checklist.

How do I define the definition of done in a GitHub issue?▼

Defining the definition-of-done in a GitHub issue involves structuring the body to clearly explain what a successful resolution looks like, focusing on the desired outcome rather than specific implementation steps.