diff --git a/docs/README.skills.md b/docs/README.skills.md index 41ee218b81..cdb41102c9 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -216,7 +216,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [github-actions-runtime-upgrade-conventions](../skills/github-actions-runtime-upgrade-conventions/SKILL.md)
`gh skills install github/awesome-copilot github-actions-runtime-upgrade-conventions` | Upgrade GitHub Actions to supported runtimes by selecting safe action versions, preserving workflow behavior, and validating post-upgrade execution. | None | | [github-codespaces-efficiency](../skills/github-codespaces-efficiency/SKILL.md)
`gh skills install github/awesome-copilot github-codespaces-efficiency` | Audit and improve GitHub Codespaces efficiency. Use this skill when a user wants faster Codespaces startup, lower Codespaces spend, slim devcontainers, right-size machines, tune idle timeout, or scope prebuilds to branches with sustained usage. | `references/codespaces.md`
`references/review-rubric.md` | | [github-copilot-starter](../skills/github-copilot-starter/SKILL.md)
`gh skills install github/awesome-copilot github-copilot-starter` | Set up complete GitHub Copilot configuration for a new project based on technology stack | None | -| [github-issues](../skills/github-issues/SKILL.md)
`gh skills install github/awesome-copilot github-issues` | Create, update, and manage GitHub issues using MCP tools. Use this skill when users want to create bug reports, feature requests, or task issues, update existing issues, add labels/assignees/milestones, set issue fields (dates, priority, custom fields), set issue types, manage issue workflows, link issues, add dependencies, or track blocked-by/blocking relationships. Triggers on requests like "create an issue", "file a bug", "request a feature", "update issue X", "set the priority", "set the start date", "link issues", "add dependency", "blocked by", "blocking", or any GitHub issue management task. | `references/dependencies.md`
`references/images.md`
`references/issue-fields.md`
`references/issue-types.md`
`references/milestones.md`
`references/projects.md`
`references/search.md`
`references/sub-issues.md`
`references/templates.md` | +| [github-issues](../skills/github-issues/SKILL.md)
`gh skills install github/awesome-copilot github-issues` | Create, update, and manage GitHub issues using MCP tools. Use this skill when users want to create bug reports, feature requests, or task issues, update existing issues, add labels/assignees/milestones, manage repository labels, set issue fields (dates, priority, custom fields), set issue types, manage issue workflows, link issues, add dependencies, or track blocked-by/blocking relationships. Triggers on requests like "create an issue", "file a bug", "request a feature", "update issue X", "set the priority", "set the start date", "create a label", "rename a label", "list repo labels", "link issues", "add dependency", "blocked by", "blocking", or any GitHub issue management task. | `references/dependencies.md`
`references/images.md`
`references/issue-fields.md`
`references/issue-types.md`
`references/labels.md`
`references/milestones.md`
`references/projects.md`
`references/search.md`
`references/sub-issues.md`
`references/templates.md` | | [github-release](../skills/github-release/SKILL.md)
`gh skills install github/awesome-copilot github-release` | Guides IA through releasing a new version of a GitHub library end-to-end. Handles SemVer versioning and Keep a Changelog formatting automatically. | `references/commit-classification.md`
`references/semver-rules.md` | | [gitmoji](../skills/gitmoji/SKILL.md)
`gh skills install github/awesome-copilot gitmoji` | Generates commit messages following the gitmoji convention (https://gitmoji.dev) — picks the right emoji for the intent of the change and writes a well-formed message. Use when asked to "write a gitmoji commit", "add an emoji to my commit message", "which gitmoji should I use", "gitmoji this change", or when a project uses gitmoji-style commit messages. Works from a git diff, staged changes, or a plain description of the change. Generates the message only — does not run git commands. | `references/gitmoji-reference.md` | | [go-mcp-server-generator](../skills/go-mcp-server-generator/SKILL.md)
`gh skills install github/awesome-copilot go-mcp-server-generator` | Generate a complete Go MCP server project with proper structure, dependencies, and implementation using the official github.com/modelcontextprotocol/go-sdk. | None | diff --git a/skills/github-issues/SKILL.md b/skills/github-issues/SKILL.md index 438049f069..030f740557 100644 --- a/skills/github-issues/SKILL.md +++ b/skills/github-issues/SKILL.md @@ -1,6 +1,6 @@ --- name: github-issues -description: 'Create, update, and manage GitHub issues using MCP tools. Use this skill when users want to create bug reports, feature requests, or task issues, update existing issues, add labels/assignees/milestones, set issue fields (dates, priority, custom fields), set issue types, manage issue workflows, link issues, add dependencies, or track blocked-by/blocking relationships. Triggers on requests like "create an issue", "file a bug", "request a feature", "update issue X", "set the priority", "set the start date", "link issues", "add dependency", "blocked by", "blocking", or any GitHub issue management task.' +description: 'Create, update, and manage GitHub issues using MCP tools. Use this skill when users want to create bug reports, feature requests, or task issues, update existing issues, add labels/assignees/milestones, manage repository labels, set issue fields (dates, priority, custom fields), set issue types, manage issue workflows, link issues, add dependencies, or track blocked-by/blocking relationships. Triggers on requests like "create an issue", "file a bug", "request a feature", "update issue X", "set the priority", "set the start date", "create a label", "rename a label", "list repo labels", "link issues", "add dependency", "blocked by", "blocking", or any GitHub issue management task.' --- # GitHub Issues @@ -195,6 +195,7 @@ The following features require REST or GraphQL APIs beyond the basic MCP tools. | Advanced search | Complex queries with boolean logic, date ranges, cross-repo search, issue field filters (`field.name:value`) | [references/search.md](references/search.md) | | Sub-issues & parent issues | Breaking work into hierarchical tasks | [references/sub-issues.md](references/sub-issues.md) | | Milestones | Create, read, update, close, reopen, delete milestones and manage milestone issues | [references/milestones.md](references/milestones.md) | +| Labels | Discover, create, rename, recolor, and delete repository labels; add or replace labels on an issue | [references/labels.md](references/labels.md) | | Issue dependencies | Tracking blocked-by / blocking relationships | [references/dependencies.md](references/dependencies.md) | | Issue types (advanced) | GraphQL operations beyond MCP `list_issue_types` / `type` param | [references/issue-types.md](references/issue-types.md) | | Projects V2 | Project boards, progress reports, field management | [references/projects.md](references/projects.md) | diff --git a/skills/github-issues/references/labels.md b/skills/github-issues/references/labels.md new file mode 100644 index 0000000000..cb4d9747fe --- /dev/null +++ b/skills/github-issues/references/labels.md @@ -0,0 +1,157 @@ +# Labels + +Labels are repository-scoped objects with a name, a color, and an optional +description. Applying a label to an issue and creating a label are separate +operations, so list a repository's labels before using them rather than assuming +a name exists. + +The `gh label` and `gh issue` commands act on the current repository; add +`--repo {owner}/{repo}` to target another one. `gh api` has no `--repo` flag: it +fills the `{owner}` and `{repo}` placeholders from the current repository, so set +`GH_REPO={owner}/{repo}` or write the values into the path when working elsewhere. + +The GitHub MCP server's label tools require the non-default `labels` toolset and +cannot add or remove an individual label on an issue, so this reference uses the +`gh` CLI throughout. + +## List Labels + +`gh label list` returns only the first 30 labels. Always pass `--limit` when the +result decides whether a label exists, or the answer will be wrong on any +repository with a larger label set. + +```bash +gh label list --limit 1000 +``` + +Search names and descriptions, and return structured output: + +```bash +gh label list --limit 1000 --search "triage" +gh label list --limit 1000 --json name,color,description --jq '.[] | "\(.name) (#\(.color))"' +``` + +Sort by name instead of creation order: + +```bash +gh label list --limit 1000 --sort name --order asc +``` + +## Create Label + +Only the name is required. Color is six hex characters **without** a leading `#`; +a random color is assigned when it is omitted. Description must be 100 +characters or fewer. + +```bash +gh label create "needs-triage" \ + --color FBCA04 \ + --description "Awaiting maintainer review" +``` + +Creating a label that already exists fails. Use `--force` to create it or update +its color and description if it is already there, which makes seeding a label set +repeatable: + +```bash +gh label create "needs-triage" --color FBCA04 --force +``` + +## Rename or Recolor Label + +Send only what changes. `--name` sets the new name. + +```bash +gh label edit "needs-triage" --name "triage" +gh label edit "triage" --color D93F0B --description "Awaiting maintainer review" +``` + +## Delete Label + +Deleting a label removes it from every issue and pull request that carries it. +`--yes` is required when running without a prompt. Delete a label only when +explicitly requested. + +```bash +gh label delete "triage" --yes +``` + +## Copy Labels Between Repositories + +Clones the source repository's labels into the current one, skipping names that +already exist. `--force` overwrites them instead. + +```bash +gh label clone {owner}/{source-repo} +``` + +## View an Issue's Labels + +```bash +gh issue view {issue_number} --json labels --jq '.labels[].name' +``` + +## Add Labels to an Issue + +Adds to the labels already on the issue. Repeat the flag for several labels. + +```bash +gh issue edit {issue_number} --add-label "bug" --add-label "needs-triage" +``` + +## Remove Labels from an Issue + +```bash +gh issue edit {issue_number} --remove-label "needs-triage" +``` + +## Replace All Labels on an Issue + +`gh issue edit` adds and removes but cannot replace the whole set. Use the API +endpoint for that: `PUT` drops the existing labels and sets the ones supplied. + +```bash +gh api repos/{owner}/{repo}/issues/{issue_number}/labels \ + -X PUT \ + -f 'labels[]=bug' +``` + +## Remove All Labels from an Issue + +```bash +gh api repos/{owner}/{repo}/issues/{issue_number}/labels -X DELETE +``` + +## Default Labels + +GitHub creates these labels in a new repository: +`accessibility`, `bug`, `documentation`, `duplicate`, `enhancement`, +`good first issue`, `help wanted`, `invalid`, `question`, `wontfix`. + +Maintainers can rename or delete any of them, so check rather than assume. The +`isDefault` field separates them from labels the repository added: + +```bash +gh label list --limit 1000 --json name,isDefault --jq '.[] | select(.isDefault | not) | .name' +``` + +## Usage Rules + +- List the repository's labels before applying them, so the names used match the + repository's existing taxonomy. Pass `--limit` when doing so; the default of 30 + silently hides the rest. +- Create a label explicitly, with a color and description, rather than relying on + a name appearing as a side effect of labelling an issue. +- Color is six hexadecimal characters with no leading `#`. +- Description must be 100 characters or fewer. +- Use `--add-label` and `--remove-label` to change part of an issue's labels. + They leave the other labels intact. +- Replace an issue's whole label set only when replacement is explicitly + requested. Read the current labels first, and prefer add and remove otherwise: + `PUT` discards every label not named in the call. +- Label names are matched case-insensitively and stored with the case given. +- Quote label names that contain spaces. +- Pass `--yes` to `gh label delete` when running without a prompt, and ask before + deleting: the label disappears from every issue that carries it. +- Prefer issue types over labels for categorization when the organization has + issue types configured.