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

* 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>

skills/github-issues/references/sub-issues.md

@@ -2,46 +2,64 @@
 
 Sub-issues let you break down work into hierarchical tasks. Each parent issue can have up to 100 sub-issues, nested up to 8 levels deep. Sub-issues can span repositories within the same owner.
 
+## Recommended Workflow
+
+The simplest way to create a sub-issue is **two steps**: create the issue, then link it.
+
+```bash
+# Step 1: Create the issue and capture its numeric ID
+ISSUE_ID=$(gh api repos/{owner}/{repo}/issues \
+  -X POST \
+  -f title="Sub-task title" \
+  -f body="Description" \
+  --jq '.id')
+
+# Step 2: Link it as a sub-issue of the parent
+# IMPORTANT: sub_issue_id must be an integer. Use --input (not -f) to send JSON.
+echo "{\"sub_issue_id\": $ISSUE_ID}" | gh api repos/{owner}/{repo}/issues/{parent_number}/sub_issues -X POST --input -
+```
+
+**Why `--input` instead of `-f`?** The `gh api -f` flag sends all values as strings, but the API requires `sub_issue_id` as an integer. Using `-f sub_issue_id=12345` will return a 422 error.
+
+Alternatively, use GraphQL `createIssue` with `parentIssueId` to do it in one step (see GraphQL section below).
+
 ## Using MCP tools
 
 **List sub-issues:**
 Call `mcp__github__issue_read` with `method: "get_sub_issues"`, `owner`, `repo`, and `issue_number`.
 
 **Create an issue as a sub-issue:**
-There is no MCP tool for creating sub-issues directly. Use REST or GraphQL (see below).
+There is no MCP tool for creating sub-issues directly. Use the workflow above or GraphQL.
 
 ## Using REST API
 
 **List sub-issues:**
-```
-GET /repos/{owner}/{repo}/issues/{issue_number}/sub_issues
+```bash
+gh api repos/{owner}/{repo}/issues/{issue_number}/sub_issues
 ```
 
 **Get parent issue:**
-```
-GET /repos/{owner}/{repo}/issues/{issue_number}/parent
+```bash
+gh api repos/{owner}/{repo}/issues/{issue_number}/parent
 ```
 
 **Add an existing issue as a sub-issue:**
-```
-POST /repos/{owner}/{repo}/issues/{issue_number}/sub_issues
-Body: { "sub_issue_id": 12345 }
+```bash
+# sub_issue_id is the numeric issue ID (not the issue number)
+# Get it from the .id field when creating or fetching an issue
+echo '{"sub_issue_id": 12345}' | gh api repos/{owner}/{repo}/issues/{parent_number}/sub_issues -X POST --input -
 ```
 
-The `sub_issue_id` is the numeric issue **ID** (not the issue number). Get it from the issue's `id` field in any API response.
-
-To move a sub-issue that already has a parent, add `"replace_parent": true`.
+To move a sub-issue that already has a parent, add `"replace_parent": true` to the JSON body.
 
 **Remove a sub-issue:**
-```
-DELETE /repos/{owner}/{repo}/issues/{issue_number}/sub_issue
-Body: { "sub_issue_id": 12345 }
+```bash
+echo '{"sub_issue_id": 12345}' | gh api repos/{owner}/{repo}/issues/{parent_number}/sub_issue -X DELETE --input -
 ```
 
 **Reprioritize a sub-issue:**
-```
-PATCH /repos/{owner}/{repo}/issues/{issue_number}/sub_issues/priority
-Body: { "sub_issue_id": 6, "after_id": 5 }
+```bash
+echo '{"sub_issue_id": 6, "after_id": 5}' | gh api repos/{owner}/{repo}/issues/{parent_number}/sub_issues/priority -X PATCH --input -
 ```
 
 Use `after_id` or `before_id` to position the sub-issue relative to another.