issue-creation

name	issue-creation
description	Team-aware GitHub issue creation workflow. Reads .agents/team-conventions.md from the current repo if it exists; falls back to relaxed defaults otherwise. Trigger: When creating a GitHub issue, reporting a bug, requesting a feature, proposing an enhancement, filing tech debt, or fixing docs.
license	Apache-2.0
metadata	{"author":"FullFran","version":"1.0","inspired_by":"gentleman-programming/agent-teams-lite"}

When to Use

Use this skill whenever the user asks to create, file, draft, or submit a GitHub issue. Also use it when triaging or approving issues as a maintainer.

For creating a pull request, use the sibling skill branch-pr instead. For exhaustive gh command coverage, see the gh-cli skill.

Critical Rules

1. Always read .agents/team-conventions.md first if it exists at the repo root. It overrides every default in this file.
2. Never create blank issues — always pick a template (bug, feature, enhancement, docs, tech-debt).
3. Never invent labels. Use only labels that already exist in the repo (gh label list). If a label is missing, ask the user before creating it.
4. Always set status:needs-triage on creation if that label exists. If the team conventions enable approval gating, also tell the user the issue must wait for status:approved before any PR can be opened against it.
5. Search for duplicates BEFORE creating — gh issue list --search "<keywords>".

Workflow

1. Read .agents/team-conventions.md (if exists)
2. Search existing issues for duplicates
3. Pick the right template (bug | feature | enhancement | docs | tech-debt)
4. Fill in mandatory fields, propose values for optional fields
5. Show the user the draft body BEFORE creating
6. Create the issue with gh issue create --template <name>.yml
7. Verify it was created and report the URL

Reading team conventions

The conventions file lives at <repo>/.agents/team-conventions.md. Sections you care about:

Section	What to do with it
## Issue-first enforcement	If require_approval: true, mention to the user that the issue will start as status:needs-triage and a maintainer must add status:approved before any PR can link it.
## Labels	Use exactly the label set documented here. Do not add labels that are not listed.
## External tracker	If set to linear or jira, link the external ticket in the issue body (the conventions file should explain how).

If the file does not exist, fall back to the defaults below.

Defaults (when no .agents/team-conventions.md)

• Issue-first enforcement: not required (PRs can be opened without a linked issue, but encouraged).
• Approval gate: none (no status:approved requirement).
• Labels available (assume they exist unless gh label list says otherwise):
  • type: — bug, feature, enhancement, docs, tech-debt, chore
  • priority: — high, medium, low
  • status: — needs-triage, in-progress, blocked, approved
  • specials: breaking-change, good-first-issue, help-wanted

Templates

The team templates live at .github/ISSUE_TEMPLATE/<type>.yml in each repo. They are GitHub YAML forms with the following types:

Template	Use when	Required fields
bug.yml	Something does not work as expected	summary, steps to reproduce, expected, actual
feature.yml	Brand new capability that does not exist yet	problem, proposed solution
enhancement.yml	Improvement to something that already works	current behavior, proposed improvement
docs.yml	Missing, unclear, outdated, or incorrect docs	kind, location, problem
tech-debt.yml	Code that works today but should be improved	affected area, what is wrong, cost of leaving it

If a repo does NOT have these templates, run team-bootstrap.sh from this dotfiles repo (or the standalone team-workflow-kit) to install them in one shot.

Decision tree

Is something user-facing broken?         → bug.yml
Is the user asking for a new capability? → feature.yml
Is the user asking to improve an existing capability? → enhancement.yml
Is it about docs only?                   → docs.yml
Is it internal code that should be improved? → tech-debt.yml
Is it a question?                        → suggest GitHub Discussions instead, NOT an issue
Is it a duplicate?                       → link to existing issue, do not create

Title format

Always use a conventional-commit-style prefix in the title, even when conventional commits are not enforced for commits. This makes triage and search easy.

Type	Title prefix	Example
bug	fix:	fix: setup.sh fails on zsh with glob error
feature	feat:	feat: add Codex support to setup.sh
enhancement	feat:	feat: improve install.sh idempotency
docs	docs:	docs: clarify multi-host config in README
tech-debt	refactor: or chore:	refactor: extract shared symlink helper

Commands

Always check the conventions and search duplicates BEFORE creating:

# 1. read conventions if they exist
[[ -f .agents/team-conventions.md ]] && cat .agents/team-conventions.md

# 2. search duplicates
gh issue list --search "<keyword>"

# 3. list available labels (do not invent ones)
gh label list

# 4. create issue with the right template
gh issue create --template "bug.yml" \
  --title "fix(scope): description"

For a full bug report body, prefer the heredoc pattern (see gh-cli skill, "Heredoc Bodies for Multi-line Text").

Maintainer actions

If the user is a maintainer triaging an issue:

# accept for implementation (only matters if approval gating is on)
gh issue edit <number> --add-label "status:approved"

# bump priority
gh issue edit <number> --add-label "priority:high"

# mark as blocked with explanation
gh issue edit <number> --add-label "status:blocked"
gh issue comment <number> --body "Blocked by #..."

# close as duplicate, link to canonical
gh issue close <number> --comment "Duplicate of #..." --reason "not planned"

Bootstrap a new repo

If a repo does not yet have any of this (no templates, no labels, no conventions file), bootstrap it in one shot:

# from inside the target repo
~/dotfiles/scripts/team-bootstrap.sh .

# or from anywhere with an absolute path
~/dotfiles/scripts/team-bootstrap.sh ~/projects/cliente-x

The script is idempotent. It will skip files that already exist (use --force to overwrite). It also creates the labels in GitHub via gh label create (skip with --no-labels).