How do I install the Issue Description skill?

Run npx skillmds@latest add spillwavesolutions/issue-description in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Issue Description safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Issue Description?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Issue Description free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Issue Description?

spillwavesolutions (@spillwavesolutions) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Issue Description by spillwavesolutions

Name: Issue Description
Author: spillwavesolutions

Issue Description

Write rich, durable issue/ticket descriptions. Use when creating or updating tickets by hand, when composing bodies for ticket-sync, or when a work item needs a description a future reader (human or agent) can act on without archaeology.

File contents

Rich issue descriptions

An issue is a durable intent record, not a task title. Issues outlive PRs and are read by more people — including future agents. Every issue should let a zero-context reader understand what, why, where it sits, and what "done" looks like.

The mechanical path (worklog-synced tickets)

For items in the event log, do not hand-write bodies: bin/worklog ticket-body <ulid> renders the item's graph node — summary (from --body), context (epic, generating plan with its frozen wiki page, milestone, unplanned provenance), and traceability (decides/implements edges, delivered-by PRs). ticket-sync pushes that. To make a ticket richer, enrich the SOURCE: worklog update --body, worklog link-pr, sidecar relates_to edges — never just the remote ticket (it would drift back).

Template (hand-written issues, or systems without worklog)

## Summary
One or two sentences: what needs to be done and why it matters.

## Context / Big picture
Where this sits in the larger system or epic. Link the parent epic and
the plan that generated it.

## Problem / Motivation
What is painful or missing today? "What"-only issues rot; "why" keeps
them useful.

## Desired outcome
What does done look like? Concrete and observable.

## Scope
In scope: ...
Explicitly out of scope: ...

## Proposed approach (optional)
High-level design or sequence if known. Link relevant ADRs/design docs.

## Acceptance criteria
- [ ] ...

## Traceability
Plan / Epic / ADRs / Spec sections / Related issues.

## Notes for implementers & agents
Traps, sequencing rules, non-obvious constraints, "never do X" guidance
written for the next agent that picks this up.

Rules

Omit sections that have no real content — no boilerplate placeholders.
Every plan-generated issue links back to its frozen plan page: the why lives in the plan, the issue carries the pointer.
Surface risks and open questions early; uncertainty stated is uncertainty managed.
Body text must be readable by a junior dev or PM: no bare ULIDs in prose (spec §13.4); ULIDs belong in the machine footer.

---name: issue-descriptiondescription: Write rich, durable issue/ticket descriptions. Use when creating or updating tickets by hand, when composing bodies for ticket-sync, or when a work item needs a description a future reader (human or agent) can act on without archaeology.---# Rich issue descriptionsAn issue is a durable intent record, not a task title. Issues outlive PRsand are read by more people — including future agents. Every issue shouldlet a zero-context reader understand what, why, where it sits, and what"done" looks like.## The mechanical path (worklog-synced tickets)For items in the event log, do not hand-write bodies:`bin/worklog ticket-body <ulid>` renders the item's graph node — summary(from `--body`), context (epic, generating plan with its frozen wiki page,milestone, unplanned provenance), and traceability (decides/implementsedges, delivered-by PRs). ticket-sync pushes that. To make a ticket richer,enrich the SOURCE: `worklog update --body`, `worklog link-pr`, sidecar`relates_to` edges — never just the remote ticket (it would drift back).## Template (hand-written issues, or systems without worklog) ## Summary One or two sentences: what needs to be done and why it matters. ## Context / Big picture Where this sits in the larger system or epic. Link the parent epic and the plan that generated it. ## Problem / Motivation What is painful or missing today? "What"-only issues rot; "why" keeps them useful. ## Desired outcome What does done look like? Concrete and observable. ## Scope In scope: ... Explicitly out of scope: ... ## Proposed approach (optional) High-level design or sequence if known. Link relevant ADRs/design docs. ## Acceptance criteria - [ ] ... ## Traceability Plan / Epic / ADRs / Spec sections / Related issues. ## Notes for implementers & agents Traps, sequencing rules, non-obvious constraints, "never do X" guidance written for the next agent that picks this up.## Rules- Omit sections that have no real content — no boilerplate placeholders.- Every plan-generated issue links back to its frozen plan page: the why lives in the plan, the issue carries the pointer.- Surface risks and open questions early; uncertainty stated is uncertainty managed.- Body text must be readable by a junior dev or PM: no bare ULIDs in prose (spec §13.4); ULIDs belong in the machine footer.

Frequently asked questions