writing-issues skill (riekelt) for Claude Code: epics, stories, bugs and acceptance criteria

Makes Claude write tracker items that stand on their own: a clear outcome, a testable Done check, linked evidence and owners for open parts.

Installs: 20.4K; on skills.sh
Stars: 36; on GitHub
Updated: Sep 2026; last repo commit

writing-issues gives Claude a four-question test for tracker items: what outcome, what decides Done, what is the evidence and who owns the open parts. It defines five issue types, Epic, Story, Task, Bug and Spike, and gives a skeleton for stories and tasks and another for bug reports that starts from the verbatim symptom. It covers the writing only, not prioritization, and lists technical-writing as required background.

Good for

Product and engineering leads turning plans or reviews into tickets
Anyone filing a bug report that the next reader can search and reproduce
Teams that want acceptance criteria that can be tested

Install writing-issues

Claude Code

Copy this prompt.

Install the writing-issues skill in Claude Code. Run this command:

/plugin marketplace add riekelt/technical-writer
/plugin install technical-writer@technical-writer

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Pick one route, not both, or you get every skill twice. The skills CLI route must include technical-writing, which writing-issues lists as REQUIRED BACKGROUND in its SKILL.md.

From the project README. Source.

What's in the skill

When it loads

Use when writing or refining tracker items - epics, stories, tasks, bug reports, spikes, or acceptance criteria - or when turning a discussion, review finding, or plan into tickets. Encodes the survives-without-you test, the issue-type glossary, and the story and bug skeletons. Use whenever work is written into a tracker, even from a rough verbal dump.

Sections in SKILL.md

Overview
When to invoke, and not
The survives-without-you test
Issue types
Story and task skeleton
Bug report skeleton
Rules

Key facts

Author: riekelt (owner of the GitHub repo)
License: MIT (LICENSE file and plugin manifest)
Installs on skills.sh: 20,407 as of 2026-11-02
GitHub stars: 36 for the whole riekelt/technical-writer repo, 2026-11-02
What is inside: 1 file: SKILL.md
Needs: The technical-writing skill (SKILL.md lists it as REQUIRED BACKGROUND)
Part of: The technical-writer plugin: 11 skills, 2 agents and 2 commands
Last repo commit: 2026-09-13
Works in: Claude Code per the README install section. The repo also ships Codex and Cursor plugin manifests.

What it includes

Four questions every issue must answer
What outcome, what decides Done, what is the evidence behind each decision, and who owns each open part. An owner is a name, a role or an explicit unassigned.
Read · Survives-without-you test
Epic, Story, Task, Bug and Spike with one-line definitions
One glossary per tracker. A spike is done when the decision is recorded, never when someone looked into it.
Write · Issue types
Problem, outcome, acceptance, out of scope, open items, sources
Acceptance checks must be independently testable. Gherkin given-when-then is accepted when the team uses it, and INVEST works as a sizing check.
Try: “Turn these review findings into stories with acceptance checks.”
Write · Story and task skeleton
Symptom, reproduction, expected, actual, environment
The symptom is a verbatim error or observable misbehaviour. The title carries the symptom, not the diagnosis, and a suspected cause is labelled a hypothesis.
Try: “File a bug for the duplicate reminder emails.”
Write · Bug report skeleton
One home, append do not rewrite, trust code over issue status
The issue owns what and why, the plan owns how. Scope changes are dated notes. Before building on an old issue, verify it against the repository.
Read · Rules

From the official docs

Permissions

Low risk

Claude drafts tracker text from whatever you give it, so check drafts for internal details before posting them somewhere public.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

Issue text can include internal details
SKILL.md has issues link repo paths, documents and measurements as evidence. Our advice: check what a draft contains before pasting it into a public tracker. github.com
The plugin route adds 2 agents and 2 commands
The plugin ships agents prose-reviewer and doc-grounder (both with Read, Glob, Grep and Bash tools) and the commands /prose-review and /ground-docs. The plugin folder has no hooks or MCP config. Use the skills command in the install box if you want only this skill. github.com

Technical details

Turning on read-only	No read-only mode. The skill tells Claude to write or edit documents.
Sign-in and keys	SKILL.md names no account or API key.
Data retention	SKILL.md names no logging or telemetry.
Scopes	Claude drafts issue text; SKILL.md names no tracker integration

Questions

What does writing-issues do?

It makes Claude write epics, stories, tasks, bug reports and spikes so a stranger can tell the outcome, the acceptance check, the evidence and who owns what is open.

How do I install writing-issues?

Use the install box at the top of this page. The plugin route installs the whole set. The skills command route names technical-writing as well, because this skill lists it as required background.

Does it create tickets in Jira or GitHub?

SKILL.md names no tracker integration or API. It covers how items are written, and says it does not cover prioritization or workflow advice.

What if the reporter is not available?

SKILL.md says to file with named gaps rather than block. Missing details become explicitly owned open items inside the issue.

writing-issues vs writing-design-docs?

When an issue needs a design argued, that is a design doc: the writing-issues SKILL.md says the issue links the design doc and never inlines it. It also tells Claude to apply the five vagueness defects from writing-design-docs to the acceptance list, so that skill is a useful companion. The skills command in the install box does not include it; the plugin route does.

Is writing-issues safe to install?

The skill folder holds only SKILL.md, so it bundles no scripts. It writes ticket text; SKILL.md names no tracker access. Review the changes it makes to your documents, as you would any edit.

Can I use writing-issues in the Claude app or Cursor?

The README documents Claude Code, and the repo also ships Codex and Cursor plugin manifests. It does not mention the Claude app. Our advice: this page offers no Claude app upload because the skill works on documents inside a repository, so use Claude Code or Codex.

Information

updated Nov 2, 2026

Repository: riekelt/technical-writer
Folder: plugins/technical-writer/skills/writing-issues

riekelt/technical-writer skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 6

README · github.com
marketplace.json · github.com
writing-issues on skills.sh · skills.sh
SKILL.md · github.com
LICENSE · github.com
writing-design-docs SKILL.md · github.com