GitHub CLI — issues, milestones, and discussion for analysis
Use gh to work with GitHub issues: first run an interactive check—if gh is not installed, stop, ask whether the user wants installation guidance (see the consultative pattern in 112-java-maven-plugins, Maven Wrapper step), wait for an answer, then continue. When gh is available, confirm auth, list issues with optional milestone filters, render markdown tables from --json output, load full issue bodies and comment threads for analysis, and when the user wants user stories plus Gherkin, chain to @014-agile-user-story using issue content as source material for the interactive questionnaire.
What is covered in this Skill?
- Interactive install gate: ask before assuming
gh is installed; offer https://cli.github.com/ and OS hints when the user agrees
- Install/auth checks (
gh --version, gh auth status, gh auth login)
- Repository context (
--repo, inferred from git remote)
- Issue lists: states, limits, milestone filter,
gh issue list --json for tabular output
- Milestone discovery via
gh api when titles are unknown
- Deep reads:
gh issue view with --json (body, comments) or --comments
Constraints
Do not fabricate issue data; use only gh output (or explicitly agreed public REST API responses). Never print tokens or secrets.
- INTERACTIVE GATE: If
gh is missing, stop, ask whether the user wants installation guidance, wait—do not skip to issue listing
- FIRST (after gate): Verify
gh is available before issuing subcommands
- TABLES: Prefer
--json + markdown pipe tables for issue list summaries
- THREAD: For analysis, include body and all comments (or explicitly summarize with omissions noted)
- 014: For user stories from issues, use
@014-agile-user-story and align answers with GitHub-sourced text
When to use this skill
- gh issue list
- List GitHub issues
- Issues in milestone
- GitHub CLI issues
- gh issue view comments
Reference
For detailed guidance, examples, and constraints, see references/021-tooling-github.md.
1---2name: 021-tooling-github3description: Use when you need the GitHub CLI (`gh`) to verify installation, list issues (all or by milestone) as markdown tables, fetch issue bodies and comments for analysis, or hand off to @014-agile-user-story when creating user stories from GitHub threads. Uses an interactive install gate — if `gh` is missing, ask whether to show installation guidance before any issue commands. Part of the skills-for-java project4license: Apache-2.05---6# GitHub CLI — issues, milestones, and discussion for analysis
7
8Use **`gh`** to work with GitHub issues: **first** run an **interactive** check—if `gh` is not installed, **stop**, ask whether the user wants installation guidance (see the consultative pattern in **`112-java-maven-plugins`**, Maven Wrapper step), **wait** for an answer, then continue. When `gh` is available, confirm auth, list issues with optional milestone filters, render **markdown tables** from `--json` output, load **full issue bodies and comment threads** for analysis, and when the user wants user stories plus Gherkin, **chain to `@014-agile-user-story`** using issue content as source material for the interactive questionnaire.
9
10**What is covered in this Skill?**
11
12- **Interactive** install gate: ask before assuming `gh` is installed; offer https://cli.github.com/ and OS hints when the user agrees
13- Install/auth checks (`gh --version`, `gh auth status`, `gh auth login`)
14- Repository context (`--repo`, inferred from git remote)
15- Issue lists: states, limits, milestone filter, `gh issue list --json` for tabular output
16- Milestone discovery via `gh api` when titles are unknown
17- Deep reads: `gh issue view` with `--json` (body, comments) or `--comments`
18
19## Constraints
20
21Do not fabricate issue data; use only `gh` output (or explicitly agreed public REST API responses). Never print tokens or secrets.
22
23- **INTERACTIVE GATE**: If `gh` is missing, **stop**, ask whether the user wants installation guidance, **wait**—do not skip to issue listing
24- **FIRST** (after gate): Verify `gh` is available before issuing subcommands
25- **TABLES**: Prefer `--json` + markdown pipe tables for issue list summaries
26- **THREAD**: For analysis, include body and all comments (or explicitly summarize with omissions noted)
27- **014**: For user stories from issues, use `@014-agile-user-story` and align answers with GitHub-sourced text
28
29## When to use this skill
30
31- gh issue list
32- List GitHub issues
33- Issues in milestone
34- GitHub CLI issues
35- gh issue view comments
36
37## Reference
38
39For detailed guidance, examples, and constraints, see [references/021-tooling-github.md](references/021-tooling-github.md).