Add gh discussion and Issues 2.0 reference to the gh skill, plus a README note (cli#13631)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Babak K. Shandiz <babakks@github.com>

Author: 4 people

README.md

@@ -10,6 +10,18 @@ GitHub CLI is supported for users on GitHub.com, GitHub Enterprise Cloud, and Gi
 
 For [installation options see below](#installation), for usage instructions [see the manual](https://cli.github.com/manual/).
 
+## Agent skills
+
+An [agent skill](https://agentskills.io) is available for driving `gh` from coding agents. Install or update it with the built-in `gh skill` command:
+
+```shell
+# Install the skill (user scope recommended)
+gh skill install cli/cli gh --scope user
+
+# Update the skill after a `gh` release
+gh skill update gh
+```
+
 ## Contributing
 
 If anything feels off or if you feel that some functionality is missing, please check out the [contributing page](.github/CONTRIBUTING.md). There you will find instructions for sharing your feedback, building the tool locally, and submitting pull requests to the project.

skills/gh/SKILL.md

@@ -55,6 +55,60 @@ Pass `--repo OWNER/REPO` (`-R`) to override the resolved CWD repo.
 - `gh issue list --search "..."` and `gh pr list --search "..."` accept
   the same syntax but are scoped to one repo.
 
+## Issue types, sub-issues, and relationships
+
+Newer `gh issue` subcommands model issue types, sub-issue hierarchy, and
+blocked-by/blocking relationships.
+
+- `gh issue create`: `--type <name>`, `--parent <number|url>` (creates the
+  new issue as a sub-issue), `--blocked-by <number|url,...>`, `--blocking <number|url,...>`.
+- `gh issue edit` (edits one or more issues in the same repo, e.g.
+  `gh issue edit 23 34`): `--type <name>` / `--remove-type`,
+  `--parent <n|url>` / `--remove-parent`,
+  `--add-sub-issue <n,n>` / `--remove-sub-issue <n,n>`,
+  `--add-blocked-by <n,n>` / `--remove-blocked-by <n,n>`,
+  `--add-blocking <n,n>` / `--remove-blocking <n,n>`. Relationship and parent
+  refs are issue numbers or URLs; a URL may point to another repo on the same
+  host, but a different host is rejected. `--add-sub-issue` cannot be used
+  when editing more than one issue.
+- `gh issue list --type <name>` filters by issue type.
+- `gh issue view` and `gh issue list` accept these as `--json` fields (prefer
+  them over scraping the default text output): `issueType`, `parent`,
+  `subIssues`, `subIssuesSummary`, `blockedBy`, `blocking`. `subIssues`,
+  `blockedBy`, and `blocking` are objects shaped
+  `{"nodes": [...], "totalCount": N}` (not flat arrays), and `nodes` is capped
+  (`subIssues` at 100, `blockedBy`/`blocking` at 50), so compare the node count
+  against `totalCount` to detect truncation.
+- GHES: issue types and sub-issues need 3.17+; blocked-by/blocking
+  relationships need 3.19+.
+
+## Discussions (`gh discussion`)
+
+Preview command set, subject to change. Subcommands:
+
+- `gh discussion list [--state open|closed|all] [--category <name>] [--author <handle>] [--label <name>,...] [--answered] [--search <query>] [--sort created|updated] [--order asc|desc] [--limit N] [--after <cursor>] [--json <fields>] [--web]`
+  lists a repo's discussions. `--state` defaults to open, `--sort` to updated,
+  `--order` to desc. `--answered` is tri-state (`--answered=false` for
+  unanswered) for Q&A categories.
+- `gh discussion view {<number>|<url>|<comment-id>|<comment-url>} [--comments] [--order oldest|newest] [--limit N] [--after <cursor>] [--json <fields>] [--web]`
+  shows a discussion's body; add `--comments` for its comments, or pass a
+  comment ID/URL as the argument to list that comment's replies (no
+  `--replies` flag; `--comments` is rejected with a comment argument).
+  `--order` (default newest), `--limit`, and `--after` apply only to comment
+  and reply listings.
+- `gh discussion create [--title <t>] [--body <b> | --body-file <path>] [--category <name>] [--label <name>,...]`
+  creates a discussion. `--title`, a body (`--body` or `--body-file`), and
+  `--category` are required non-interactively; omitting any will prompt on a
+  terminal.
+- `gh discussion edit {<number>|<url>} [--title <t>] [--body <b>] [--body-file <path>] [--category <name>] [--add-label <name>,...] [--remove-label <name>,...]`
+  edits title, body, category, or labels.
+- `gh discussion comment {<number>|<discussion-url>|<comment-id>|<comment-url>} [--body <b>] [--body-file <path>] [--edit] [--delete] [--yes]`
+  adds a top-level comment (when given a discussion) or a reply (when given a
+  comment); `--edit` or `--delete` updates or removes a comment/reply and
+  needs a comment ID or URL. `--yes` skips the `--delete` confirmation.
+- `--json`/`--jq`/`--template` are available on `list` and `view` only;
+  `create` and `edit` print the discussion URL. `comment` prints the discussion comment (or reply) URL.
+
 ## Fall back to `gh api` for anything `--json` doesn't expose
 
 Sometimes useful data isn't on the typed commands. Examples: