Skill

report-bug

Gathers structured bug details, reproduction steps, errors, and environment info for spec-first plugin issues, then formats a GitHub issue. Use for agent, command, skill, or MCP problems.

Bash

Github

Markdown

developer-tools

npx claudepluginhub sunrain520/spec-first

Tool Access

This skill uses the workspace's default tool permissions.

Preview

Report bugs encountered while using the spec-first plugin. This skill gathers structured information and creates a GitHub issue for the maintainer.

SKILL.md

Similar Skills

report-bug-ce

13.2k

Guides users to report bugs in compound-engineering plugin by gathering details, env info, formatting Markdown, and creating GitHub issues.

compound-engineering

ac-issue

Creates GitHub issues in WaterplanAI/agentic-config repo for bugs and feature requests using GitHub CLI. Handles templates, explicit args, or extracts from conversation context. Invoke via /ac-issue.

2 tools

ac-tools

issue-reporting

Guides reporting bugs in GTM skills: collects skill name, prompt, actual/expected output, context files like brand.md; classifies issue; generates formatted GitHub issue.

gtm-skills

Stats

Stars23

Forks4

Last CommitApr 25, 2026

Actions

View Source View Plugin View on GitHub View README

Help us improve

Share bugs, ideas, or general feedback.

Report a Spec-First Plugin Bug

Report bugs encountered while using the spec-first plugin. This skill gathers structured information and creates a GitHub issue for the maintainer.

Step 1: Gather Bug Information

Ask the user the following questions using the platform's blocking question tool: AskUserQuestion in Claude Code (call ToolSearch with select:AskUserQuestion first if its schema isn't loaded) or request_user_input in Codex. Fall back to numbered options in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question:

Question 1: Bug Category

What type of issue are you experiencing?
Options: Agent not working, Command not working, Skill not working, MCP server issue, Installation problem, Other

Question 2: Specific Component

Which specific component is affected?
Ask for the name of the agent, command, skill, or MCP server

Question 3: What Happened (Actual Behavior)

Ask: "What happened when you used this component?"
Get a clear description of the actual behavior

Question 4: What Should Have Happened (Expected Behavior)

Ask: "What did you expect to happen instead?"
Get a clear description of expected behavior

Question 5: Steps to Reproduce

Ask: "What steps did you take before the bug occurred?"
Get reproduction steps

Question 6: Error Messages

Ask: "Did you see any error messages? If so, please share them."
Capture any error output

Step 2: Collect Environment Information

Automatically gather environment details. Detect the coding agent platform and collect what is available:

OS info (all platforms):

uname -a

Plugin version: Read the plugin manifest or installed plugin metadata. Common locations:

Claude Code: ~/.claude/plugins/installed_plugins.json
Codex: .codex/plugins/ or project config
Other platforms: check the platform's plugin registry

Agent CLI version: Run the platform's version command:

Claude Code: claude --version
Codex: codex --version
Other platforms: use the appropriate CLI version flag

If any of these fail, note "unknown" and continue — do not block the report.

Step 3: Format the Bug Report

Create a well-structured bug report with:

## Bug Description

**Component:** [Type] - [Name]
**Summary:** [Brief description from argument or collected info]

## Environment

- **Plugin Version:** [from plugin manifest/registry]
- **Agent Platform:** [Claude Code or Codex]
- **Agent Version:** [from CLI version command]
- **OS:** [from uname]

## What Happened

[Actual behavior description]

## Expected Behavior

[Expected behavior description]

## Steps to Reproduce

1. [Step 1]
2. [Step 2]
3. [Step 3]

## Error Messages

[Any error output]

## Additional Context

[Any other relevant information]

---
*Reported via `/report-bug` skill*

Step 4: Create GitHub Issue

Use the GitHub CLI to create the issue:

gh issue create \
  --repo sunrain520/spec-first \
  --title "[spec-first] Bug: [Brief description]" \
  --body "[Formatted bug report from Step 3]" \
  --label "bug,spec-first"

Note: If labels don't exist, create without labels:

gh issue create \
  --repo sunrain520/spec-first \
  --title "[spec-first] Bug: [Brief description]" \
  --body "[Formatted bug report]"

Step 5: Confirm Submission

After the issue is created:

Display the issue URL to the user
Thank them for reporting the bug
Let them know the maintainer (Kieran Klaassen) will be notified

Output Format

Bug report submitted successfully!

Issue: https://github.com/sunrain520/spec-first/issues/[NUMBER]
Title: [spec-first] Bug: [description]

Thank you for helping improve the spec-first plugin!
The maintainer will review your report and respond as soon as possible.

Error Handling

If gh CLI is not installed or not authenticated: prompt the user to install/authenticate first
If issue creation fails: display the formatted report so the user can manually create the issue
If required information is missing: re-prompt for that specific field

Privacy Notice

This skill does NOT collect:

Personal information
API keys or credentials
Private code from projects
File paths beyond basic OS info

Only technical information about the bug is included in the report.