Awesome/awesome-copilot
1
0
Fork 0
mirror of https://github.com/github/awesome-copilot.git synced 2026-03-12 12:15:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improve github-issues skill: fix MCP tools, add search reference, fix sub-issues docs (#888)

Browse Source 
* Add advanced search reference with query syntax guide

Covers search qualifiers, boolean logic, date ranges, missing metadata
filters, common patterns, and when to use search vs list_issues.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Add issue fields search support to search and issue-fields references

- Add Advanced Search Mode section to search.md covering field: qualifier,
  has:field: syntax, REST advanced_search=true, and GraphQL ISSUE_ADVANCED
- Add Searching by Field Values section to issue-fields.md with REST/GraphQL
  examples and qualifier reference table
- Note MCP search_issues limitation (no advanced_search support)
- Update SKILL.md capability table to mention issue field filters

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Clarify three search approaches: list_issues vs search_issues vs advanced search

Replace the simple two-column comparison with a capability matrix showing
what each approach supports (field filters, boolean logic, scope, etc.)
and a decision guide for when to use each one.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix issue field search syntax: use dot notation (field.name:value)

The colon notation (field:Name:Value) is silently ignored by the API.
The correct syntax is dot notation (field.priority:P0) which works in
REST (advanced_search=true), GraphQL (ISSUE_ADVANCED), and web UI.

Also supports has:field.name, no:field.name, and date comparisons.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix github-issues skill: correct MCP tools and add gh api workflows

The skill listed 5 MCP tools that don't exist (create_issue, update_issue,
get_issue, add_issue_comment, list_issue_types), causing tool-not-found
errors when agents tried to follow the skill instructions.

Changes:
- Split tools table into MCP (read ops) and CLI/API (write ops)
- Add gh api commands for creating, updating, commenting on issues
- Document that gh issue create doesn't support --type flag
- Add GraphQL query for discovering issue types
- Remove redundant [Bug]/[Feature] title prefixes (use type param instead)
- Update examples to use gh api instead of non-existent MCP tools

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix sub-issues reference: add gh api examples and integer gotcha

The sub_issue_id parameter requires an integer but gh api -f sends strings,
causing 422 errors. Updated all REST examples to use --input with raw JSON.

Also added:
- Recommended two-step workflow (create issue, then link)
- Explicit warning about -f vs --input for integer params
- Proper gh api command syntax instead of raw HTTP notation

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Address PR review: fix search docs accuracy and broken link

