Awesome/awesome-copilot
1
0
Fork 0
mirror of https://github.com/github/awesome-copilot.git synced 2026-06-23 07:57:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update github-issues skill to prefer MCP for issue fields

Browse Source 
Add MCP tools (list_issue_fields, set_issue_fields, issue_write with
issue_fields param, list_issues with field_filters) as the preferred
approach for managing issue fields. REST and GraphQL APIs remain as
fallback when MCP is unavailable.

Key changes:
- SKILL.md: Add new MCP tools to Available Tools table, update workflow
- references/issue-fields.md: Restructure to lead with MCP, demote REST
  to fallback section, add examples for all MCP tool variants

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Tadas Labudis
2026-06-19 12:09:12 +01:00
parent 251f416b6d
commit dfecafec8c
2 changed files with 126 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/github-issues/SKILL.md
+10 -7
View File
@@ -9,20 +9,23 @@ Manage GitHub issues using the `@modelcontextprotocol/server-github` MCP server.
## Available Tools
### MCP Tools (read operations)
### MCP Tools (preferred)
| Tool | Purpose |
|------|---------|
| `mcp__github__issue_read` | Read issue details, sub-issues, comments, labels (methods: get, get_comments, get_sub_issues, get_labels) |
| `mcp__github__list_issues` | List and filter repository issues by state, labels, date |
| `mcp__github__issue_read` | Read issue details (including field values), sub-issues, comments, labels |
| `mcp__github__issue_write` | Create or update issues, set fields, labels, assignees, type, state |
| `mcp__github__list_issues` | List and filter issues by state, labels, date, and field values |
| `mcp__github__list_issue_fields` | Discover available issue fields and their options for a repo/org |
| `mcp__github__set_issue_fields` | Set issue field values with confidence scoring and rationale |
| `mcp__github__search_issues` | Search issues across repos using GitHub search syntax |
| `mcp__github__projects_list` | List projects, project fields, project items, status updates |
| `mcp__github__projects_get` | Get details of a project, field, item, or status update |
| `mcp__github__projects_write` | Add/update/delete project items, create status updates |
### CLI / REST API (write operations)
### CLI / REST API (fallback)
The MCP server does not currently support creating, updating, or commenting on issues. Use `gh api` for these operations.
Use `gh api` when MCP tools are not available or for operations not yet supported by MCP (e.g., adding comments).
| Operation | Command |
|-----------|---------|
@@ -39,12 +42,12 @@ The MCP server does not currently support creating, updating, or commenting on i
1. **Determine action**: Create, update, or query?
2. **Gather context**: Get repo info, existing labels, milestones if needed
3. **Structure content**: Use appropriate template from [references/templates.md](references/templates.md)
4. **Execute**: Use MCP tools for reads, `gh api` for writes
4. **Execute**: Prefer MCP tools (`issue_write`, `set_issue_fields`); fall back to `gh api` if MCP is unavailable
5. **Confirm**: Report the issue URL to user
## Creating Issues
Use `gh api` to create issues. This supports all parameters including issue types.
**Prefer MCP** when the `issue_write` tool is available. It supports title, body, type, labels, assignees, milestone, and issue fields in one call. Fall back to `gh api` if MCP is not available.
```bash
gh api repos/{owner}/{repo}/issues \
skills/github-issues/references/issue-fields.md
+116 -2
View File
@@ -4,9 +4,123 @@ Issue fields are custom metadata (dates, text, numbers, single-select) defined a
**Prefer issue fields over project fields.** When you need to set metadata like dates, priority, or status on an issue, use issue fields (which live on the issue itself) rather than project fields (which live on a project item). Issue fields travel with the issue across projects and views, while project fields are scoped to a single project. Only use project fields when issue fields are not available or when the field is project-specific (e.g., sprint iterations).
## REST API (recommended)
## MCP Tools (preferred)
The REST API is the simplest way to discover fields and set values.
When the GitHub MCP server is available, use MCP tools for all issue field operations. They handle ID resolution internally, so you work with human-readable names.
### Discovering available fields
Use `list_issue_fields` to get field definitions and valid options:
```
Tool: mcp__github__list_issue_fields
Parameters:
owner: "ORG"
repo: "REPO" # optional; omit for org-level fields
```
Returns field names, types (text, number, date, single_select), and for single-select fields, the list of valid option names.
### Reading field values on an issue
Use `issue_read` with method `get`. Field values are included in the response.
```
Tool: mcp__github__issue_read
Parameters:
method: "get"
owner: "OWNER"
repo: "REPO"
issue_number: 123
```
### Setting fields via issue_write (simplest)
When creating or updating an issue, pass `issue_fields` inline. Uses field names and option names directly (no ID lookups needed):
```
Tool: mcp__github__issue_write
Parameters:
method: "update"
owner: "OWNER"
repo: "REPO"
issue_number: 123
show_ui: false
issue_fields:
- field_name: "Priority"
field_option_name: "P1"
- field_name: "Target Date"
value: "2026-07-01"
- field_name: "Effort"
value: 5
```
Each entry takes `field_name` (case-insensitive) plus one of:
- `field_option_name` - for single-select fields (validated against options)
- `value` - for text, number, or date fields (date as YYYY-MM-DD)
- `delete: true` - to clear the field value
### Setting fields via set_issue_fields (advanced)
Use the dedicated `set_issue_fields` tool when you need confidence scoring, rationale, or suggestion mode. Requires GraphQL node IDs (get them from `list_issue_fields` response):
```
Tool: mcp__github__set_issue_fields
Parameters:
owner: "OWNER"
repo: "REPO"
issue_number: 123
fields:
- field_id: "IFD_abc123"
date_value: "2026-07-01"
confidence: "HIGH"
rationale: "Deadline stated in issue description"
- field_id: "IFSS_def456"
single_select_option_id: "OPT_xyz789"
confidence: "MEDIUM"
rationale: "Reports a crash when saving, likely high priority"
is_suggestion: true
```
Each entry takes `field_id` plus one value parameter:
| Field type | Value parameter | Format |
|-----------|----------------|--------|
| Date | `date_value` | ISO 8601 date string |
| Text | `text_value` | String |
| Number | `number_value` | Number |
| Single select | `single_select_option_id` | GraphQL node ID of the option |
Additional parameters per field:
- `confidence` (LOW/MEDIUM/HIGH) - how certain you are of this value
- `rationale` (max 280 chars) - one sentence explaining what led to this choice
- `is_suggestion` (boolean) - if true, sent as a suggestion rather than applied value
- `delete` (boolean) - set true to clear the field value
### Filtering issues by field values
Use `list_issues` with `field_filters` to find issues matching specific field values:
```
Tool: mcp__github__list_issues
Parameters:
owner: "OWNER"
repo: "REPO"
state: "OPEN"
field_filters:
- field_name: "Priority"
value: "P1"
```
### Workflow (MCP)
1. **Discover fields** - `list_issue_fields` to see available fields and options
2. **Set values** - use `issue_write` with `issue_fields` for simple cases, or `set_issue_fields` for confidence/rationale
3. **Query by fields** - use `list_issues` with `field_filters`
## REST API (fallback)
Use the REST API when MCP tools are not available.
### Discovering available fields