How to use the GitHub Issue Creation agent skill (issue-creation)

What the issue-creation skill makes the agent do

When the skill is active, the agent follows a fixed procedure before writing to GitHub. It confirms the exact target repository, reads the repository's YAML issue form and policy, searches open and closed issues for duplicates, and only then drafts or creates an issue.

The skill also covers commenting on existing issues and changing labels. It refuses to add protected labels such as status:approved unless the actor has the right permissions and a human has given explicit instruction.

The skill is documentation the agent follows. It is not a standalone tool, and it does not enforce permissions itself. Access is still controlled by GitHub.

• Confirms the exact target as HOST/OWNER/REPO before reading or writing
• Reads the repository's issue format policy and selected form
• Runs one open-and-closed duplicate search before any write
• Comments on a matching existing issue instead of filing a duplicate when the candidate conforms
• Stops on missing facts instead of guessing

Install the skill with a ZIP or the Claude apps

Download the skill ZIP from this page. To make it available to all your projects, unzip it into ~/.claude/skills/. To limit it to one project, unzip it into that project's .claude/skills/ folder.

If you use the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into the project's .claude/skills/
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Prepare GitHub CLI access before you start

The skill uses the GitHub CLI (gh). It must be installed and authenticated to the host that hosts the target repository. The account you use needs permission to create issues in that repository.

For protected label changes, the account needs MAINTAIN or ADMIN permission. TRIAGE is not enough for protected labels.

• GitHub CLI (gh) installed and authenticated to the target host
• Repository access with permission to create issues
• MAINTAIN or ADMIN permission for protected label changes

Trigger the skill with a natural request

The skill activates on requests about issue creation, bug reports, feature requests, or issue approval. Name the repository explicitly so the agent does not have to guess which one you mean. Use the HOST/OWNER/REPO form when you can.

Good requests say what happened or what you want, and which repository it belongs to. The agent will ask for any fact it cannot verify.

• "Draft a bug report for github.com/OWNER/REPO about the login timeout I saw today."
• "Check whether this feature request already exists in OWNER/REPO before filing it."
• "Comment on issue #NUMBER in OWNER/REPO with the reproduction steps I just gave you."
• "Add the approved label to issue #NUMBER in OWNER/REPO."

What the agent checks before creating an issue

Before a create, the agent works through the repository's issue format. If the repository uses a YAML form, the agent fills the form's declared fields and does not fall back to Markdown. If the repository has no template and permits issues, the agent uses a concise Markdown body.

Duplicate search covers open and closed issues and happens before any write. If a matching issue already covers the behavior and meets the repository's format, the agent comments there instead. If the match lacks required information, the agent asks the author to repair it rather than rewriting it.

• Exact target repository confirmed
• Repository issue form or template read
• Open and closed issues searched for duplicates
• Labels checked to exist and be permitted for the actor
• One create attempt, with no blind retry

Safety notes: scripts and network access

This skill runs scripts and uses the network. It calls GitHub through the gh command, so it reads repository data and may create or change issues and comments on the host you authenticated to. Review what the agent proposes before you approve a write.

Body text is kept in private temporary files outside the repository, and the agent is told not to print the contents of protected files. Protected labels such as status:approved, size:exception, and any repository-defined gate-override label need explicit human instruction naming the exact issue or PR, the exact host and repository, and the action.

• Runs scripts and uses the network
• Writes go to the host and repository you name
• Protected labels need explicit human instruction and sufficient permission
• Permission enforcement comes from GitHub, not from the skill

Tips for reliable results

Give the agent the exact repository and what you observed. The more specific the report, the less the agent needs to ask.

If the agent stops, read the missing fact it names. It is designed to stop rather than guess, so a stop is usually the correct outcome.

Use the skill on repositories that use YAML Issue Forms. The skill does not fall back to Markdown when a required form is present.

• Name the repository in HOST/OWNER/REPO form when possible
• Describe observed behaviour, not just a conclusion
• Expect questions when required fields are missing
• Check the result on GitHub before relying on it