summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorbot <bot@x>2026-11-13 11:02:50 +0000
committerbot <bot@x>2026-11-13 11:05:00 +0000
commitc378aad9570133006c4b81500d06aed67aeee6af (patch)
tree0be8bad4b82e83649601103714aae4f5ac3e9bab
parent5863806dd4e15c63174bee4e7515a4256792ecfa (diff)
setup-matt-pocock-skills: record how to attach a file to a commenttracker-attach-files
The issue-tracker doc now says how a skill attaches an image or video to a comment on an issue or PR (gh --attach on GitHub, the uploads API on GitLab, an assets/ folder for local markdown, the user's own method or "can't" for other trackers), and Read a PR / Read an MR move into Conventions so skills other than triage can read a PR. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
-rw-r--r--.changeset/tracker-attach-files.md5
-rw-r--r--docs/engineering/setup-matt-pocock-skills.md6
-rw-r--r--skills/engineering/setup-matt-pocock-skills/SKILL.md4
-rw-r--r--skills/engineering/setup-matt-pocock-skills/issue-tracker-github.md8
-rw-r--r--skills/engineering/setup-matt-pocock-skills/issue-tracker-gitlab.md8
-rw-r--r--skills/engineering/setup-matt-pocock-skills/issue-tracker-local.md5
6 files changed, 29 insertions, 7 deletions
diff --git a/.changeset/tracker-attach-files.md b/.changeset/tracker-attach-files.md
new file mode 100644
index 0000000..c54d5cc
--- /dev/null
+++ b/.changeset/tracker-attach-files.md
@@ -0,0 +1,5 @@
+---
+"mattpocock-skills": patch
+---
+
+`setup-matt-pocock-skills` now records how to attach a file (an image or a video) to a comment on an issue or PR in `docs/agents/issue-tracker.md`: `gh issue comment` / `gh pr comment --attach` on GitHub, an uploads-API Markdown link on GitLab, an `assets/` folder for local markdown, and for any other tracker the user's own method or a note that it can't. Each template gains a "When a skill says 'attach a file to a comment'" section, and "Read a PR" / "Read an MR" moves into Conventions so any skill can read a PR, not just triage.
diff --git a/docs/engineering/setup-matt-pocock-skills.md b/docs/engineering/setup-matt-pocock-skills.md
index 4b255af..b349b4b 100644
--- a/docs/engineering/setup-matt-pocock-skills.md
+++ b/docs/engineering/setup-matt-pocock-skills.md
@@ -42,11 +42,11 @@ The tracker options:
| **GitHub** | the repo's GitHub Issues | the `gh` CLI |
| **GitLab** | the repo's GitLab Issues | the `glab` CLI |
| **Local markdown** | files under `.scratch/<feature>/` in this repo | nothing, not even a remote |
-| **Other** | wherever you say | one paragraph from you describing the workflow |
+| **Other** | wherever you say | one paragraph from you describing the workflow, including how to attach a file to a comment |
-The first three ship as templates in the skill and work out of the box. Local markdown is a full option, not a fallback. The skill supports a solo project with no remote. One caveat: don't use local markdown if you use GitHub. They are alternatives, so pick one.
+The first three ship as templates in the skill and work out of the box. Each also records how a skill attaches a file (an image or a video) to a comment on an issue or PR: `gh issue comment` / `gh pr comment --attach` on GitHub, an upload through GitLab's API, or a copy in an `assets/` folder for local markdown. Skills that make media, like an animatic of a PR, post it that way instead of calling a tracker's CLI themselves. Local markdown is a full option, not a fallback. The skill supports a solo project with no remote. One caveat: don't use local markdown if you use GitHub. They are alternatives, so pick one.
-"Other" is a full option too. It is how Jira, Linear, Azure DevOps and Beads all work. You describe the workflow, the skill records your prose in `docs/agents/issue-tracker.md`, and the downstream skills follow the prose. Users have already built this: a Jira-over-[MCP](https://www.aihero.dev/ai-coding-dictionary/mcp) variant, a Gitea CLI shaped like `gh`, a hand-built local dashboard.
+"Other" is a full option too. It is how Jira, Linear, Azure DevOps and Beads all work. You describe the workflow (and how to attach a file, or that your tracker can't), the skill records your prose in `docs/agents/issue-tracker.md`, and the downstream skills follow the prose. Users have already built this: a Jira-over-[MCP](https://www.aihero.dev/ai-coding-dictionary/mcp) variant, a Gitea CLI shaped like `gh`, a hand-built local dashboard.
## Common questions
diff --git a/skills/engineering/setup-matt-pocock-skills/SKILL.md b/skills/engineering/setup-matt-pocock-skills/SKILL.md
index 2df0b07..7668b10 100644
--- a/skills/engineering/setup-matt-pocock-skills/SKILL.md
+++ b/skills/engineering/setup-matt-pocock-skills/SKILL.md
@@ -44,7 +44,7 @@ Default posture: these skills were designed for GitHub. If a `git remote` points
- **GitHub**: issues live in the repo's GitHub Issues (uses the `gh` CLI)
- **GitLab**: issues live in the repo's GitLab Issues (uses the [`glab`](https://gitlab.com/gitlab-org/cli) CLI)
- **Local markdown**: issues live as files under `.scratch/<feature>/` in this repo (good for solo projects or repos without a remote)
-- **Other** (Jira, Linear, etc.): ask the user to describe the workflow in one paragraph; the skill will record it as freeform prose
+- **Other** (Jira, Linear, etc.): ask the user to describe the workflow in one paragraph, including how to attach a file (an image or a video) to a comment, or that their tracker can't; the skill will record it as freeform prose
Record the choice in `docs/agents/issue-tracker.md`. The GitHub and GitLab templates carry a "PRs as a request surface" flag, defaulted **off**. Leave it off and don't raise it: a user who wants external PRs in the triage queue can flip the flag in the file later.
@@ -113,7 +113,7 @@ Then write the docs files using the seed templates in this skill folder as a sta
- [triage-labels.md](./triage-labels.md): label mapping (only if `triage` is installed)
- [domain.md](./domain.md): domain doc consumer rules + layout
-For "other" issue trackers, write `docs/agents/issue-tracker.md` from scratch using the user's description.
+For "other" issue trackers, write `docs/agents/issue-tracker.md` from scratch using the user's description. Give it the same `## When a skill says "..."` sections as the templates, including "attach a file to a comment"; where the tracker can't attach, that section says so, and a skill hands the user the file's path instead.
### 5. Done
diff --git a/skills/engineering/setup-matt-pocock-skills/issue-tracker-github.md b/skills/engineering/setup-matt-pocock-skills/issue-tracker-github.md
index dc806f5..035636a 100644
--- a/skills/engineering/setup-matt-pocock-skills/issue-tracker-github.md
+++ b/skills/engineering/setup-matt-pocock-skills/issue-tracker-github.md
@@ -11,6 +11,8 @@ Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all o
- **Blocking**: GitHub's **native issue dependencies**, the canonical, UI-visible representation. Add an edge with `gh issue create --blocked-by <n>,<n> ...` or `gh issue edit <child> --add-blocked-by <blocker>` (`gh` 2.94+). Older `gh`: `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
- **Count open blockers**: `gh api repos/<owner>/<repo>/issues/<n> --jq .issue_dependencies_summary.blocked_by` (open blockers only; 0 means startable). `gh issue view <n> --json blockedBy` also lists closed blockers, so filter it: `--jq '[.blockedBy.nodes[] | select(.state == "OPEN")] | length'`.
- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Attach a file to a comment** (an image or a video, on an issue or a PR): `gh issue comment <number> --attach <file> --body "..."`, or `gh pr comment <number> --attach <file> --body "..."`. GitHub uploads the file and renders it inline, a video as a player. Repeat `--attach` for several files. Videos are capped at 10MB on a free plan and 100MB on a paid one. `--attach` needs `gh` 2.102+ (`gh issue comment --help` lists it); on an older `gh`, hand the user the file to drag into the comment box in the browser.
+- **Read a PR**: `gh pr view <number> --json title,body,author,files,baseRefName,headRefName,closingIssuesReferences`, then `gh pr view <number> --comments` (off a TTY, `--comments` prints only the comments, not the body), and `gh pr diff <number>` for the diff.
- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
- **Close**: post the explanation with `gh issue comment <number> --body "..."`, then `gh issue close <number>`. On an already-closed issue, `gh issue close --comment` drops the comment and still exits 0.
@@ -24,7 +26,7 @@ File issues only into the user's own repo. Never file into `mattpocock/skills` (
When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:
-- **Read a PR**: `gh pr view <number>`, then `gh pr view <number> --comments` (off a TTY, `--comments` prints only the comments, not the body), and `gh pr diff <number>` for the diff.
+- **Read a PR**: as in **Read a PR** under Conventions.
- **List external PRs for triage**: `gh api --paginate 'repos/{owner}/{repo}/pulls?state=open' --jq '.[] | select(.author_association | IN("OWNER","MEMBER","COLLABORATOR") | not) | {number, title, author: .user.login, author_association, labels: [.labels[].name]}'`.
- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`.
@@ -38,6 +40,10 @@ Create a GitHub issue.
Read it as in **Read an issue** above.
+## When a skill says "attach a file to a comment"
+
+Post the comment with the file attached, as in **Attach a file to a comment** above.
+
## Wayfinding operations
Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
diff --git a/skills/engineering/setup-matt-pocock-skills/issue-tracker-gitlab.md b/skills/engineering/setup-matt-pocock-skills/issue-tracker-gitlab.md
index 1aeb5d0..d405bb6 100644
--- a/skills/engineering/setup-matt-pocock-skills/issue-tracker-gitlab.md
+++ b/skills/engineering/setup-matt-pocock-skills/issue-tracker-gitlab.md
@@ -8,9 +8,11 @@ Issues and specs for this repo live as GitLab issues. Use the [`glab`](https://g
- **Read an issue**: `glab issue view <number> --comments`. Use `-F json` for machine-readable output.
- **List issues**: `glab issue list -O json` with appropriate `--label` filters.
- **Comment on an issue**: `glab issue note <number> --message "..."`. GitLab calls comments "notes".
+- **Attach a file to a comment** (an image or a video, on an issue or an MR): upload it to the project, then post the Markdown the upload returns as the note. The upload is a multipart POST to the project uploads API, with a token from the environment: `curl -sf --header "PRIVATE-TOKEN: $GITLAB_TOKEN" --form "file=@<file>" "https://<host>/api/v4/projects/<url-encoded owner%2Frepo>/uploads"`. Its JSON `markdown` field (`![name](/uploads/...)`) renders the file inline, a video as a player: post it with `glab issue note <number> --message "<text> <markdown>"` (or `glab mr note`). The size limit is the instance's attachment limit.
- **Apply / remove labels**: `glab issue update <number> --label "..."` / `--unlabel "..."`. Multiple labels can be comma-separated or by repeating the flag.
- **Close**: `glab issue close <number>`. `glab issue close` does not accept a closing comment, so post the explanation first with `glab issue note <number> --message "..."`, then close.
- **Merge requests**: GitLab calls PRs "merge requests". Use `glab mr create`, `glab mr view`, `glab mr note`, etc., the same shape as `gh pr ...` with `mr` in place of `pr` and `note`/`--message` in place of `comment`/`--body`.
+- **Read an MR**: `glab mr view <number> --comments` and `glab mr diff <number>` for the diff.
Infer the repo from `git remote -v`; `glab` does this automatically when run inside a clone.
@@ -20,7 +22,7 @@ Infer the repo from `git remote -v`; `glab` does this automatically when run ins
When set to `yes`, MRs run through the same labels and states as issues, using the `glab mr` equivalents:
-- **Read an MR**: `glab mr view <number> --comments` and `glab mr diff <number>` for the diff.
+- **Read an MR**: as in **Read an MR** under Conventions.
- **List external MRs for triage**: `glab mr list -O json`, then keep only MRs whose author is not a project member/owner (a contributor's MR, not a maintainer's in-flight work).
- **Comment / label / close**: `glab mr note`, `glab mr update --label`/`--unlabel`, `glab mr close`.
@@ -34,6 +36,10 @@ Create a GitLab issue.
Run `glab issue view <number> --comments`.
+## When a skill says "attach a file to a comment"
+
+Upload the file and post its Markdown in a note, as in **Attach a file to a comment** above.
+
## Wayfinding operations
Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
diff --git a/skills/engineering/setup-matt-pocock-skills/issue-tracker-local.md b/skills/engineering/setup-matt-pocock-skills/issue-tracker-local.md
index 0209a19..0ebb81e 100644
--- a/skills/engineering/setup-matt-pocock-skills/issue-tracker-local.md
+++ b/skills/engineering/setup-matt-pocock-skills/issue-tracker-local.md
@@ -9,6 +9,7 @@ Issues and specs for this repo live as markdown files in `.scratch/`.
- Implementation issues are one file per ticket at `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01`, never a single combined tickets file
- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)
- Comments and conversation history append to the bottom of the file under a `## Comments` heading
+- An attached file (an image or a video) is copied into `.scratch/<feature-slug>/assets/` and linked from the comment with a relative path: `![alt](../assets/<file>)` from a ticket under `issues/`, `![alt](assets/<file>)` from `spec.md`
## When a skill says "publish to the issue tracker"
@@ -18,6 +19,10 @@ Create a new file under `.scratch/<feature-slug>/` (creating the directory if ne
Read the file at the referenced path. The user will normally pass the path or the issue number directly.
+## When a skill says "attach a file to a comment"
+
+Copy the file into the feature's `assets/` folder and link it from a comment under `## Comments`.
+
## Wayfinding operations
Used by `/wayfinder`. The **map** is a file with one **child** file per ticket.