ReddRadar
Agent skill
issue-writing
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?"
Install this agent skill to your Project
npx add-skill https://github.com/jclfocused/claude-agents/tree/main/custom_plugins/plugins/linear-planning-workflow/skills/issue-writing
SKILL.md
Issue Writing Skill
This skill guides the creation of well-structured, actionable Linear 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 sub-issues
- Reviewing existing issues for clarity
- Users ask how to document requirements
Issue Structure: Parent Feature Issues
## IMPORTANT: Linear Issue Discipline
[Standard discipline rules]
---
## Problem
[1-2 sentences: Why does this feature need to exist?]
## Solution
[1-2 sentences: What are we building to solve this?]
## High-Level Implementation
[Bullet points: Key technical decisions, patterns]
## Codebase Investigation Findings
[What patterns to follow, similar features, code locations]
## Out of Scope / Deferred
[Explicitly list what we're NOT doing]
Issue Structure: Sub-Issues / Tasks
## Objective
[1-2 sentences: What specific thing needs to be done?]
## Acceptance Criteria
- [ ] [Specific, testable criterion 1]
- [ ] [Specific, testable criterion 2]
- [ ] [Specific, testable criterion 3]
## Implementation Notes
- Relevant files: [paths]
- Patterns to follow: [reference]
- Dependencies: [other issues]
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 issue
- Relevant: Directly related to the objective
- Testable: Can be validated by running/checking
Principles for Issue Writing
- Self-Contained Context - Everything needed to understand and execute
- What, Not How - Describe outcome, not implementation
- Appropriate Granularity - Not too big, not too small
- Link to Resources - Design, API docs, related issues
- State Assumptions - Make implicit expectations explicit
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"
Mermaid Diagrams in Linear Issues
ALWAYS include Mermaid diagrams when applicable. Linear supports Mermaid diagrams natively in issue descriptions. Use them to visualize:
- User flows and interaction sequences
- Data flow and processing pipelines
- State machines and lifecycle transitions
- Component relationships and dependencies
- API/service interaction patterns
- Entity relationships and data models
Mermaid Syntax in Linear
Use standard markdown code fences with mermaid as the language identifier:
```mermaid
flowchart TD
A[Start] --> B[End]
```
Common Diagram Types
| Type | Use Case | Syntax |
|---|---|---|
flowchart TD |
Top-down user flows, process flows | flowchart TD |
flowchart LR |
Left-right horizontal flows | flowchart LR |
sequenceDiagram |
API calls, service interactions | sequenceDiagram |
stateDiagram-v2 |
State machines, status transitions | stateDiagram-v2 |
erDiagram |
Database schemas, entity relationships | erDiagram |
classDiagram |
Class relationships, component structure | classDiagram |
When to Include Diagrams
Always include a diagram when:
- Describing a multi-step process or user flow
- Explaining how components interact
- Documenting state transitions
- Showing data flow between systems
- Illustrating API call sequences
- Mapping entity relationships
The diagram should appear in:
- Parent issue "High-Level Implementation" section
- Sub-issue descriptions when flow context is needed
- Bug reports when showing expected vs actual flow
- Any issue where visual clarity aids understanding
Remember: A good issue can be executed by anyone who reads it.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
jclfocused/claude-agents
graphite-workflow
Use this skill when working with Graphite (gt) for stacked PRs, using execute-issue-graphite agent, or when the user mentions Graphite, stacking, or gt commands. Ensures proper use of gt commands instead of raw git for stack-aware operations.
jclfocused/claude-agents
vertical-slice-planning
Use this skill when discussing feature breakdown, PR structure, implementation ordering, or how to decompose work. Guides thinking about vertical slices (end-to-end functionality) rather than horizontal layers (all of one layer first). Triggers on "how should we break this down?", "what order should we implement?", "how many PRs?", or decomposition discussions.
jclfocused/claude-agents
mvp-scoping
Use this skill when discussing features, planning work, or when users describe what they want to build. Guides MVP thinking - focusing on "what's the minimum to make this work?" rather than comprehensive solutions. Triggers on phrases like "help me think through this feature", "what should we build first?", "how should we scope this?", or any feature planning discussion.
jclfocused/claude-agents
atomic-design-planning
Use this skill when discussing UI components, design systems, frontend implementation, or component architecture. Guides thinking about Atomic Design methodology - atoms, molecules, organisms - and promotes component reuse over creation. Triggers on UI/frontend discussions, "what components do we need?", "should I create a new component?", or design system questions.
jclfocused/claude-agents
linear-discipline
Use this skill when discussing code changes, implementation work, feature status, or when starting/completing development tasks. Reminds about Linear issue tracking discipline - always having an issue in progress before writing code, marking work as done, and creating issues for unexpected scope. Triggers when users mention implementing features, writing code, or checking on work status.
jclfocused/claude-agents
example-skill
Example skill - Claude will autonomously use this based on the description. Describe what this skill does and when to use it.
Didn't find tool you were looking for?