github
diff --git a/‎docs/README.skills.md‎
Lines changed: 1 addition & 1 deletion b/‎docs/README.skills.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎skills/github-issues/SKILL.md‎
Lines changed: 95 additions & 49 deletions b/‎skills/github-issues/SKILL.md‎
Lines changed: 95 additions & 49 deletions
diff --git a/‎skills/github-issues/references/images.md‎
Lines changed: 116 additions & 0 deletions b/‎skills/github-issues/references/images.md‎
Lines changed: 116 additions & 0 deletions
@@ -122,7 +122,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to
 | [git-commit](../skills/git-commit/SKILL.md) | Execute git commit with conventional commit message analysis, intelligent staging, and message generation. Use when user asks to commit changes, create a git commit, or mentions "/commit". Supports: (1) Auto-detecting type and scope from changes, (2) Generating conventional commit messages from diff, (3) Interactive commit with optional type/scope/description overrides, (4) Intelligent file staging for logical grouping | None |
 | [git-flow-branch-creator](../skills/git-flow-branch-creator/SKILL.md) | Intelligent Git Flow branch creator that analyzes git status/diff and creates appropriate branches following the nvie Git Flow branching model. | None |
 | [github-copilot-starter](../skills/github-copilot-starter/SKILL.md) | Set up complete GitHub Copilot configuration for a new project based on technology stack | None |
-| [github-issues](../skills/github-issues/SKILL.md) | 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, or manage issue workflows. Triggers on requests like "create an issue", "file a bug", "request a feature", "update issue X", "set the priority", "set the start date", or any GitHub issue management task. | `references/dependencies.md`<br />`references/issue-fields.md`<br />`references/issue-types.md`<br />`references/projects.md`<br />`references/sub-issues.md`<br />`references/templates.md` |
+| [github-issues](../skills/github-issues/SKILL.md) | 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, or manage issue workflows. Triggers on requests like "create an issue", "file a bug", "request a feature", "update issue X", "set the priority", "set the start date", or any GitHub issue management task. | `references/dependencies.md`<br />`references/images.md`<br />`references/issue-fields.md`<br />`references/issue-types.md`<br />`references/projects.md`<br />`references/search.md`<br />`references/sub-issues.md`<br />`references/templates.md` |
 | [go-mcp-server-generator](../skills/go-mcp-server-generator/SKILL.md) | Generate a complete Go MCP server project with proper structure, dependencies, and implementation using the official github.com/modelcontextprotocol/go-sdk. | None |
 | [image-manipulation-image-magick](../skills/image-manipulation-image-magick/SKILL.md) | Process and manipulate images using ImageMagick. Supports resizing, format conversion, batch processing, and retrieving image metadata. Use when working with images, creating thumbnails, resizing wallpapers, or performing batch image operations. | None |
 | [import-infrastructure-as-code](../skills/import-infrastructure-as-code/SKILL.md) | Import existing Azure resources into Terraform using Azure CLI discovery and Azure Verified Modules (AVM). Use when asked to reverse-engineer live Azure infrastructure, generate Infrastructure as Code from existing subscriptions/resource groups/resource IDs, map dependencies, derive exact import addresses from downloaded module source, prevent configuration drift, and produce AVM-based Terraform files ready for validation and planning across any Azure resource type. | None |
 
@@ -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,46 +95,72 @@ 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
 
 ### Example 1: Bug Report
 
 **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) |
