devskill 2.0.6 → 2.0.8

package/skills/github-issues/references/dependencies.md

@@ -0,0 +1,71 @@
+# Issue Dependencies (Blocked By / Blocking)
+
+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.
+
+## Using REST API
+
+**List issues blocking this issue:**
+```
+GET /repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocked_by
+```
+
+**Add a blocking dependency:**
+```
+POST /repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocked_by
+Body: { "issue_id": 12345 }
+```
+
+The `issue_id` is the numeric issue **ID** (not the issue number).
+
+**Remove a blocking dependency:**
+```
+DELETE /repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocked_by/{issue_id}
+```
+
+## Using GraphQL
+
+**Read dependencies:**
+```graphql
+{
+  repository(owner: "OWNER", name: "REPO") {
+    issue(number: 123) {
+      blockedBy(first: 10) { nodes { number title state } }
+      blocking(first: 10) { nodes { number title state } }
+      issueDependenciesSummary { blockedBy blocking totalBlockedBy totalBlocking }
+    }
+  }
+}
+```
+
+**Add a dependency:**
+```graphql
+mutation {
+  addBlockedBy(input: {
+    issueId: "BLOCKED_ISSUE_NODE_ID"
+    blockingIssueId: "BLOCKING_ISSUE_NODE_ID"
+  }) {
+    blockingIssue { number title }
+  }
+}
+```
+
+**Remove a dependency:**
+```graphql
+mutation {
+  removeBlockedBy(input: {
+    issueId: "BLOCKED_ISSUE_NODE_ID"
+    blockingIssueId: "BLOCKING_ISSUE_NODE_ID"
+  }) {
+    blockingIssue { number title }
+  }
+}
+```
+
+## Tracked issues (read-only)
+
+Task-list tracking relationships are available via GraphQL as read-only fields:
+
+- `trackedIssues(first: N)` - issues tracked in this issue's task list
+- `trackedInIssues(first: N)` - issues whose task lists reference this issue
+
+These are set automatically when issues are referenced in task lists (`- [ ] #123`). There are no mutations to manage them.

package/skills/github-issues/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.

package/skills/github-issues/references/issue-fields.md

