# Issue Writing

> Issue Writing is an Agent Skill for productivity published in the majiayu000/claude-skill-registry repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use this skill when writing, reviewing, or discussing issue descriptions, acceptance criteria, or task breakdowns. Ensures consistent, high-quality issue structure that any developer or AI can pick up and execute. Triggers when drafting issues, defining requirements, or when users ask "how should I write this issue?" or "what should the acceptance criteria be?"

- Skill name: `issue-writing`
- Category: [Productivity](https://www.openparable.com/skill/productivity/1)
- Source: https://github.com/majiayu000/claude-skill-registry/blob/HEAD/skills/data/issue-writing/SKILL.md
- Repository: majiayu000/claude-skill-registry (498 GitHub stars when collected)

## SKILL.md

# Issue Writing Skill

This skill guides the creation of well-structured, actionable Jira issues that any developer or AI can pick up and execute independently.

## When to Use

Apply this skill when:
- Writing or drafting issue descriptions
- Defining acceptance criteria for tasks
- Breaking down features into Subtasks
- Reviewing existing issues for clarity
- Users ask how to document requirements

## Issue Structure: Parent Stories

```
h2. IMPORTANT: Jira Issue Discipline
[Standard discipline rules]

---

h2. Problem
[1-2 sentences: Why does this feature need to exist?]

h2. Solution
[1-2 sentences: What are we building to solve this?]

h2. High-Level Implementation
[Bullet points: Key technical decisions, patterns]

h2. Codebase Investigation Findings
[What patterns to follow, similar features, code locations]

h2. Out of Scope / Deferred
[Explicitly list what we're NOT doing]
```

## Issue Structure: Subtasks

```
h2. Objective
[1-2 sentences: What specific thing needs to be done?]

h2. Acceptance Criteria
* [Specific, testable criterion 1]
* [Specific, testable criterion 2]
* [Specific, testable criterion 3]

h2. Implementation Notes
* Relevant files: [paths]
* Patterns to follow: [reference]
* Dependencies: [other Subtasks]
```

## Writing Good Acceptance Criteria (SMART)

- **Specific**: Clear about what exactly needs to happen
- **Measurable**: Can objectively verify if it's done
- **Achievable**: Within scope of this single Subtask
- **Relevant**: Directly related to the objective
- **Testable**: Can be validated by running/checking

## Jira Formatting Notes

Jira uses Wiki markup, not Markdown:
- Headers: `h1.`, `h2.`, `h3.`
- Bold: `*bold*`
- Bullets: `*` or `-`
- Numbered list: `#`
- Code: `{{inline}}` or `{code}block{code}`
- Links: `[title|url]`

## Anti-Patterns to Avoid

- **Vague objectives**: "Improve the dashboard"
- **Missing acceptance criteria**: Assuming it's obvious
- **Implementation prescription**: Over-specifying the how
- **Hidden dependencies**: Not mentioning blockers
- **Scope creep**: Adding "nice to haves"

Remember: **A good issue can be executed by anyone who reads it.**

---

Source: https://www.openparable.com/skill/productivity/issue-writing (OpenParable). Cite the canonical URL above.
