OpenParable
Skip to content
← Back to skills

Issue Writing

Productivity
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?"

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/majiayu000/claude-skill-registry/blob/HEAD/skills/data/issue-writing/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/issue-writing, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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.