mirror of
https://github.com/mattpocock/skills.git
synced 2026-07-29 02:52:42 +07:00
Matt PocockandClaude Opus 4.8
42a5b70fca
Add a Claude Code plugin marketplace so the promoted skills can be installed as a managed, read-only bundle (subscribe rather than fork), alongside the existing skills.sh installer. - Enrich .claude-plugin/plugin.json with marketplace metadata (version, description, author, license, keywords); keep the curated promoted-only skills array. - Add .claude-plugin/marketplace.json making the repo its own single-plugin marketplace (mattpocock-skills@mattpocock). - README: document /plugin install alongside skills.sh, and the subscribe-vs-fork tradeoff. - CLAUDE.md: extend the promoted-set invariant to cover marketplace.json and plugin.json/package.json version sync. - ADR 0002: record why Claude ships now and a native Codex plugin is deferred (Codex skills field is single-path + drops symlinks, which can't express a curated subset of a bucketed repo without a restructure). Verified: 'claude plugin validate . --strict' passes, and marketplace add -> install resolves all 21 promoted skills at v1.2.0. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
25 lines
3.2 KiB
Markdown
25 lines
3.2 KiB
Markdown
Skills are organized into bucket folders under `skills/`:
|
|
|
|
- `engineering/` — daily code work
|
|
- `productivity/` — daily non-code workflow tools
|
|
- `misc/` — kept around but rarely used, not promoted
|
|
- `personal/` — tied to my own setup, not promoted
|
|
- `in-progress/` — drafts not yet ready to ship
|
|
- `deprecated/` — no longer used
|
|
|
|
Every skill in `engineering/` or `productivity/` (the **promoted** buckets) must have a reference in the top-level `README.md` and an entry in `.claude-plugin/plugin.json`'s `skills` array (the Claude Code plugin ships exactly the promoted set). Skills in `misc/`, `personal/`, `in-progress/`, and `deprecated/` must not appear in either.
|
|
|
|
The repo is also its own single-plugin Claude Code marketplace: `.claude-plugin/marketplace.json` lists the one `mattpocock-skills` plugin. When bumping the release version, keep `.claude-plugin/plugin.json`'s `version` in sync with `package.json`'s — Claude uses the plugin `version` to decide when installed users see an update. Run `claude plugin validate . --strict` after touching either manifest. Why a Claude plugin but not (yet) a Codex one lives in [.agents/adr/0002-ship-as-a-claude-code-plugin.md](./.agents/adr/0002-ship-as-a-claude-code-plugin.md).
|
|
|
|
Each skill entry in the top-level `README.md` must link the skill name to its `SKILL.md`.
|
|
|
|
Each bucket folder has a `README.md` that lists every skill in the bucket with a one-line description, with the skill name linked to its `SKILL.md`. The promoted buckets' `README.md`s and the top-level `README.md` group entries into **User-invoked** and **Model-invoked**; non-promoted bucket `README.md`s (`misc/`, `personal/`) use a flat list.
|
|
|
|
Skills in `engineering/` and `productivity/` also have a human-facing docs page at `docs/<bucket>/<skill-name>.md` (the docs tree mirrors those two bucket folders under `skills/`). The published URL is `https://aihero.dev/skills-<skill-name>` regardless of bucket — the docs path is repo organisation only. When you add, rename, or change the behaviour of a skill in `engineering/` or `productivity/`, create or re-sync its docs page following [.agents/writing-docs.md](./.agents/writing-docs.md). Skills in the non-promoted buckets (`misc/`, `personal/`, `in-progress/`, `deprecated/`) get **no** docs page.
|
|
|
|
Every `SKILL.md` is either user-invoked (`disable-model-invocation: true`, reachable only by the human) or model-invoked (model- or user-reachable). See [.agents/invocation.md](./.agents/invocation.md).
|
|
|
|
[`ask-matt`](./skills/engineering/ask-matt/SKILL.md) is the router that maps every user-reachable skill and how they relate. The same trigger that re-syncs a docs page applies to it: whenever you add, rename, remove, or change how a user-reachable skill fits the flows, re-read `ask-matt`'s `SKILL.md` and update it so the map stays accurate — a new skill it never mentions, or a stale one it still routes to, is a router that lies.
|
|
|
|
To (re)link every skill 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.
|