yasukei/agent-skills

GitHub Issue erstellen

Skill zum Erstellen von Issues in einem vom Benutzer festgelegten Format. Ziel ist es, jedes Mal Issues mit der gleichen Struktur zu erstellen, die nach dem Lesen direkt bearbeitet und auf Abschluss geprüft werden können. Insbesondere die Acceptance Criteria werden später in Tools wie issue-to-pr als Bedingungen für die Implementierung und Überprüfung verwendet und müssen daher überprüfbar formuliert sein.

1. Zuerst Repository-Vorlagen prüfen

Wenn das Repository eigene Vorlagen hat, haben diese Vorrang vor der Vorlage dieses Skills. Prüfpfade:

• .github/ISSUE_TEMPLATE/ mit *.md und *.yml / *.yaml (config.yml ist eine Konfigurationsdatei, keine Vorlage)
• .github/ISSUE_TEMPLATE.md, ISSUE_TEMPLATE.md im Stammverzeichnis, docs/ISSUE_TEMPLATE.md
• Falls nichts davon existiert, das gemeinsame Repository des Besitzers <owner>/.github an denselben Pfaden prüfen

Wenn ein lokaler Clone existiert, die Dateien direkt ansehen. Andernfalls mit gh api repos/<owner>/<repo>/contents/.github/ISSUE_TEMPLATE abrufen.

Wurde eine Vorlage gefunden:

• Eine Vorlage auswählen, die zum gewünschten Issue-Typ (Task / Bug) passt, anhand von Dateiname, name, about und labels.
• Die Überschriftenstruktur der Vorlage übernehmen und keine Überschriften dieses Skills einmischen. Nur wichtige Informationen (wie Abhängigkeiten), die in der Vorlage keinen Platz haben, kurz am Ende anhängen.
• Bei YAML-Issue-Forms speichert GitHub die Formulardaten als Text mit der Überschrift ### <label> für jedes attributes.label. Den Text genauso aufbauen und Pflichtfelder (required: true) immer ausfüllen.
• Den title (Präfix), labels und assignees aus dem Frontmatter / der Formulardefinition der Vorlage übernehmen.

Wenn es keine passende Vorlage für den Typ gibt (z. B. Bug-Vorlage vorhanden, aber keine für Tasks), nur für diesen Typ die untenstehende Vorlage verwenden.

2. Typ bestimmen

• Task: Neue Funktion, Verbesserung, Refactoring, Dokumentation, CI, Recherche usw. („etwas tun“). → Task-Vorlage
• Bug: Fehlerbehebung, wenn das Verhalten nicht der Erwartung entspricht. → Bug-Vorlage

Bei Unsicherheit: „Widerspricht das aktuelle Verhalten der Spezifikation?“ Wenn ja, ist es ein Bug.

3. Task-Vorlage

## Goal

<In 1–2 Sätzen, was erreicht werden soll. Auch kurz erwähnen, warum es nötig ist>

## Scope

- <Was getan wird. Bei mehreren zusammenhängenden Blöcken mit **fettgedruckten Unterüberschriften** gruppieren>

## Out of scope

- <Was nicht getan wird. Benachbarte Bereiche, die leicht missverstanden werden, explizit ausschließen>

## Acceptance criteria

- <Bedingungen, die den Abschluss überprüfbar machen. Test, CI, Kommandoausgabe usw. – in beobachtbarer Form>

## Depends on

- #<Nummer>

Part of #<Parent-Issue-Nummer>.

Schreibtipps:

• Goal: Neben dem „Was“ auch das „Warum“ kurz nennen. So können spätere Leser Priorität und Entscheidungen nachvollziehen.
• Scope: So granular formulieren, dass der Implementierende nicht zögern muss. Typnamen, Kommandos, Dateipfade usw. konkret angeben. Punkte, die aus vorherigen Reviews übernommen wurden, mit einer entsprechenden Unterüberschrift kennzeichnen.
• Out of scope: Explizit schreiben, was „diesmal nicht“ gemacht wird, um Scope Creep zu verhindern. Wenn es wirklich nichts gibt, - None schreiben, den Abschnitt aber stehen lassen (damit klar ist, dass er nicht vergessen wurde).
• Acceptance criteria: Nicht „… ist implementiert“, sondern „… Test existiert und läuft durch“, „CI führt … aus und ist erfolgreich“ – so, dass ein Dritter es überprüfen kann.
• Depends on: Issues, die zuerst abgeschlossen sein müssen, als - #Nummer auflisten (GitHub zeigt sie dann mit Titel an). Falls keine: - None.
• Wenn der Task aus einem Parent-Issue aufgeteilt wurde, am Ende Part of #<Nummer>. schreiben.
• Nur wenn es Hintergrundmaterial, Referenzlinks oder offene Punkte gibt, nach den Acceptance Criteria einen Abschnitt ## Notes hinzufügen. Nicht künstlich erzeugen.