@@ -0,0 +1,191 @@
+# Issue Fields (GraphQL, Private Preview)
+
+> **Private preview:** Issue fields are currently in private preview. Request access at https://github.com/orgs/community/discussions/175366
+
+Issue fields are custom metadata (dates, text, numbers, single-select) defined at the organization level and set per-issue. They are separate from labels, milestones, and assignees. Common examples: Start Date, Target Date, Priority, Impact, Effort.
+
+**Important:** All issue field queries and mutations require the `GraphQL-Features: issue_fields` HTTP header. Without it, the fields are not visible in the schema.
+
+**Prefer issue fields over project fields.** When you need to set metadata like dates, priority, or status on an issue, use issue fields (which live on the issue itself) rather than project fields (which live on a project item). Issue fields travel with the issue across projects and views, while project fields are scoped to a single project. Only use project fields when issue fields are not available or when the field is project-specific (e.g., sprint iterations).
+
+## Discovering available fields
+
+Fields are defined at the org level. List them before trying to set values:
+
+```graphql
+# Header: GraphQL-Features: issue_fields
+{
+  organization(login: "OWNER") {
+    issueFields(first: 30) {
+      nodes {
+        __typename
+        ... on IssueFieldDate { id name }
+        ... on IssueFieldText { id name }
+        ... on IssueFieldNumber { id name }
+        ... on IssueFieldSingleSelect { id name options { id name color } }
+      }
+    }
+  }
+}
+```
+
+Field types: `IssueFieldDate`, `IssueFieldText`, `IssueFieldNumber`, `IssueFieldSingleSelect`.
+
+For single-select fields, you need the option `id` (not the name) to set values.
+
+## Reading field values on an issue
+
+```graphql
+# Header: GraphQL-Features: issue_fields
+{
+  repository(owner: "OWNER", name: "REPO") {
+    issue(number: 123) {
+      issueFieldValues(first: 20) {
+        nodes {
+          __typename
+          ... on IssueFieldDateValue {
+            value
+            field { ... on IssueFieldDate { id name } }
+          }
+          ... on IssueFieldTextValue {
+            value
+            field { ... on IssueFieldText { id name } }
+          }
+          ... on IssueFieldNumberValue {
+            value
+            field { ... on IssueFieldNumber { id name } }
+          }
+          ... on IssueFieldSingleSelectValue {
+            name
+            color
+            field { ... on IssueFieldSingleSelect { id name } }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Setting field values
+
+Use `setIssueFieldValue` to set one or more fields at once. You need the issue's node ID and the field IDs from the discovery query above.
+
+```graphql
+# Header: GraphQL-Features: issue_fields
+mutation {
+  setIssueFieldValue(input: {
+    issueId: "ISSUE_NODE_ID"
+    issueFields: [
+      { fieldId: "IFD_xxx", dateValue: "2026-04-15" }
+      { fieldId: "IFT_xxx", textValue: "some text" }
+      { fieldId: "IFN_xxx", numberValue: 3.0 }
+      { fieldId: "IFSS_xxx", singleSelectOptionId: "OPTION_ID" }
+    ]
+  }) {
+    issue { id title }
+  }
+}
+```
+
+Each entry in `issueFields` takes a `fieldId` plus exactly one value parameter:
+
+| Field type | Value parameter | Format |
+|-----------|----------------|--------|
+| Date | `dateValue` | ISO 8601 date string, e.g. `"2026-04-15"` |
+| Text | `textValue` | String |
+| Number | `numberValue` | Float |
+| Single select | `singleSelectOptionId` | ID from the field's `options` list |
+
+To clear a field value, set `delete: true` instead of a value parameter.
+
+## Workflow for setting fields
+
+1. **Discover fields** - query the org's `issueFields` to get field IDs and option IDs
+2. **Get the issue node ID** - from `repository.issue.id`
+3. **Set values** - call `setIssueFieldValue` with the issue node ID and field entries
+4. **Batch when possible** - multiple fields can be set in a single mutation call
+
+## Example: Set dates and priority on an issue
+
+```bash
+gh api graphql \
+  -H "GraphQL-Features: issue_fields" \
+  -f query='
+mutation {
+  setIssueFieldValue(input: {
+    issueId: "I_kwDOxxx"
+    issueFields: [
+      { fieldId: "IFD_startDate", dateValue: "2026-04-01" }
+      { fieldId: "IFD_targetDate", dateValue: "2026-04-30" }
+      { fieldId: "IFSS_priority", singleSelectOptionId: "OPTION_P1" }
+    ]
+  }) {
+    issue { id title }
+  }
+}'
+```
+
+## 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.

package/skills/github-issues/references/issue-types.md

@@ -0,0 +1,72 @@
+# Issue Types (Advanced GraphQL)
+
+Issue types (Bug, Feature, Task, Epic, etc.) are defined at the **organization** level and inherited by repositories. They categorize issues beyond labels.
+
+For basic usage, the MCP tools handle issue types natively. Call `mcp__github__list_issue_types` to discover types, and pass `type: "Bug"` to `mcp__github__create_issue` or `mcp__github__update_issue`. This reference covers advanced GraphQL operations.
+
+## GraphQL Feature Header
+
+All GraphQL issue type operations require the `GraphQL-Features: issue_types` HTTP header.
+
+## List types (org or repo level)
+
+```graphql
+# Header: GraphQL-Features: issue_types
+{
+  organization(login: "OWNER") {
+    issueTypes(first: 20) {
+      nodes { id name color description isEnabled }
+    }
+  }
+}
+```
+
+Types can also be listed per-repo via `repository.issueTypes` or looked up by name via `repository.issueType(name: "Bug")`.
+
+## Read an issue's type
+
+```graphql
+# Header: GraphQL-Features: issue_types
+{
+  repository(owner: "OWNER", name: "REPO") {
+    issue(number: 123) {
+      issueType { id name color }
+    }
+  }
+}
+```
+
+## Set type on an existing issue
+
+```graphql
+# Header: GraphQL-Features: issue_types
+mutation {
+  updateIssueIssueType(input: {
+    issueId: "ISSUE_NODE_ID"
+    issueTypeId: "IT_xxx"
+  }) {
+    issue { id issueType { name } }
+  }
+}
+```
+
+## Create issue with type
+
+```graphql
+# Header: GraphQL-Features: issue_types
+mutation {
+  createIssue(input: {
+    repositoryId: "REPO_NODE_ID"
+    title: "Fix login bug"
+    issueTypeId: "IT_xxx"
+  }) {
+    issue { id number issueType { name } }
+  }
+}
+```
+
+To clear the type, set `issueTypeId` to `null`.
+
+## Available colors
+
+`GRAY`, `BLUE`, `GREEN`, `YELLOW`, `ORANGE`, `RED`, `PINK`, `PURPLE`