Merge pull request #1179 from mattpocock/scope-and-issue-templates

Add SCOPE.md, issue forms, and out-of-scope records
This commit is contained in:
Matt Pocock authored and GitHub committed 2026-10-06 13:15:48 +01:00
commit c665c5559e
13 files changed
+264 -21

No files matched your search

+11 -3
View File
@@ -2,7 +2,7 @@
One install story, one wording. `README.md`, `.changeset/*`, and every page under `docs/` must say **this** and nothing else. Change it here first, then propagate.
`mattpocock-skills` is listed in **Claude Code's official marketplace** (configured name `claude-plugins-official`, source repo `anthropics/claude-plugins-official`), which every Claude Code install has out of the box. There is no marketplace to add first. Official Anthropic marketplaces have auto-update enabled by default ([discover-plugins](https://code.claude.com/docs/en/discover-plugins)), so "updates arrive automatically" is a true claim, not a hope.
`mattpocock-skills` is listed in **Claude Code's official marketplace** (configured name `claude-plugins-official`, source repo `anthropics/claude-plugins-official`), which every Claude Code install has out of the box. There is no marketplace to add first. Official Anthropic marketplaces have auto-update enabled by default ([discover-plugins](https://code.claude.com/docs/en/discover-plugins)), but the listing pins this repo to a commit `sha` that Anthropic moves by hand, so installed users only see a release once that pin moves (see ADR 0002's 2026-08-05 update). Never promise that updates arrive automatically or immediately; the block below says when they arrive and how to track the repo directly instead.
## Claude Code: the plugin
@@ -18,7 +18,15 @@ Or, from inside a session:
/plugin install mattpocock-skills
```
It's in Claude Code's official marketplace, so there's nothing to add first, and updates arrive automatically.
It's in Claude Code's official marketplace, so there's nothing to add first. Updates reach you when Anthropic's marketplace moves its pin to a new release, which can lag behind this repo by days or weeks.
**Stuck on an old version?** `claude plugin list` shows what you have, and [CHANGELOG.md](../CHANGELOG.md) shows the latest release. To track this repo directly instead, switch to its own marketplace and turn on auto-update for it under `/plugin` → Marketplaces (it's off by default for marketplaces outside Anthropic's):
```bash
claude plugin uninstall mattpocock-skills@claude-plugins-official
claude plugin marketplace add mattpocock/skills
claude plugin install mattpocock-skills@mattpocock
```
</canonical-block>
@@ -58,4 +66,4 @@ The plugin is a managed, read-only bundle you subscribe to. skills.sh writes fil
## Not the install story
`.claude-plugin/marketplace.json` makes the repo its own single-plugin marketplace (`/plugin marketplace add mattpocock/skills`, then `/plugin install mattpocock-skills@mattpocock`). The official listing supersedes it. It is kept as a fallback for installing the repo directly (an unreleased commit, or a fork), and is **not** documented to users.
`.claude-plugin/marketplace.json` makes the repo its own single-plugin marketplace (`/plugin marketplace add mattpocock/skills`, then `/plugin install mattpocock-skills@mattpocock`). The official listing supersedes it. It is kept as a fallback for installing the repo directly (an unreleased commit, or a fork). Users see it in exactly one place: the "Stuck on an old version?" escape hatch in the `claude-code` block, for when the official pin lags. It is never offered as the primary route.
+43
View File
@@ -0,0 +1,43 @@
name: Bug
description: A skill did the wrong thing in a real session.
labels: ["bug"]
body:
- type: markdown
attributes:
value: |
Bugs in `skills/misc/` are not fixed (see [`.out-of-scope/frozen-misc-skills.md`](https://github.com/mattpocock/skills/blob/main/.out-of-scope/frozen-misc-skills.md)). Installer problems with `npx skills` belong at skills.sh.
- type: input
id: skill
attributes:
label: Skill
description: Which skill, e.g. `to-tickets`, `grilling`.
validations:
required: true
- type: input
id: harness
attributes:
label: Harness and version
description: e.g. Claude Code 2.3.1, Codex CLI 0.40, Cursor. Say how you installed (plugin or skills.sh) and which skills version.
validations:
required: true
- type: input
id: model
attributes:
label: Model and effort
description: e.g. Opus, high effort. Roughly how full was the context when it happened?
validations:
required: true
- type: textarea
id: what-happened
attributes:
label: What happened
description: What you ran, and what the skill did. Paste the relevant part of the session.
validations:
required: true
- type: textarea
id: expected
attributes:
label: What you expected
description: What the skill should have done instead, and which line of the SKILL.md (if any) says so.
validations:
required: true
+5
View File
@@ -0,0 +1,5 @@
blank_issues_enabled: false
contact_links:
- name: Questions and discussion
url: https://github.com/mattpocock/skills/discussions
about: How-do-I questions, ideas you want to talk through, and anything that isn't a concrete failure in a skill.
+40
View File
@@ -0,0 +1,40 @@
name: Idea or feedback
description: A change to an existing skill, grounded in a failure you saw.
body:
- type: markdown
attributes:
value: |
This repo is curated. An idea stays open only if it clears **both** parts of the bar in [`SCOPE.md`](https://github.com/mattpocock/skills/blob/main/SCOPE.md):
1. **Observed failure**: it describes something that went wrong in a real session, not a hypothetical improvement.
2. **Fits the philosophy**: it doesn't match anything in [`.out-of-scope/`](https://github.com/mattpocock/skills/tree/main/.out-of-scope), and it isn't a config option, a harness-specific branch, or a personal-workflow tweak.
New skills are not accepted. `misc/` skills are frozen.
- type: checkboxes
id: read-scope
attributes:
label: Before filing
options:
- label: I've read `SCOPE.md` and checked `.out-of-scope/`, and this isn't covered by either.
required: true
- type: input
id: skill
attributes:
label: Skill
description: Which existing skill this changes.
validations:
required: true
- type: textarea
id: observed
attributes:
label: What went wrong
description: The real session where the skill fell short. What you ran, what it did, and why that was a problem. Include harness and model.
validations:
required: true
- type: textarea
id: change
attributes:
label: Proposed change
description: What you'd change in the skill, as concretely as you can.
validations:
required: true
+18
View File
@@ -0,0 +1,18 @@
# Changes to `misc/` skills
The skills under `skills/misc/` (`git-guardrails-claude-code`, `migrate-to-shoehorn`, `scaffold-exercises`, `setup-pre-commit`, and anything else that lands there) are frozen. Bug reports, feature requests and PRs against them are closed.
## Why this is out of scope
`misc/` is where skills go when I keep them around but rarely use them. They aren't promoted: they don't ship in the Claude Code plugin, they have no docs page, and I'm not running them day to day, so I can't tell whether a fix is right or notice when one breaks something else. Maintaining them at the same bar as the promoted skills would cost the same as a promoted skill for a fraction of the use.
They stay in the repo, unmaintained, because they still work for some people as-is. If one doesn't work for you, install it with skills.sh and fix your copy: the files are yours to edit.
If a `misc/` skill is promoted back into `engineering/` or `productivity/` later, it's back in scope from that point.
## Prior requests
- #14: "Potential typo in setup-pre-commit/SKILL.md"
- #301: "`block-dangerous-git.sh` is bypassed by any git global option (e.g. `git -C <dir> push`)"
- #465: "git-guardrails-claude-code documentation is missing benefits over built in Claude code deny rules"
- #898: "git-guardrails-claude-code: hook fails open without jq and misses common git spellings"
+28
View File
@@ -0,0 +1,28 @@
# Renaming skills to dodge harness built-in commands
Skill names are not changed because a harness ships a built-in command or skill with the same name (`/prototype`, `/research`, `/code-review`, and so on). Requests to rename a skill, or add an alias, to avoid a collision are out of scope.
## Why this is out of scope
Harnesses add built-ins all the time, and each harness picks its own names. Renaming every time one of them lands on a name we already use would mean chasing a moving target across Claude Code, Copilot, Devin and the rest, and breaking every user's muscle memory and every cross-reference between skills each time.
How a harness resolves two things with the same name is the harness's behaviour, not the skill's. The skill text is correct either way.
The way through is namespaced invocation. The Claude Code plugin exposes every skill under its plugin name, so you can always reach ours explicitly:
```
/mattpocock-skills:research
/mattpocock-skills:code-review
```
If you installed with skills.sh, the files are yours: rename the folder and the `name:` field in your copy.
If a harness gives you no way to reach a namespaced or renamed skill at all, report that to the harness.
## Prior requests
- #423: "/code-review shadows Claude Code own review skill"
- #483: "/code-review name clash with Claude Code built-in"
- #857: "Rename the research skill to avoid conflict with Copilot's built-in /research command"
- #1019: "Shorthand `/prototype` conflicts with hidden new Claude Code built-in skill `/prototype`"
- #1037: "Skill name overlap with devin cli inbuilt commands"
+13 -15
View File
@@ -1,25 +1,23 @@
# Issue tracker integrations are limited to mainstream tools
# Issue tracker integrations: GitHub, GitLab and local markdown only
`setup-matt-pocock-skills` only offers first-class support for **mainstream** issue trackers. Requests to add support for niche, new, or single-vendor experimental trackers are out of scope.
`setup-matt-pocock-skills` offers first-class support for exactly three issue trackers, one per seed template in `skills/engineering/setup-matt-pocock-skills/`:
- **GitHub** (`issue-tracker-github.md`, via `gh`)
- **GitLab** (`issue-tracker-gitlab.md`, via `glab`)
- **Local markdown** (`issue-tracker-local.md`, files under `.scratch/`)
Requests to add a first-class backend for any other tracker are out of scope. That includes Jira, Linear, Azure DevOps, Trello, YouTrack, and new agent-focused trackers.
## Why this is out of scope
Every issue-tracker backend hard-codes a CLI shape into the skills (commands, flags, output parsing). Each new backend is permanent maintenance surface, because it has to keep working as the tool's CLI evolves, and it has to keep being tested against `/to-spec`, `/to-tickets`, `/triage`, and friends. That cost is only worth paying for trackers a meaningful fraction of users actually have.
Every issue-tracker backend hard-codes a CLI shape into the skills (commands, flags, output parsing). Each new backend is permanent maintenance surface, because it has to keep working as the tool's CLI evolves, and it has to keep being tested against `/to-spec`, `/to-tickets`, `/triage`, and friends. I use GitHub, so that's the backend I can actually keep correct. GitLab is close enough in shape to ride along, and local markdown needs no CLI at all.
"Mainstream" is a judgment call, not a numeric bar:
Popularity doesn't change this. Jira is widely used and has an official CLI (`acli`), and it still isn't getting a template: it's a backend I don't run, with its own link semantics, workflow states and CLI quirks to keep tested. The cost lands on me whether or not the tool is mainstream.
- GitHub, GitLab, and Backlog.md are the kind of tools we'd consider mainstream: broadly known, widely used, well past the experimental phase.
- A brand-new agent-focused tool with a few hundred GitHub stars is not, no matter how interesting the design.
Stars, age, and download counts are useful signals when making the call but none of them is the rule. The rule is: would a typical engineer recognise this tool and have plausibly chosen it for their team?
The escape hatches for non-mainstream trackers already exist:
- `local markdown` for lightweight in-repo tracking.
- `other/custom` for users who want to wire something up themselves.
Neither requires the core skills to know about the specific tool.
Every other tracker goes through the **Other** option in `/setup-matt-pocock-skills`: you describe your workflow in a paragraph and the skill records it as prose in `docs/agents/issue-tracker.md`. That file is yours. If you've refined a Jira or Linear workflow that works, keep it in your own repo or publish it, and point the setup at it.
## Prior requests
- #99: "Add dex as an issue tracker backend" (dex was ~3 months old and ~300 stars at the time of the request)
- #258: "Add Jira as first-class issue tracker via Rovo MCP"
- #1137: "Add Jira as a first-class issue tracker, via Atlassian's official CLI (`acli`)"
+19
View File
@@ -0,0 +1,19 @@
# Grilling through the harness's native question tool
Grilling sessions (`/grilling`, `/grill-me`, `/grill-with-docs`, and grilling inside other skills) ask their questions as plain chat text. Requests to route them through a harness's built-in question UI (Claude Code's `AskUserQuestion`, a host "question tool", a structured or batched questionnaire mode) are out of scope.
## Why this is out of scope
The skills are harness-neutral text. They run in Claude Code, Codex, Copilot, Cursor and anything else skills.sh installs into, and each harness has a different question tool, or none. Naming one harness's tool in the skill means either a harness-specific branch in every grilling skill, or a skill that only works properly in one place.
The question UI also changes the grilling itself. Structured pickers push the model towards multiple-choice questions with pre-baked answers, which is the opposite of what grilling is for: open questions you answer in your own words, one branch of the decision tree at a time. I've tried the `AskUserQuestion` UI and don't want it in these skills.
If you prefer your harness's question tool, say so in your own `CLAUDE.md` / `AGENTS.md` ("when grilling, ask via AskUserQuestion"). That's a one-line, per-user preference, and it doesn't need the shared skill to know about it.
## Prior requests
- #19: "grill-me: not always using the question tool"
- #643: "Proposal: Use AskQuestion for structured input during grilling sessions"
- #840: "Use host's question tool for grilling sessions"
- #1107: "Grilling doesn't use Agent's native QA tool OOTB"
- #1152: "Proposal: experimental HTML questionnaire mode for batch grilling"
+21
View File
@@ -0,0 +1,21 @@
# New skill proposals and contributions
This repo does not take proposals or contributions for new skills, including ones that arrive with a ready branch or a fork.
## Why this is out of scope
The catalog is the set of skills I use myself every day, and it's deliberately small. Every skill is permanent maintenance surface: it has to stay in step with the others, with the docs pages, with `ask-matt`'s routing map, and with the plugin manifest. The shorter and fewer the skills, the cheaper they are to keep correct.
The rule I apply to my own ideas applies here too: if you can compose the behaviour from existing skills, it doesn't get a new skill. Most proposals are a specific workflow built out of grilling, `to-spec`, `to-tickets`, `implement` and friends, and that composition belongs in your own prompts or your own skills.
You're very welcome to publish a skill yourself. skills.sh makes that straightforward, and nothing here needs to know about it.
This covers *new* skills only. A concrete failure in an existing skill is judged against the bar in [`SCOPE.md`](../SCOPE.md) like any other issue.
## Prior requests
- #101: "Any skill to iteratively build CONTEXT.md (and ADRs) for a brownfield codebase?"
- #414: "Add a `handoff-to-pro` skill for generating one-shot prompts for external frontier chat models"
- #727: "new skill - teach pr"
- #1051: "Contribution ready: /red-team, the optional pre-implementation spec review from #633"
- #1166: "Skill proposal: agent-chat-ux for productivity (branch ready on fork)"
+6
View File
@@ -23,3 +23,9 @@ Every `SKILL.md` is either user-invoked (`disable-model-invocation: true` plus `
To (re)link every skill outside `deprecated/` and `misc/` into the local harness skill directories (`~/.claude/skills`, `~/.agents/skills`), run `scripts/link-skills.sh`. Each entry is a symlink into this repo, so a `git pull` keeps installed skills current; re-run the script after adding, removing, or renaming a skill.
No em-dashes anywhere in this repo's prose (`SKILL.md` files, docs, `README.md`, `CHANGELOG.md`, ADRs, changesets, code comments). Where a sentence reaches for one, rewrite it instead with a comma, colon, period, parentheses, or a conjunction, whichever the sentence actually wants; never do a blind character substitution.
## Agent skills
### Triage labels
Canonical names, unchanged. See `docs/agents/triage-labels.md`. Issues are judged against [`SCOPE.md`](./SCOPE.md).
+11 -3
View File
@@ -24,7 +24,7 @@ If you want to keep up with changes to these skills, and any new ones I create,
## Installation (30-second setup)
Two ways in, two philosophies. **The [Claude Code plugin](https://code.claude.com/docs/en/plugins)** installs the whole set as a managed, read-only bundle that updates when I ship, so you subscribe rather than fork. **[skills.sh](https://skills.sh/mattpocock/skills)** copies editable skill files into your project, so you can hack on them and make them your own. Pick one: installing both leaves you with every skill twice.
Two ways in, two philosophies. **The [Claude Code plugin](https://code.claude.com/docs/en/plugins)** installs the whole set as a managed, read-only bundle that updates when Anthropic's marketplace picks up my releases, so you subscribe rather than fork. **[skills.sh](https://skills.sh/mattpocock/skills)** copies editable skill files into your project, so you can hack on them and make them your own. Pick one: installing both leaves you with every skill twice.
### 1. Get the skills
@@ -41,7 +41,15 @@ Or, from inside a session:
/plugin install mattpocock-skills
```
It's in Claude Code's official marketplace, so there's nothing to add first, and updates arrive automatically.
It's in Claude Code's official marketplace, so there's nothing to add first. Updates reach you when Anthropic's marketplace moves its pin to a new release, which can lag behind this repo by days or weeks.
**Stuck on an old version?** `claude plugin list` shows what you have, and [CHANGELOG.md](./CHANGELOG.md) shows the latest release. To track this repo directly instead, switch to its own marketplace and turn on auto-update for it under `/plugin` → Marketplaces (it's off by default for marketplaces outside Anthropic's):
```bash
claude plugin uninstall mattpocock-skills@claude-plugins-official
claude plugin marketplace add mattpocock/skills
claude plugin install mattpocock-skills@mattpocock
```
</details>
@@ -75,7 +83,7 @@ It writes the skills into your repo as ordinary files you own and can edit. Noth
In your agent, run it once per repo. It will:
- Ask you which issue tracker you want to use (GitHub, Linear, or local files)
- Ask you which issue tracker you want to use (GitHub, GitLab, local files, or anything else you describe)
- Ask you what labels you apply to tickets when you triage them (`/triage` uses labels)
- Ask you where you want to save any docs we create
+34
View File
@@ -0,0 +1,34 @@
# Scope
This repo is the set of skills I use every day. It is curated: ideas are welcome, and each one is judged against the bar below. Issues are for tracking changes to the skills. Questions and discussion go to [GitHub Discussions](https://github.com/mattpocock/skills/discussions).
## The bar
An idea or feedback issue stays open only if it clears **both** parts:
1. **Observed failure.** It describes something that went wrong in a real session: what you ran, what the skill did, what you expected. A hypothetical improvement ("it would be better if...") does not clear this part.
2. **Fits the philosophy.** It does not match anything in [`.out-of-scope/`](./.out-of-scope/) or a past rejection, and it is not a config option, a harness-specific branch, or a tweak to suit one person's workflow. Those belong in your own `CLAUDE.md` / `AGENTS.md`, or in a fork (skills.sh gives you an editable copy).
Size is irrelevant: a one-word fix and a rewrite face the same bar. Reactions and +1 comments do not count towards it.
## By bucket
- **`engineering/`, `productivity/`, `in-progress/`**: the bar above.
- **`misc/`**: frozen and unmaintained. Every issue is closed. See [`frozen-misc-skills.md`](./.out-of-scope/frozen-misc-skills.md).
- **New skills**: proposals and contributions are closed. If the behaviour composes from existing skills, it does not get a new one. See [`new-skills.md`](./.out-of-scope/new-skills.md).
## Already decided
Each file in [`.out-of-scope/`](./.out-of-scope/) records one rejected concept and why. Read them before filing:
- [`frozen-misc-skills.md`](./.out-of-scope/frozen-misc-skills.md)
- [`harness-name-collisions.md`](./.out-of-scope/harness-name-collisions.md)
- [`mainstream-issue-trackers-only.md`](./.out-of-scope/mainstream-issue-trackers-only.md)
- [`native-question-tool.md`](./.out-of-scope/native-question-tool.md)
- [`new-skills.md`](./.out-of-scope/new-skills.md)
- [`question-limits.md`](./.out-of-scope/question-limits.md)
- [`setup-skill-verify-mode.md`](./.out-of-scope/setup-skill-verify-mode.md)
## Unclear issues
An issue that can't be judged against the bar gets one round of questions and the `needs-info` label. With no reply from the reporter in 14 days, it is closed. Rejections close as "not planned".
+15
View File
@@ -0,0 +1,15 @@
# Triage Labels
The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
| Label in mattpocock/skills | Label in our tracker | Meaning |
| -------------------------- | -------------------- | ---------------------------------------- |
| `needs-triage` | `needs-triage` | Maintainer needs to evaluate this issue |
| `needs-info` | `needs-info` | Waiting on reporter for more information |
| `ready-for-agent` | `ready-for-agent` | Fully specified, ready for an AFK agent |
| `ready-for-human` | `ready-for-human` | Requires human implementation |
| `wontfix` | `wontfix` | Will not be actioned |
When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
Judge every issue against [`SCOPE.md`](../../SCOPE.md) before picking a state. Rejections close as "not planned".