Raise issue skill for Claude Code

skill.md

name	raise-issue
description	Creates a GitHub issue (bug or feature) from a rough description, with codebase context and clarifying questions.

Raise GitHub Issue

This skill takes a rough description of a bug or feature request and produces a well-formed GitHub issue, enriched with codebase context and any clarification gathered from the user.

Workflow

1. Classify — Determine whether this is a bug or a feature from the description. If ambiguous, ask the user before proceeding.

2. Explore — Do light, targeted codebase exploration relevant to the description: find the affected files, services, or components. Use Grep and Glob to locate relevant code. Aim to understand enough to add helpful context; do not over-invest here.

3. Clarify — Identify gaps in the description that would make the issue hard to action. Ask the user up to 3 focused questions. Wait for their answers before drafting the issue. Skip questions whose answers are already clear from what was provided or from the codebase exploration.

4. Draft and create — Compose the issue body and create it via gh.

Issue Classification

Type	Issue type	Label (fallback)
Bug	Bug	bug
Feature	Feature	enhancement

Before creating the issue, check whether the repository has issue types enabled by querying the GraphQL API (see execution steps). If the repo supports issue types, use them. If not, fall back to labels.

Issue Body Format

Use this markdown template:

For bugs:

## Description
[Clear statement of what is wrong and where]

## Steps to Reproduce
1. [Step]
2. [Step]
3. [Step]

## Observed Behaviour
[Observed result]

## Expected Behaviour
[What should happen instead]

## Affected Area
[Service/component/file(s) identified during codebase exploration]

## Infosec Considerations
[Information security considerations in the implementation of a fix]

## Additional Context
[Anything else relevant: environment, frequency, related issues, code pointers]

For features:

## Description
[What is being requested and why]

## Proposed Behaviour
[How it should work from the user's perspective]

## Affected Area
[Service/component/file(s) that will likely need to change, from codebase
exploration]

## Infosec Considerations
[Information security considerations in the implementation of the feature]

## Acceptance Criteria
- [ ] [Observable outcome that confirms the feature is done]
- [ ] [Another criterion]

## Additional Context
[Related issues, design considerations, constraints]

Execution Steps

1. Parse the user's description to classify the issue type (bug or feature). If genuinely unclear, ask: "Is this a bug report or a feature request?"

2. Run focused Grep/Glob searches to locate relevant code. For a bug, find the suspected component. For a feature, find the area that would need to change. Note file paths and any relevant function/class names.

3. Identify missing information needed to write a good issue. For bugs this typically means: steps to reproduce, expected vs actual behaviour, environment details. For features: the user goal, scope, acceptance criteria. Ask only what is genuinely unknown — no padding.

4. Once you have enough information, compose the issue body using the appropriate template above. Incorporate specific file paths, component names, or code references found during exploration to make the issue immediately actionable for a developer.

5. Detect whether the repository has issue types enabled:

   gh api graphql -f query='
     query {
       repository(owner: "<owner>", name: "<repo>") {
         issueTypes(first: 50) {
           nodes { id name }
         }
       }
     }'

   If this returns issue type nodes, the repo uses issue types. Store the result as ISSUE_TYPES. If the query fails or returns an empty list, set ISSUE_TYPES to empty — the repo uses labels instead.

6. Create the issue using a heredoc for the body to prevent shell escaping of backticks or other markdown characters:

   If the repo does NOT have issue types — use labels:

   gh issue create \
     --title "<concise title>" \
     --label "bug" \
     --body "$(cat <<'ISSUE_BODY'
   <issue body>
   ISSUE_BODY
   )"

   If the repo has issue types — omit the label:

   gh issue create \
     --title "<concise title>" \
     --body "$(cat <<'ISSUE_BODY'
   <issue body>
   ISSUE_BODY
   )"

   Do NOT pass the body as a quoted string literal — this causes backticks and triple-backticks to be escaped with backslashes. Always use the heredoc form above.

7. Skip this step if ISSUE_TYPES is empty. Otherwise, set the issue type via GraphQL. Extract the issue number from the URL returned in step 6, then:

   a. Look up the id for the target type (Bug or Feature) in ISSUE_TYPES.

   b. Look up the issue's global node ID:

   gh api graphql -f query='
     query {
       repository(owner: "<owner>", name: "<repo>") {
         issue(number: <number>) { id }
       }
     }'

   c. Update the issue type:

   gh api graphql -f query='
     mutation {
       updateIssueIssueType(input: {
         issueId: "<issue_node_id>",
         issueTypeId: "<issue_type_id>"
       }) {
         issue { id }
       }
     }'

   If setting the issue type fails, note this to the user but do not fail the overall operation — the issue has already been created.

8. Output the URL of the created issue so the user can open it directly in the GitHub UI to attach screenshots or further embellish.

Important Notes

• Keep titles concise and imperative: "Driver location not updating on reassignment" not "There is a problem where the driver location..."
• The codebase exploration is a means to an end — cite specific file paths and line numbers where helpful, but do not dump large code excerpts into the issue body.
• The user will add images and further detail via the GitHub UI; focus on giving a developer enough context to reproduce or estimate the work.
• If using labels and the bug or enhancement label does not exist in the repo, gh issue create will fail. In that case, omit the --label flag and note the missing label to the user.