- Fix misleading claim about full boolean logic support (implicit AND only)
- Remove sort:updated from query example (it's an API param, not a qualifier)
- Clarify -linked:pr comment to avoid confusion with authoring status
- Fix relative link in issue-fields.md (sibling file, not nested path)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Improve projects reference: scope warning, gh api examples, issue-side queries

From hands-on usage: hit INSUFFICIENT_SCOPES trying to update project
status because token had read:project but not project write scope.

Added:
- OAuth scope requirements table with gh auth refresh workaround
- How to find an issue's project item ID (query from issue side)
- All GraphQL examples now use gh api graphql (copy-paste ready)
- End-to-end example: set issue status to In Progress

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Add images-in-issues reference: hosting methods, pitfalls, screenshots

Documents three approaches for embedding images in issue comments
via CLI: Contents API with github.com/raw/ URLs, browser drag-drop
for permanent user-attachments URLs, and gist hosting limitations.

Includes puppeteer screenshot recipe and comparison table.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Update README.skills.md with images reference

Run npm run build to regenerate skill listing.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix issue-fields search: add GraphQL bulk query, caveat search syntax

The field.name:value search qualifier is unreliable via API (returns
0 results even when matching issues exist). Added a recommended
GraphQL approach that fetches issues and filters by issueFieldValues
client-side. Documented the correct IssueFieldSingleSelectValue
schema (name, not value). Marked search qualifier syntax as
experimental with a reliability warning.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* docs(github-issues): improve project discovery guidance

The projectsV2 query param does keyword search, not exact match,
and sorts by recency. For large orgs like github, common words like
'issue' return 400+ results and bury the target project.

Added a priority-ordered discovery strategy:
1. Direct lookup by number (instant)
2. Reverse lookup from a known issue's projectItems (most reliable)
3. GraphQL name search with client-side jq filtering (fallback)
4. MCP tool (small orgs only)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Tadas Labudis
2026-03-06 10:20:36 +00:00
committed by GitHub
parent 1b15663c46
commit fca5de1f6a
7 changed files with 721 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files

144
skills/github-issues/SKILL.md
View File

@@ -7,63 +7,81 @@ description: 'Create, update, and manage GitHub issues using MCP tools. Use this
Manage GitHub issues using the `@modelcontextprotocol/server-github` MCP server.
## Available MCP Tools
## Available Tools
### MCP Tools (read operations)
| Tool | Purpose |
|------|---------|
| `mcp__github__create_issue` | Create new issues |
| `mcp__github__update_issue` | Update existing issues |
| `mcp__github__get_issue` | Fetch issue details |
| `mcp__github__search_issues` | Search issues |
| `mcp__github__add_issue_comment` | Add comments |
| `mcp__github__list_issues` | List repository issues |
| `mcp__github__list_issue_types` | List available issue types for an organization |
| `mcp__github__issue_read` | Read issue details, sub-issues, comments, labels |
| `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__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)
The MCP server does not currently support creating, updating, or commenting on issues. Use `gh api` for these operations.
| Operation | Command |
|-----------|---------|
| Create issue | `gh api repos/{owner}/{repo}/issues -X POST -f title=... -f body=...` |
| Update issue | `gh api repos/{owner}/{repo}/issues/{number} -X PATCH -f title=... -f state=...` |
| Add comment | `gh api repos/{owner}/{repo}/issues/{number}/comments -X POST -f body=...` |
| Close issue | `gh api repos/{owner}/{repo}/issues/{number} -X PATCH -f state=closed` |
| Set issue type | Include `-f type=Bug` in the create call (REST API only, not supported by `gh issue create` CLI) |
**Note:** `gh issue create` works for basic issue creation but does **not** support the `--type` flag. Use `gh api` when you need to set issue types.
## Workflow
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**: Call the appropriate MCP tool
4. **Execute**: Use MCP tools for reads, `gh api` for writes
5. **Confirm**: Report the issue URL to user
## Creating Issues
### Required Parameters
Use `gh api` to create issues. This supports all parameters including issue types.
```
owner: repository owner (org or user)
repo: repository name
title: clear, actionable title
body: structured markdown content
```bash
gh api repos/{owner}/{repo}/issues \
-X POST \
-f title="Issue title" \
-f body="Issue body in markdown" \
-f type="Bug" \
--jq '{number, html_url}'
```
### Optional Parameters
Add any of these flags to the `gh api` call:
```
labels: ["bug", "enhancement", "documentation", ...]
assignees: ["username1", "username2"]
milestone: milestone number (integer)
type: issue type name (e.g., "Bug", "Feature", "Task", "Epic")
-f type="Bug" # Issue type (Bug, Feature, Task, Epic, etc.)
-f labels[]="bug" # Labels (repeat for multiple)
-f assignees[]="username" # Assignees (repeat for multiple)
-f milestone=1 # Milestone number
```
**Issue types** are organization-level metadata. Before using `type`, call `mcp__github__list_issue_types` with the org name to discover available types. If the org has no issue types configured, omit the parameter.
**Issue types** are organization-level metadata. To discover available types, use:
```bash
gh api graphql -f query='{ organization(login: "ORG") { issueTypes(first: 10) { nodes { name } } } }' --jq '.data.organization.issueTypes.nodes[].name'
```
**Prefer issue types over labels for categorization.** When issue types are available (e.g., Bug, Feature, Task), use the `type` parameter instead of applying equivalent labels like `bug` or `enhancement`. Issue types are the canonical way to categorize issues on GitHub. Only fall back to labels when the org has no issue types configured.
### Title Guidelines
- Start with type prefix when useful: `[Bug]`, `[Feature]`, `[Docs]`
- Be specific and actionable
- Keep under 72 characters
- When issue types are set, don't add redundant prefixes like `[Bug]`
- Examples:
- `[Bug] Login fails with SSO enabled`
- `[Feature] Add dark mode support`
- `Add unit tests for auth module`
- `Login fails with SSO enabled` (with type=Bug)
- `Add dark mode support` (with type=Feature)
- `Add unit tests for auth module` (with type=Task)
### Body Structure
@@ -77,14 +95,17 @@ Always use the templates in [references/templates.md](references/templates.md).
## Updating Issues
Use `mcp__github__update_issue` with:
Use `gh api` with PATCH:
```
owner, repo, issue_number (required)
title, body, state, labels, assignees, milestone (optional - only changed fields)
```bash
gh api repos/{owner}/{repo}/issues/{number} \
-X PATCH \
-f state=closed \
-f title="Updated title" \
--jq '{number, html_url}'
```
State values: `open`, `closed`
Only include fields you want to change. Available fields: `title`, `body`, `state` (open/closed), `labels`, `assignees`, `milestone`.
## Examples
@@ -92,31 +113,54 @@ State values: `open`, `closed`
**User**: "Create a bug issue - the login page crashes when using SSO"
**Action**: Call `mcp__github__create_issue` with:
```json
{
"owner": "github",
"repo": "awesome-copilot",
"title": "[Bug] Login page crashes when using SSO",
"body": "## Description\nThe login page crashes when users attempt to authenticate using SSO.\n\n## Steps to Reproduce\n1. Navigate to login page\n2. Click 'Sign in with SSO'\n3. Page crashes\n\n## Expected Behavior\nSSO authentication should complete and redirect to dashboard.\n\n## Actual Behavior\nPage becomes unresponsive and displays error.\n\n## Environment\n- Browser: [To be filled]\n- OS: [To be filled]\n\n## Additional Context\nReported by user.",
"type": "Bug"
}
**Action**:
```bash
gh api repos/github/awesome-copilot/issues \
-X POST \
-f title="Login page crashes when using SSO" \
-f type="Bug" \
-f body="## Description
The login page crashes when users attempt to authenticate using SSO.
## Steps to Reproduce
1. Navigate to login page
2. Click 'Sign in with SSO'
3. Page crashes
## Expected Behavior
SSO authentication should complete and redirect to dashboard.
## Actual Behavior
Page becomes unresponsive and displays error." \
--jq '{number, html_url}'
```
### Example 2: Feature Request
**User**: "Create a feature request for dark mode with high priority"
**Action**: Call `mcp__github__create_issue` with:
```json
{
"owner": "github",
"repo": "awesome-copilot",
"title": "[Feature] Add dark mode support",
"body": "## Summary\nAdd dark mode theme option for improved user experience and accessibility.\n\n## Motivation\n- Reduces eye strain in low-light environments\n- Increasingly expected by users\n- Improves accessibility\n\n## Proposed Solution\nImplement theme toggle with system preference detection.\n\n## Acceptance Criteria\n- [ ] Toggle switch in settings\n- [ ] Persists user preference\n- [ ] Respects system preference by default\n- [ ] All UI components support both themes\n\n## Alternatives Considered\nNone specified.\n\n## Additional Context\nHigh priority request.",
"type": "Feature",
"labels": ["high-priority"]
}
**Action**:
```bash
gh api repos/github/awesome-copilot/issues \
-X POST \
-f title="Add dark mode support" \
-f type="Feature" \
-f labels[]="high-priority" \
-f body="## Summary
Add dark mode theme option for improved user experience and accessibility.
## Motivation
- Reduces eye strain in low-light environments
- Increasingly expected by users
## Proposed Solution
Implement theme toggle with system preference detection.
## Acceptance Criteria
- [ ] Toggle switch in settings
- [ ] Persists user preference
- [ ] Respects system preference by default" \
--jq '{number, html_url}'
```
## Common Labels
@@ -148,8 +192,10 @@ The following features require REST or GraphQL APIs beyond the basic MCP tools.
| Capability | When to use | Reference |
|------------|-------------|-----------|
| 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) |
| 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) |
| Issue fields | Custom metadata: dates, priority, text, numbers (private preview) | [references/issue-fields.md](references/issue-fields.md) |
| Images in issues | Embedding images in issue bodies and comments via CLI | [references/images.md](references/images.md) |