4. Bug-Vorlage

## Summary

<In 1–2 Sätzen, was passiert>

## Steps to reproduce

1. <Schritt>
2. <Schritt>

## Expected behavior

<Was eigentlich passieren sollte>

## Actual behavior

<Was tatsächlich passiert. Fehlermeldungen und Logs in Codeblöcke setzen>

## Environment

- Version / commit: <Version oder Commit-Hash>
- <OS / Browser / Node usw. – alles Relevante>

## Acceptance criteria

- Bei den obigen Schritten tritt das Expected behavior ein
- Ein Regressionstest, der den Bug reproduziert, wurde hinzugefügt und läuft durch

## Notes

<Verdacht auf Ursache, verknüpfte Issues/PRs, Workarounds usw. Wenn nichts, diesen Abschnitt weglassen>

Schreibtipps:

• Schritte, Umgebung und Logs nur schreiben, wenn sie vom Benutzer gehört oder selbst bestätigt wurden. Unbekannte Felder nicht raten – Unknown schreiben oder den Benutzer fragen. Erfundene Reproduktionsschritte führen zu falschen Recherchen.
• Ursachenverdacht getrennt von Fakten (Actual behavior) in den Notes notieren. Wenn Symptome und Hypothesen vermischt werden, wird das Issue schwer lesbar, falls die Hypothese falsch ist.
• Wenn die Korrekturrichtung bereits klar ist, ebenfalls in Notes schreiben.

5. Titel, Labels und Metadaten

• Titel nach dem Schema <Bereich>: <Inhalt> (z. B. core: data types, tree IR, and UI–runtime protocol). Bereich an vorhandene area:*-Labels oder andere Kategorien des Repos anpassen. Bei Bugs den Symptom beschreiben, nicht den Korrekturinhalt (z. B. runtime: TON timer does not fire after coldReset).
• Labels aus den vorhandenen mit gh label list auswählen. Neben Bereichs-Labels bei Bugs bug hinzufügen, falls vorhanden. Keine nicht existierenden Labels selbst erzeugen.
• Meilenstein und Parent-Issue setzen, falls bekannt.
• Sprache des Titels und des Texts an die bestehenden Issues und PRs des Repos anpassen (mit gh issue list --state all --limit 10 und gh pr list --state all --limit 10 prüfen). Wenn es weder Issues noch PRs gibt, auf Japanisch schreiben.
• Abschnittsnamen (Goal, Scope, Summary, Steps to reproduce usw.) auch bei japanischem Text auf Englisch belassen. Bei Verwendung einer Repository-Vorlage deren Überschriften direkt übernehmen.

6. Erstellen

Den Text in eine temporäre Datei schreiben und mit --body-file übergeben (um Probleme mit Shell-Quoting zu vermeiden).

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

• Wenn der Benutzer explizit „erstellen“ gesagt hat, direkt erstellen. Bei nur einer Bitte um einen Entwurf oder wenn viele Inhalte geraten wurden, den Text zeigen und vor dem Erstellen bestätigen lassen.
• Wenn ein Parent-Issue existiert, zusätzlich zum Part of #N. im Text auch als GitHub Sub-Issue verknüpfen (mit gh api via POST /repos/<owner>/<repo>/issues/<Parent-Nummer>/sub_issues, wobei sub_issue_id die id des Kind-Issues ist, nicht die Nummer). Falls die API nicht verfügbar ist, reicht die Angabe im Text.
• Bei der Erstellung mehrerer Issues in Abhängigkeit: zuerst das Issue erstellen, von dem andere abhängen, damit die Nummern in Depends on korrekt sind.
• Nach der Erstellung die Issue-URL mitteilen.