@@ -0,0 +1,116 @@
+# Images in Issues and Comments
+
+How to embed images in GitHub issue bodies and comments programmatically via the CLI.
+
+## Methods (ranked by reliability)
+
+### 1. GitHub Contents API (recommended for private repos)
+
+Push image files to a branch in the same repo, then reference them with a URL that works for authenticated viewers.
+
+**Step 1: Create a branch**
+
+```bash
+# Get the SHA of the default branch
+SHA=$(gh api repos/{owner}/{repo}/git/ref/heads/main --jq '.object.sha')
+
+# Create a new branch
+gh api repos/{owner}/{repo}/git/refs -X POST \
+  -f ref="refs/heads/{username}/images" \
+  -f sha="$SHA"
+```
+
+**Step 2: Upload images via Contents API**
+
+```bash
+# Base64-encode the image and upload
+BASE64=$(base64 -i /path/to/image.png)
+
+gh api repos/{owner}/{repo}/contents/docs/images/my-image.png \
+  -X PUT \
+  -f message="Add image" \
+  -f content="$BASE64" \
+  -f branch="{username}/images" \
+  --jq '.content.path'
+```
+
+Repeat for each image. The Contents API creates a commit per file.
+
+**Step 3: Reference in markdown**
+
+```markdown
+![Description](https://github.com/{owner}/{repo}/raw/{username}/images/docs/images/my-image.png)
+```
+
+> **Important:** Use `github.com/{owner}/{repo}/raw/{branch}/{path}` format, NOT `raw.githubusercontent.com`. The `raw.githubusercontent.com` URLs return 404 for private repos. The `github.com/.../raw/...` format works because the browser sends auth cookies when the viewer is logged in and has repo access.
+
+**Pros:** Works for any repo the viewer has access to, images live in version control, no expiration.
+**Cons:** Creates commits, viewers must be authenticated, images won't render in email notifications or for users without repo access.
+
+### 2. Gist hosting (public images only)
+
+Upload images as files in a gist. Only works for images you're comfortable making public.
+
+```bash
+# Create a gist with a placeholder file
+gh gist create --public -f description.md <<< "Image hosting gist"
+
+# Note: gh gist edit does NOT support binary files.
+# You must use the API to add binary content to gists.
+```
+
+> **Limitation:** Gists don't support binary file uploads via the CLI. You'd need to base64-encode and store as text, which won't render as images. Not recommended.
+
+### 3. Browser upload (most reliable rendering)
+
+The most reliable way to get permanent image URLs is through the GitHub web UI:
+
+1. Open the issue/comment in a browser
+2. Drag-drop or paste the image into the comment editor
+3. GitHub generates a permanent `https://github.com/user-attachments/assets/{UUID}` URL
+4. These URLs work for anyone, even without repo access, and render in email notifications
+
+> **Why the API can't do this:** GitHub's `upload/policies/assets` endpoint requires a browser session (CSRF token + cookies). It returns an HTML error page when called with API tokens. There is no public API for generating `user-attachments` URLs.
+
+## Taking screenshots programmatically
+
+Use `puppeteer-core` with local Chrome to screenshot HTML mockups:
+
+```javascript
+const puppeteer = require('puppeteer-core');
+
+const browser = await puppeteer.launch({
+  executablePath: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  defaultViewport: { width: 900, height: 600, deviceScaleFactor: 2 }
+});
+
+const page = await browser.newPage();
+await page.setContent(htmlString);
+
+// Screenshot specific elements
+const elements = await page.$$('.section');
+for (let i = 0; i < elements.length; i++) {
+  await elements[i].screenshot({ path: `mockup-${i + 1}.png` });
+}
+
+await browser.close();
+```
+
+> **Note:** MCP Playwright may not connect to localhost due to network isolation. Use puppeteer-core with a local Chrome installation instead.
+
+## Quick reference
+
+| Method | Private repos | Permanent | No auth needed | API-only |
+|--------|:---:|:---:|:---:|:---:|
+| Contents API + `github.com/raw/` | ✅ | ✅ | ❌ | ✅ |
+| Browser drag-drop (`user-attachments`) | ✅ | ✅ | ✅ | ❌ |
+| `raw.githubusercontent.com` | ❌ (404) | ✅ | ❌ | ✅ |
+| Gist | Public only | ✅ | ✅ | ❌ (no binary) |
+
+## Common pitfalls
+
+- **`raw.githubusercontent.com` returns 404 for private repos** even with a valid token in the URL. GitHub's CDN does not pass auth headers through.
+- **API download URLs are temporary.** URLs returned by `gh api repos/.../contents/...` with `download_url` include a token that expires.
+- **`upload/policies/assets` requires a browser session.** Do not attempt to call this endpoint from the CLI.
+- **Base64 encoding for large files** can hit API payload limits. The Contents API has a ~100MB file size limit but practical limits are lower for base64-encoded payloads.
+- **Email notifications** will not render images that require authentication. If email readability matters, use the browser upload method.