Build a /new-issue skill and stop writing issues by hand

John Long
AI · Workflow
Illustration of a crow delivering a letter to a mailbox

This is the last post in my series on skills for dev workflow. I've covered building /next-task and extracting /approve. Now let's build the skill that feeds the whole pipeline: /new-issue.

The idea is simple. You spot a bug or think of a feature and describe it in a sentence or two — as vague as you want. The agent examines your codebase, figures out the context, and files a well-structured issue in your tracker. No tab-switching. No filling out forms. Just describe what you noticed and move on.

Here's what I wanted my /new-issue skill to do:

  1. Parse a plain-English description of the issue
  2. Examine the codebase for relevant context
  3. Detect whether it's a bug or a feature
  4. Generate a structured issue with a description, ASCII wireframes (for UI tasks), and acceptance criteria
  5. Label bugs with "Bug" and prefix the title with "Bug:"
  6. File it in Linear with a "Triage" status under the current milestone

Start with a prompt

Like /next-task, you don't need to write this skill by hand. Just ask your agent to build it for you. Edit this starter prompt to taste:

Create a `/new-issue` skill for this project. When I run it with a description, it should examine the codebase to understand the context, then create a well-structured Linear issue. Detect whether it's a bug or a feature — if it's a bug, prefix the title with "Bug:" and add a "Bug" label. Every issue should have a brief description at the top, ASCII wireframes for anything that affects the UI, and acceptance criteria as a checkbox list at the end. File the issue with "Triage" status under the current milestone project. Before writing the skill, consult the latest documentation for skills to ensure that it's in the right format.
Create a `/new-issue` skill for this project. When I run it with a description, it should examine the codebase to understand the context, then create a well-structured Linear issue. Detect whether it's a bug or a feature — if it's a bug, prefix the title with "Bug:" and add a "Bug" label. Every issue should have a brief description at the top, ASCII wireframes for anything that affects the UI, and acceptance criteria as a checkbox list at the end. File the issue with "Triage" status under the current milestone project. Before writing the skill, consult the latest documentation for skills to ensure that it's in the right format.

Adapt this for your own setup. If you use Jira instead of Linear, say so. If you use GitHub Issues, same thing. The agent will figure out the right API calls. You'll also need to make sure the right tools are installed — I recommend the official Linear MCP for Linear and the gh command line tool for GitHub.

Surprisingly good issues

Here's the thing I didn't expect: the issues Claude writes are genuinely good. Clear descriptions, specific acceptance criteria, relevant context pulled from the codebase. It's the kind of issue you actually want to pick up and work on — which is more than I can say for a lot of issues I've seen over the years.

When you type something vague like "the settings page is broken on mobile," the agent doesn't just parrot that back into a form field. It reads your code. It finds the settings page component, looks at how it's laid out, and writes a specific report about what's likely going wrong. The acceptance criteria are testable. The description has context.

This matters more than it sounds. Bad issues slow everything down. Vague descriptions lead to back-and-forth. Missing acceptance criteria mean the implementer has to guess when they're done. A well-written issue is a force multiplier, and it turns out an agent with access to your codebase is really good at writing them.

ASCII wireframes as a design tool

My favorite part of my /new-issue skill is that the agent makes wireframes. For any issue that affects the UI, the agent generates ASCII mockups using box-drawing characters — dropdowns, modals, context menus, form layouts. They look something like this:

┌────────────────────────────────────────┐
│  Move "My Document"                    │
├────────────────────────────────────────┤
│                                        │
│  Organization                          │
│  ┌──────────────────────────────────┐  │
│  │ Acme Corp                      ▼ │  │
│  └──────────────────────────────────┘  │
│                                        │
│  Project                               │
│  ┌──────────────────────────────────┐  │
│  │ Select a project...            ▼ │  │
│  └──────────────────────────────────┘  │
│                                        │
│                    [Cancel]  [Move]    │
└────────────────────────────────────────┘
┌────────────────────────────────────────┐
│  Move "My Document"                    │
├────────────────────────────────────────┤
│                                        │
│  Organization                          │
│  ┌──────────────────────────────────┐  │
│  │ Acme Corp                      ▼ │  │
│  └──────────────────────────────────┘  │
│                                        │
│  Project                               │
│  ┌──────────────────────────────────┐  │
│  │ Select a project...            ▼ │  │
│  └──────────────────────────────────┘  │
│                                        │
│                    [Cancel]  [Move]    │
└────────────────────────────────────────┘

