yasukei/agent-skills

Creating GitHub Issues

A skill for writing issues in a user-defined format. The goal is to create issues that have the same structure every time and can be read and acted upon or completed immediately. In particular, Acceptance Criteria are used directly as completion conditions when implementing or reviewing later (e.g., with issue-to-pr), so they must be written in a verifiable way.

1. Check Repository Templates First

If the repository has templates, they take precedence over this skill's templates as the repository's rules. Check these locations:

• .github/ISSUE_TEMPLATE/ directory for *.md and *.yml / *.yaml (note: config.yml is a configuration file, not a template)
• .github/ISSUE_TEMPLATE.md, root ISSUE_TEMPLATE.md, docs/ISSUE_TEMPLATE.md
• If none of the above exist, check the owner's shared repository <owner>/.github in the same locations

If a local clone is available, check the files directly. Otherwise, retrieve them using gh api repos/<owner>/<repo>/contents/.github/ISSUE_TEMPLATE or similar.

When a template is found:

• Select the one matching the type of issue you are creating (task / bug) based on the filename, name, about, and labels.
• Follow the template's heading structure; do not mix in this skill's headings. Only add crucial information (e.g., dependencies) that has no designated place in the template, appended briefly at the end.
• For YAML issue forms, GitHub saves form submissions as body text with ### <label> headings, where <label> is the attributes.label. Assemble the body in the same way, ensuring all required: true fields are filled.
• Apply the title (prefix), labels, and assignees from the template's front matter/form definition.

If no matching template for the type exists (e.g., a bug template exists but no task template), only then use the corresponding template from this skill.

2. Determine the Type

• Task: New features, improvements, refactoring, documentation, CI, research — "things to do". → Task template
• Bug: Fixes for behavior that is not working as expected. → Bug template

If unsure, decide based on "Does the current behavior violate the specification?" If yes, it's a bug.

3. Task Template

## Goal

<Briefly describe what to achieve in 1-2 sentences. Add a note on why it's needed.>

## Scope

- <Things to do. If there are multiple groups, use **bold subheadings** to group them.>

## Out of scope

- <Things not to do. Clearly mention adjacent areas that might cause confusion.>

## Acceptance criteria

- <Conditions that determine completion. Should be observable, e.g., tests, CI, command results.>

## Depends on

- #<number>

Part of #<parent issue number>.

Writing tips:

• Goal: Include not just "what" but also a brief note on "why". This helps future readers understand priority and decision rationale.
• Scope: Be specific enough that the implementer does not get lost. Mention types, command names, file names, etc. If items are carried over from a previous review, separate them with a recognizable subheading.
• Out of scope: Explicitly state what is not included in this issue to prevent scope creep. If there is truly nothing, write - None, but keep the section to show it was deliberately considered empty.
• Acceptance criteria: Write in a verifiable way, e.g., "Tests exist and pass", "CI runs and succeeds", not " is implemented".
• Depends on: List issues that must be completed first using - #number (GitHub will display them with titles). If none, write - None.
• If this is a subtask from a parent issue, append Part of #<number>..
• Only add a ## Notes section after Acceptance Criteria if there are background materials, reference links, or undecided items. Do not force it.

4. Bug Template

## Summary

<Describe the problem in 1-2 sentences.>

## Steps to reproduce

1. <step>
2. <step>

## Expected behavior

<What should happen instead.>

## Actual behavior

<What actually happens. Paste error messages or logs in code blocks.>

## Environment

- Version / commit: <version or commit hash>
- <Relevant environment details: OS / browser / Node, etc.>

## Acceptance criteria

- Following the reproduction steps above, the expected behavior occurs.
- A regression test reproducing this bug is added and passes.

## Notes

<Any suspected cause, related issues/PRs, workarounds. Omit this section if there's nothing to note.>

Writing tips:

• Only include information you directly heard from the user or observed yourself for steps, environment, and logs. If a field is unknown, do not guess; write Unknown or ask the user. Fictional reproduction steps can mislead the investigation.
• Separate suspected causes from facts (actual behavior) by placing them in Notes. Mixing symptoms with hypotheses makes the issue harder to read if the hypothesis turns out to be wrong.
• If the fix strategy is already decided, also write it in Notes.

5. Title, Labels, and Metadata

• Title format: <area>: <description> (e.g., core: data types, tree IR, and UI–runtime protocol). Match the area to existing labels like area:* in the repository. For bugs, describe the symptom, not the fix (e.g., runtime: TON timer does not fire after coldReset).
• Labels: Choose from existing labels using gh label list. In addition to area labels, add the bug label for bugs if it exists. Do not create non-existent labels.
• If a milestone or parent issue is known, set them.
• Language: Match the existing issues and PRs in the repository. Check with gh issue list --state all --limit 10 and gh pr list --state all --limit 10. If no existing issues or PRs exist, write in Japanese.
• Section names (Goal, Scope, Summary, Steps to reproduce, etc.) remain in English even if the body is in Japanese. However, if using a repository template, use its headings exactly.

6. Creating the Issue

Write the body to a temporary file and pass it using --body-file (to prevent shell quoting from mangling the body).

gh issue create --repo <owner>/<repo> \
  --title "<title>" --body-file /tmp/issue-body.md \
  --label "<label>" --milestone "<milestone>"

• If the user explicitly says "create", go ahead and create it. If only a draft is requested, or if much of the content is filled in by guesswork, show the body for confirmation first, then create.
• If there is a parent issue, in addition to writing Part of #N. in the body, also link it as a GitHub sub-issue (using gh api with POST /repos/<owner>/<repo>/issues/<parent number>/sub_issues, passing the child issue's id instead of its number for sub_issue_id). If the API is not available, the body text is sufficient.
• When creating multiple issues from a split, create them in dependency order so that the Depends on sections contain the actual numbers.
• After creation, inform the user of the issue URL.