Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Open-source issue creation: bug reports, feature requests, and structured contribution communication. Invoke whenever task involves any interaction with issues in external repositories โ filing bugs, proposing features, reporting problems, or preparing issue content for open-source projects.
Issue Writing
Every issue you file costs maintainer time. Earn that time with evidence, not prose.
Open-source maintainers are volunteers. A single low-quality issue engages 3-4 people for up to 3 hours each. AI-
generated "slop" โ vague, unverified, polished-but-empty reports โ has driven projects to shut down bug bounties, ban
reporters, and implement strict contribution policies. You are an AI agent โ the exact actor these policies target. The
only way to contribute without causing harm is to hold yourself to a higher standard than any human contributor.
References
Bug report structure โ ${CLAUDE_SKILL_DIR}/references/bug-report-structure.md Title formulas, body template, MRE
construction, regression info, supporting evidence guidelines
Feature request structure โ ${CLAUDE_SKILL_DIR}/references/feature-request-structure.md Problem-first framing,
proposed solution, alternatives, research on what drives developer engagement
Anti-slop patterns โ ${CLAUDE_SKILL_DIR}/references/anti-slop.md How maintainers detect AI slop, stylistic and
structural markers, project policies against AI contributions, verification checklist
Preparation Pipeline
Before writing a single word of an issue, complete every step.
1. Read Project Guidelines
Read CONTRIBUTING.md (check root, docs/, and .github/ directories)
Read issue templates in .github/ISSUE_TEMPLATE/ โ if templates exist, you must use them
Read CODE_OF_CONDUCT.md if present
Check for AI contribution policies. Projects like LLVM, Selenium, and Django require human review and explanation of
all AI-generated content. Some ban autonomous agent contributions entirely. If the project prohibits AI-generated
contributions, stop and inform the user โ do not file the issue.
Do not file issues against items labeled "good first issue" โ these are reserved for humans learning the project
Note the project's communication norms: formal vs. casual, expected detail level
2. Search for Duplicates
Search the project's issue tracker for both open and closed issues. Use multiple search terms โ the same problem is
often described differently by different people.
# GitHub CLI duplicate search
gh issue list -R owner/repo --search "keyword" --state all --limit 30
If you find a related issue:
Exact duplicate (open) โ do not create a new issue. Add useful new information as a comment if you have it.
Exact duplicate (closed) โ check why it was closed. If the fix didn't work or the problem recurred, reference the
closed issue in your new one.
Related but different โ proceed, but reference the related issue to show awareness.
3. Verify the Problem
Confirm you are using the latest release or the development branch
Reproduce the bug with precise steps โ if you cannot reproduce it, you cannot report it
Eliminate local environment issues: test in a clean environment, default configuration, fresh profile
For feature requests: verify the feature doesn't already exist in documentation or configuration
4. Gather Evidence
Collect concrete evidence before writing:
Exact error messages, stack traces, or log output
Version numbers (software version, OS, runtime, relevant dependencies)
Screenshots or screen recordings for visual issues
A minimal reproducible example if reporting a bug
Writing the Issue
Issue Type: Bug Report
Follow the project's issue template if one exists. If not, use this structure:
Title: Concise description of the observable problem (~10 words). Describe what breaks, not what you think causes
it.
Good: "--output json flag produces invalid JSON when input contains unicode"
Bad: "JSON output is broken"
Bad: "Bug in the parser"
Body:
Description โ one paragraph expanding the title. Include software version and environment.
Steps to reproduce โ numbered, precise steps. Each step describes action and intent.
Expected result โ what should happen. Be concrete.
Actual result โ what happens instead. Include exact error messages. Separate facts from speculation.
Minimal reproducible example โ if applicable, the smallest possible code/config that triggers the bug.
For detailed structural guidance, read the bug report reference.
Issue Type: Feature Request
Title: Describe the desired capability, not a vague wish.
Good: "Add SAML 2.0 support alongside existing OIDC authentication"
Bad: "Better authentication"
Body:
Problem or motivation โ what you're trying to accomplish and why you can't today. Developers assess project
alignment from your problem statement, not your proposed solution.
Proposed solution โ concrete description of the desired behavior.
Alternatives considered โ what else you tried or considered, and why those are insufficient.
Additional context โ mockups, code snippets, links to similar implementations in other projects.
For detailed structural guidance and research on what drives developer engagement, read the feature request reference.
Verification Gate
Before submitting, every item must pass.
Factual accuracy:
Every file, function, or API you reference exists in the current version of the project โ verified by reading the
source, not recalled from memory
Every reproduction step works when followed literally in a clean environment
Version numbers and environment details are accurate and current
Error messages are copied verbatim, not paraphrased
Completeness:
The issue follows the project's template if one exists
The title is specific enough that a maintainer can triage without reading the body
Expected and actual results are both stated explicitly (for bugs)
The problem statement explains motivation, not just the desired feature (for feature requests)
Anti-slop:
The issue contains project-specific evidence, not generic descriptions
You are not reporting documented or intended behavior as a bug
You have not included analysis or root-cause speculation you cannot verify
The tone is factual and direct โ no filler, no excessive politeness, no alarmism
No AI-typical markers: avoid em-dash heavy prose, "delve", "robust", "comprehensive", "It's worth noting"
You are not answering questions nobody asked or explaining things the maintainer already knows
User Approval Gate
Do not create the issue until the user explicitly approves it. After completing the verification gate, present the
full draft to the user โ title, body, labels, and target repository. Wait for explicit approval before executing
gh issue create or any equivalent action. The user may request changes; iterate until approved.
GitHub CLI Mechanics
When creating issues via gh:
# Create with template (preferred โ respects project conventions)
gh issue create -R owner/repo --template "bug_report.md"# Create with explicit fields
gh issue create -R owner/repo \
--title "concise problem description" \
--body "structured body content" \
--label "bug"# Create from a file (for longer issues)
gh issue create -R owner/repo \
--title "concise problem description" \
--body-file issue-body.md
Use --template when the project has issue templates โ this provides information in the structure maintainers expect.
Some projects use YAML-based issue forms (.github/ISSUE_TEMPLATE/*.yml) which enforce structured fields โ fill every
required field.
List available templates:
# List issue templates via GitHub API
gh api repos/OWNER/REPO/contents/.github/ISSUE_TEMPLATE --jq '.[].name' 2>/dev/null
# Or browse the repository directory directly
gh browse -R OWNER/REPO -- .github/ISSUE_TEMPLATE
Communication Principles
Be factual, not dramatic. "The function returns null" โ not "This critical vulnerability causes a catastrophic
failure."
Be concise, not exhaustive. Include what's needed to understand and reproduce. Omit everything else.
Be specific, not generic. Every sentence should contain information that applies to this project and this issue,
not to software in general.
Show work, not polish. A rough but verified reproduction is worth more than a beautifully formatted guess.
Respect scope. One issue per bug. One issue per feature request. Do not combine.
Worked Example
Scenario: You discovered that a CLI tool's --format json flag outputs invalid JSON when a field contains a newline
character.
Preparation:
Read CONTRIBUTING.md โ found: "Use the bug report template. Include version output."
Searched issues โ found #342 (closed, different cause: unicode in filenames). No exact duplicate.
Verified on latest release (v2.4.1) with default config.
Title:--format json produces invalid JSON when field values contain newlines
Body:
**Version:** v2.4.1 on macOS 14.5 (Apple Silicon)
**Description**
The `--format json` flag produces output with unescaped newline characters inside
JSON string values, resulting in invalid JSON that breaks downstream parsers.
**Steps to reproduce**
1. Install tool v2.4.1
2. Create input: `echo -e "line1\nline2" > test.txt`
3. Run: `tool process test.txt --format json`
4. Pipe output to a JSON validator: `tool process test.txt --format json | jq .`
**Expected result**
Valid JSON with newlines escaped as `\n` inside string values.
**Actual result**
jq exits with error: `parse error (Invalid string) at line 3, column 0`.
Raw output contains a literal newline inside the JSON string value.
**Minimal reproducible example**
[attached as gist: link]
Integration
pr-contribution โ sibling skill. Use when submitting code changes. If filing an issue and then implementing the
fix, invoke both skills sequentially.
Critical Rules
Never file an issue you cannot verify. If you haven't reproduced the bug, don't report it. If you haven't
confirmed the feature doesn't exist, don't request it.
Never reference code you haven't read. Every function name, file path, and API endpoint in your issue must come
from reading the current source โ not from training data, not from similar projects, not from assumption.
Always use project templates when available. Ignoring templates signals that you didn't read the contribution
guidelines.
Always search before filing. Duplicate issues waste maintainer time and erode trust.
Never include unverified root-cause analysis. Speculation about why a bug occurs, when wrong, actively misleads
maintainers. Report what you observe. Let maintainers diagnose causes.
Never create without approval. Present the complete draft to the user and wait for explicit approval before
submitting.
