diff options
| author | bot <bot@x> | 2026-11-13 11:02:50 +0000 |
|---|---|---|
| committer | bot <bot@x> | 2026-11-13 11:05:00 +0000 |
| commit | c378aad9570133006c4b81500d06aed67aeee6af (patch) | |
| tree | 0be8bad4b82e83649601103714aae4f5ac3e9bab | |
| parent | 5863806dd4e15c63174bee4e7515a4256792ecfa (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>
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 (``) 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: `` from a ticket under `issues/`, `` 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. |