These are incredibly useful and easy to edit. I'll open a task in Linear, look at the wireframe, and start making adjustments right there — changing the layout, adding a field, rethinking the flow. That's often where the design happens before I ever open Figma.

Later, I'll replace the ASCII wireframes with a proper Figma mockup if needed, but having something visual to begin with kickstarts the design process.

What a session looks like

Here's /new-issue filing a bug:

> /new-issue Documents show the file name instead of the title in the sidebar

Examining codebase for sidebar document list...
Found DocumentList component rendering item.filename.

Created PIX-53: Bug: Documents show file name instead of
title in sidebar

  Documents in the sidebar are displaying the file name
  instead of the document title.

  ## Current Behavior

  ┌─────────────────────────┐
  │ My Project              │
  │   my-document.md        │  <- file name
  │   another-doc.md        │
  │   meeting-notes.md      │
  └─────────────────────────┘

  ## Expected Behavior

  ┌─────────────────────────┐
  │ My Project              │
  │   My Document           │  <- document title
  │   Another Doc           │
  │   Meeting Notes         │
  └─────────────────────────┘

  ## Acceptance Criteria
  - [ ] Document list displays the document title
  - [ ] Falls back to file name if no title is present
  - [ ] Title updates when document is renamed

  Labels: Bug
> /new-issue Documents show the file name instead of the title in the sidebar

Examining codebase for sidebar document list...
Found DocumentList component rendering item.filename.

Created PIX-53: Bug: Documents show file name instead of
title in sidebar

  Documents in the sidebar are displaying the file name
  instead of the document title.

  ## Current Behavior

  ┌─────────────────────────┐
  │ My Project              │
  │   my-document.md        │  <- file name
  │   another-doc.md        │
  │   meeting-notes.md      │
  └─────────────────────────┘

  ## Expected Behavior

  ┌─────────────────────────┐
  │ My Project              │
  │   My Document           │  <- document title
  │   Another Doc           │
  │   Meeting Notes         │
  └─────────────────────────┘

  ## Acceptance Criteria
  - [ ] Document list displays the document title
  - [ ] Falls back to file name if no title is present
  - [ ] Title updates when document is renamed

  Labels: Bug

Notice the "Bug:" prefix, the "Bug" label, and the current/expected wireframes. One sentence in, a fully structured issue out. Filed in Linear in my Backlog or Triage column. When I'm ready I can review the issue, make any changes required, and move it to the "To do" column where it can be picked up by /next-task.

Iterate as you go

Like any skill, /new-issue gets better as you refine it. A few things my skill now includes:

  • Wireframe guidelines – I included examples of common UI patterns (modals, context menus, form layouts) in the skill so the agent produces consistent wireframes.
  • Bug detection keywords – a list of words like "broken," "should," and "instead of" that help the agent distinguish bugs from features.
  • Acceptance criteria style – I asked for each criterion to start with an action verb and include edge cases.

Start simple. You'll know what to add after you've used it a few times.

The virtuous cycle

This wraps up my series on three skills for dev workflow. The three skills form a loop:

  • /new-issue – captures bugs and feature ideas the moment you think of them.
  • /next-task – pulls the highest-priority issue out of the issue tracker, implements it, and opens a PR.
  • /approve – ships it when you're satisfied.

Each skill feeds the next. File an issue, pick it up, ship it, repeat. The mechanical overhead of moving work through a pipeline disappears. What's left is the work itself.

The more I use this workflow, the more natural it feels. The tools get out of the way and I just build.

Share this post!

Comments

Loading comments...

You might also like…

Extracting sub-skills from agent skills

John LongAI

As your agent skills grow, some parts want to be their own thing. Here's how I used a simple prompt to extract a standalone /approve skill from my /next-task skill — and why thinking of skills like functions leads to better workflows.

If software becomes ephemeral

John LongAI

When software can be conjured from a conversation, the real differentiator won't be the code — it'll be the taste, the brand, and the vision behind it.