The REST API for issue field values is simpler and avoids common
pitfalls with the GraphQL approach (needing special headers, node IDs,
option IDs vs names). Key changes:
- Add REST API section as the recommended approach
- Document correct payload format (issue_field_values array wrapper)
- Document that value takes the option NAME not ID for single-select
- List common mistakes (wrong key format, missing wrapper, -f vs --input)
- Move GraphQL to an alternative section (still documented)
- Remove outdated private preview notice (now in public preview)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Add dependency/blocking trigger phrases to skill description so the
skill activates on requests like 'link issues', 'add dependency',
'blocked by', and 'blocking'
- Fix incorrect GraphQL return field in dependencies.md: blockedByIssue
does not exist on AddBlockedByPayload; the correct field is
blockingIssue
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* 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>
* Add issue fields, issue types, and list_issue_types to github-issues skill
- Add list_issue_types to available MCP tools table
- Add type parameter to optional parameters with guidance
- Expand issue types section: MCP tools (preferred) + GraphQL (advanced)
- Document org-level type discovery, create/update with type, GraphQL mutations
- Add issue fields section: discover, read, set via GraphQL
- Note required GraphQL-Features headers (issue_fields, issue_types)
- Update skill description to mention fields, types, dates, priority
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Add Projects V2 guidance to github-issues skill
Include MCP tools (projects_list, projects_get, projects_write) and
GraphQL examples for project item management.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Add sub-issues section, move issue fields to end with preview note
- Add Sub-Issues and Parent Issues section (MCP, REST, GraphQL)
- Add issue_read tool to MCP tools table
- Move Issue Fields to last section with private preview callout
- Link to community discussion for requesting access
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Prefer issue types over labels for categorization
Update guidance and examples to use type parameter (Bug, Feature)
instead of equivalent labels when issue types are available.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Prefer issue fields over project fields for metadata
Issue fields live on the issue and travel across projects.
Project fields are scoped to a single project.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Add issue dependencies (blocked by/blocking) section
Covers REST endpoints (list, add, remove) and GraphQL
(blockedBy, blocking, issueDependenciesSummary, mutations).
Also documents tracked issues read-only fields.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Add project discovery workflow for progress reports
Teach agents how to find projects by name, discover fields
and iterations, paginate items, and build status breakdowns.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Generate updated skill listing after SKILL.md changes
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Split skill into reference files per reviewer feedback
Move sub-issues, dependencies, issue types, projects, and issue fields
into separate references/ files. Main SKILL.md now contains core MCP
workflow and a capability table pointing to each reference. This way
the agent only loads the knowledge it needs for the specific task.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Tadas Labudis
Tadas Labudis
Tugdual Grall