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/issue-fields.md

@@ -125,3 +125,67 @@ mutation {
   }
 }'
 ```
+
+## Searching by field values
+
+### GraphQL bulk query (recommended)
+
+The most reliable way to find issues by field value is to fetch issues via GraphQL and filter by `issueFieldValues`. The search qualifier syntax (`field.name:value`) is not yet reliable across all environments.
+
+```bash
+# Find all open P1 issues in a repo
+gh api graphql -H "GraphQL-Features: issue_fields" -f query='
+{
+  repository(owner: "OWNER", name: "REPO") {
+    issues(first: 100, states: OPEN) {
+      nodes {
+        number
+        title
+        updatedAt
+        assignees(first: 3) { nodes { login } }
+        issueFieldValues(first: 10) {
+          nodes {
+            __typename
+            ... on IssueFieldSingleSelectValue {
+              name
+              field { ... on IssueFieldSingleSelect { name } }
+            }
+          }
+        }
+      }
+    }
+  }
+}' --jq '
+  [.data.repository.issues.nodes[] |
+    select(.issueFieldValues.nodes[] |
+      select(.field.name == "Priority" and .name == "P1")
+    ) |
+    {number, title, updatedAt, assignees: [.assignees.nodes[].login]}
+  ]'
+```
+
+**Schema notes for `IssueFieldSingleSelectValue`:**
+- The selected option's display text is in `.name` (not `.value`)
+- Also available: `.color`, `.description`, `.id`
+- The parent field reference is in `.field` (use inline fragment to get the field name)
+
+### Search qualifier syntax (experimental)
+
+Issue fields may also be searchable using dot notation in search queries. This requires `advanced_search=true` on REST or `ISSUE_ADVANCED` search type on GraphQL, but results are inconsistent and may return 0 results even when matching issues exist.
+
+```
+field.priority:P0                  # Single-select equals value
+field.target-date:>=2026-04-01     # Date comparison
+has:field.priority                 # Has any value set
+no:field.priority                  # Has no value set
+```
+
+Field names use the **slug** (lowercase, hyphens for spaces). For example, "Target Date" becomes `target-date`.
+
+```bash
+# REST API (may not return results in all environments)
+gh api "search/issues?q=repo:owner/repo+field.priority:P0+is:open&advanced_search=true" \
+  --jq '.items[] | "#\(.number): \(.title)"'
+```
+
+> **Warning:** The colon notation (`field:Priority:P1`) is silently ignored. If using search qualifiers, always use dot notation (`field.priority:P1`). However, the GraphQL bulk query approach above is more reliable. See [search.md](search.md) for the full search guide.