Skip to content

Commit b385756

Browse files
andykenwardandykenward
committed
docs: skills github-issues
1 parent a5bd26f commit b385756

10 files changed

Lines changed: 1574 additions & 0 deletions

File tree

‎.agents/skills/github-issues/SKILL.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
---
2+
name: github-issues
3+
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.'
4+
---
5+
6+
# GitHub Issues
7+
8+
Manage GitHub issues using the `@modelcontextprotocol/server-github` MCP server.
9+
10+
## Available Tools
11+
12+
### MCP Tools (read operations)
13+
14+
| Tool | Purpose |
15+
| ----------------------------- | --------------------------------------------------------------------------------------------------------- |
16+
| `mcp__github__issue_read` | Read issue details, sub-issues, comments, labels (methods: get, get_comments, get_sub_issues, get_labels) |
17+
| `mcp__github__list_issues` | List and filter repository issues by state, labels, date |
18+
| `mcp__github__search_issues` | Search issues across repos using GitHub search syntax |
19+
| `mcp__github__projects_list` | List projects, project fields, project items, status updates |
20+
| `mcp__github__projects_get` | Get details of a project, field, item, or status update |
21+
| `mcp__github__projects_write` | Add/update/delete project items, create status updates |
22+
23+
### CLI / REST API (write operations)
24+
25+
The MCP server does not currently support creating, updating, or commenting on issues. Use `gh api` for these operations.
26+
27+
| Operation | Command |
28+
| -------------- | ------------------------------------------------------------------------------------------------ |
29+
| Create issue | `gh api repos/{owner}/{repo}/issues -X POST -f title=... -f body=...` |
30+
| Update issue | `gh api repos/{owner}/{repo}/issues/{number} -X PATCH -f title=... -f state=...` |
31+
| Add comment | `gh api repos/{owner}/{repo}/issues/{number}/comments -X POST -f body=...` |
32+
| Close issue | `gh api repos/{owner}/{repo}/issues/{number} -X PATCH -f state=closed` |
33+
| Set issue type | Include `-f type=Bug` in the create call (REST API only, not supported by `gh issue create` CLI) |
34+
35+
**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.
36+
37+
## Workflow
38+
39+
1. **Determine action**: Create, update, or query?
40+
2. **Gather context**: Get repo info, existing labels, milestones if needed
41+
3. **Structure content**: Use appropriate template from [references/templates.md](references/templates.md)
42+
4. **Execute**: Use MCP tools for reads, `gh api` for writes
43+
5. **Confirm**: Report the issue URL to user
44+
45+
## Creating Issues
46+
47+
Use `gh api` to create issues. This supports all parameters including issue types.
48+
49+
```bash
50+
gh api repos/{owner}/{repo}/issues \
51+
-X POST \
52+
-f title="Issue title" \
53+
-f body="Issue body in markdown" \
54+
-f type="Bug" \
55+
--jq '{number, html_url}'
56+
```
57+
58+
### Optional Parameters
59+
60+
Add any of these flags to the `gh api` call:
61+
62+
```
63+
-f type="Bug" # Issue type (Bug, Feature, Task, Epic, etc.)
64+
-f labels[]="bug" # Labels (repeat for multiple)
65+
-f assignees[]="username" # Assignees (repeat for multiple)
66+
-f milestone=1 # Milestone number
67+
```
68+
69+
**Issue types** are organization-level metadata. To discover available types, use:
70+
71+
```bash
72+
gh api graphql -f query='{ organization(login: "ORG") { issueTypes(first: 10) { nodes { name } } } }' --jq '.data.organization.issueTypes.nodes[].name'
73+
```
74+
75+
**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.
76+
77+
### Title Guidelines
78+
79+
- Be specific and actionable
80+
- Keep under 72 characters
81+
- When issue types are set, don't add redundant prefixes like `[Bug]`
82+
- Examples:
83+
- `Login fails with SSO enabled` (with type=Bug)
84+
- `Add dark mode support` (with type=Feature)
85+
- `Add unit tests for auth module` (with type=Task)
86+
87+
### Body Structure
88+
89+
Always use the templates in [references/templates.md](references/templates.md). Choose based on issue type:
90+
91+
| User Request | Template |
92+
| ------------------------------- | --------------- |
93+
| Bug, error, broken, not working | Bug Report |
94+
| Feature, enhancement, add, new | Feature Request |
95+
| Task, chore, refactor, update | Task |
96+
97+
## Updating Issues
98+
99+
Use `gh api` with PATCH:
100+
101+
```bash
102+
gh api repos/{owner}/{repo}/issues/{number} \
103+
-X PATCH \
104+
-f state=closed \
105+
-f title="Updated title" \
106+
--jq '{number, html_url}'
107+
```
108+
109+
Only include fields you want to change. Available fields: `title`, `body`, `state` (open/closed), `labels`, `assignees`, `milestone`.
110+
111+
## Examples
112+
113+
### Example 1: Bug Report
114+
115+
**User**: "Create a bug issue - the login page crashes when using SSO"
116+
117+
**Action**:
118+
119+
```bash
120+
gh api repos/github/awesome-copilot/issues \
121+
-X POST \
122+
-f title="Login page crashes when using SSO" \
123+
-f type="Bug" \
124+
-f body="## Description
125+
The login page crashes when users attempt to authenticate using SSO.
126+
127+
## Steps to Reproduce
128+
1. Navigate to login page
129+
2. Click 'Sign in with SSO'
130+
3. Page crashes
131+
132+
## Expected Behavior
133+
SSO authentication should complete and redirect to dashboard.
134+
135+
## Actual Behavior
136+
Page becomes unresponsive and displays error." \
137+
--jq '{number, html_url}'
138+
```
139+
140+
### Example 2: Feature Request
141+
142+
**User**: "Create a feature request for dark mode with high priority"
143+
144+
**Action**:
145+
146+
```bash
147+
gh api repos/github/awesome-copilot/issues \
148+
-X POST \
149+
-f title="Add dark mode support" \
150+
-f type="Feature" \
151+
-f labels[]="high-priority" \
152+
-f body="## Summary
153+
Add dark mode theme option for improved user experience and accessibility.
154+
155+
## Motivation
156+
- Reduces eye strain in low-light environments
157+
- Increasingly expected by users
158+
159+
## Proposed Solution
160+
Implement theme toggle with system preference detection.
161+
162+
## Acceptance Criteria
163+
- [ ] Toggle switch in settings
164+
- [ ] Persists user preference
165+
- [ ] Respects system preference by default" \
166+
--jq '{number, html_url}'
167+
```
168+
169+
## Common Labels
170+
171+
Use these standard labels when applicable:
172+
173+
| Label | Use For |
174+
| ------------------ | ----------------------------- |
175+
| `bug` | Something isn't working |
176+
| `enhancement` | New feature or improvement |
177+
| `documentation` | Documentation updates |
178+
| `good first issue` | Good for newcomers |
179+
| `help wanted` | Extra attention needed |
180+
| `question` | Further information requested |
181+
| `wontfix` | Will not be addressed |
182+
| `duplicate` | Already exists |
183+
| `high-priority` | Urgent issues |
184+
185+
## Tips
186+
187+
- Always confirm the repository context before creating issues
188+
- Ask for missing critical information rather than guessing
189+
- Link related issues when known: `Related to #123`
190+
- For updates, fetch current issue first to preserve unchanged fields
191+
192+
## Extended Capabilities
193+
194+
The following features require REST or GraphQL APIs beyond the basic MCP tools. Each is documented in its own reference file so the agent only loads the knowledge it needs.
195+
196+
| Capability | When to use | Reference |
197+
| -------------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- |
198+
| Advanced search | Complex queries with boolean logic, date ranges, cross-repo search, issue field filters (`field.name:value`) | [references/search.md](references/search.md) |
199+
| Sub-issues & parent issues | Breaking work into hierarchical tasks | [references/sub-issues.md](references/sub-issues.md) |
200+
| Issue dependencies | Tracking blocked-by / blocking relationships | [references/dependencies.md](references/dependencies.md) |
201+
| Issue types (advanced) | GraphQL operations beyond MCP `list_issue_types` / `type` param | [references/issue-types.md](references/issue-types.md) |
202+
| Projects V2 | Project boards, progress reports, field management | [references/projects.md](references/projects.md) |
203+
| Issue fields | Custom metadata: dates, priority, text, numbers (private preview) | [references/issue-fields.md](references/issue-fields.md) |
204+
| Images in issues | Embedding images in issue bodies and comments via CLI | [references/images.md](references/images.md) |

