| 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
- Always read
.agents/team-conventions.md first if it exists at the repo root. It overrides every default in this file.
- Never create blank issues — always pick a template (
bug, feature, enhancement, docs, tech-debt).
- 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.
- 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.
- 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, chorepriority: — high, medium, lowstatus: — 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:
[[ -f .agents/team-conventions.md ]] && cat .agents/team-conventions.md
gh issue list --search "<keyword>"
gh label list
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:
gh issue edit <number> --add-label "status:approved"
gh issue edit <number> --add-label "priority:high"
gh issue edit <number> --add-label "status:blocked"
gh issue comment <number> --body "Blocked by #..."
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:
~/dotfiles/scripts/team-bootstrap.sh .
~/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).