‎.agents/skills/github-issues/references/dependencies.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Issue Dependencies (Blocked By / Blocking)
2+
3+
Dependencies let you mark that an issue is blocked by another issue. This creates a formal dependency relationship visible in the UI and trackable via API. No MCP tools exist for dependencies; use REST or GraphQL directly.
4+
5+
## Using REST API
6+
7+
**List issues blocking this issue:**
8+
9+
```
10+
GET /repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocked_by
11+
```
12+
13+
**Add a blocking dependency:**
14+
15+
```
16+
POST /repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocked_by
17+
Body: { "issue_id": 12345 }
18+
```
19+
20+
The `issue_id` is the numeric issue **ID** (not the issue number).
21+
22+
**Remove a blocking dependency:**
23+
24+
```
25+
DELETE /repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocked_by/{issue_id}
26+
```
27+
28+
## Using GraphQL
29+
30+
**Read dependencies:**
31+
32+
```graphql
33+
{
34+
repository(owner: "OWNER", name: "REPO") {
35+
issue(number: 123) {
36+
blockedBy(first: 10) {
37+
nodes {
38+
number
39+
title
40+
state
41+
}
42+
}
43+
blocking(first: 10) {
44+
nodes {
45+
number
46+
title
47+
state
48+
}
49+
}
50+
issueDependenciesSummary {
51+
blockedBy
52+
blocking
53+
totalBlockedBy
54+
totalBlocking
55+
}
56+
}
57+
}
58+
}
59+
```
60+
61+
**Add a dependency:**
62+
63+
```graphql
64+
mutation {
65+
addBlockedBy(
66+
input: {
67+
issueId: "BLOCKED_ISSUE_NODE_ID"
68+
blockingIssueId: "BLOCKING_ISSUE_NODE_ID"
69+
}
70+
) {
71+
blockingIssue {
72+
number
73+
title
74+
}
75+
}
76+
}
77+
```
78+
79+
**Remove a dependency:**
80+
81+
```graphql
82+
mutation {
83+
removeBlockedBy(
84+
input: {
85+
issueId: "BLOCKED_ISSUE_NODE_ID"
86+
blockingIssueId: "BLOCKING_ISSUE_NODE_ID"
87+
}
88+
) {
89+
blockingIssue {
90+
number
91+
title
92+
}
93+
}
94+
}
95+
```
96+
97+
## Tracked issues (read-only)
98+
99+
Task-list tracking relationships are available via GraphQL as read-only fields:
100+
101+
- `trackedIssues(first: N)` - issues tracked in this issue's task list
102+
- `trackedInIssues(first: N)` - issues whose task lists reference this issue
103+
104+
These are set automatically when issues are referenced in task lists (`- [ ] #123`). There are no mutations to manage them.

0 commit comments

Comments
 (0)