diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 15ef978..8f7cce2 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -1,6 +1,6 @@
 {
   "name": "samarth",
-  "description": "Samarth Rayar's Claude Code plugins, mods and skills",
+  "description": "Samarth Rayar's Claude Code plugins: mods, skills, subagents, hooks and MCP servers",
   "owner": { "name": "Samarth Rayar", "url": "https://github.com/Samarth2001" },
   "plugins": [
     {
diff --git a/.claude/skills/new-plugin/SKILL.md b/.claude/skills/new-plugin/SKILL.md
new file mode 100644
index 0000000..496bbe2
--- /dev/null
+++ b/.claude/skills/new-plugin/SKILL.md
@@ -0,0 +1,13 @@
+---
+name: new-plugin
+description: Scaffold a new plugin in this marketplace. Use when asked to add, create or start a new plugin, skill bundle, mod, subagent, hook or MCP server in this repo.
+argument-hint: "<name> [what it should do]"
+---
+
+Create a new plugin from: $ARGUMENTS
+
+1. Pick a kebab-case name and the components it needs (`skill`, `agent`, `hooks`, `mcp`, `mod`). Read `docs/plugin-anatomy.md` to choose. If the name or purpose is unclear, ask.
+2. Run `node --experimental-strip-types scripts/new-plugin.mts <name> --with <components> --description "<one line>"`.
+3. Fill in every TODO in `plugins/<name>/`. For a skill, follow `docs/writing-skills.md`. For a mod, load the `plugin-authoring` skill first.
+4. Write the plugin README: what it adds, usage with an example, configuration, and what code it runs.
+5. Run `claude plugin validate plugins/<name>`, `claude plugin test plugins/<name>` for a mod, `claude plugin validate .` and `node --experimental-strip-types scripts/catalog.mts --check`. Fix anything they report.
diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md
new file mode 100644
index 0000000..74da7df
--- /dev/null
+++ b/.claude/skills/release/SKILL.md
@@ -0,0 +1,14 @@
+---
+name: release
+description: Release a new version of a plugin in this marketplace.
+disable-model-invocation: true
+argument-hint: "<plugin> [patch|minor|major]"
+---
+
+Release plugin: $ARGUMENTS
+
+1. Read `plugins/<name>/CHANGELOG.md` and run `git log <name>--v<current-version>..HEAD -- plugins/<name>`. If that tag doesn't exist, use the full log for the folder. Then list what changed.
+2. Choose the bump if none was given: patch for fixes, minor for features, major for breaking changes such as renamed commands or settings. Confirm it with me.
+3. Set `version` in `plugins/<name>/.claude-plugin/plugin.json`. Add a `## [<version>] - <today>` section to the CHANGELOG under Added, Changed or Fixed, plus its compare link at the bottom.
+4. Run `claude plugin validate .`, `claude plugin validate plugins/<name>`, `claude plugin test plugins/<name>` if it has tests, and `node --experimental-strip-types scripts/catalog.mts --check`.
+5. Commit as `<name>: release <version>`. Then stop and show me the commands to push and tag: `git push` and `claude plugin tag plugins/<name> --push`.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 0000000..d90d1e4
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,9 @@
+## What changed
+
+## Plugins touched
+
+- [ ] Version bumped in `plugin.json` and a CHANGELOG section added for each plugin whose shipped files changed
+- [ ] The plugin's README is updated for anything users see
+- [ ] `claude plugin validate .` and `claude plugin validate plugins/<name>` pass
+- [ ] `claude plugin test plugins/<name>` passes (mods)
+- [ ] `node --experimental-strip-types scripts/catalog.mts --check` passes
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index c5c6c6a..4deb8f6 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -26,6 +26,11 @@ jobs:
           manifest="plugins/$name/.claude-plugin/plugin.json"
           changelog="plugins/$name/CHANGELOG.md"
 
+          if [ ! -f "$manifest" ]; then
+            echo "::error::$TAG names no plugin: $manifest does not exist"
+            exit 1
+          fi
+
           actual=$(sed -n 's/.*"version": *"\([^"]*\)".*/\1/p' "$manifest" | head -1)
           if [ "$actual" != "$version" ]; then
             echo "::error::$TAG does not match $manifest ($actual)"
@@ -40,6 +45,7 @@ jobs:
             on { print }
           ' "$changelog" > notes.md
           [ -s notes.md ] || echo "See $changelog." > notes.md
-          printf '\nInstall or update:\n\n```bash\nclaude plugin marketplace add %s\nclaude plugin install %s@samarth\n```\n' "$GITHUB_REPOSITORY" "$name" >> notes.md
+          marketplace=$(jq -r .name .claude-plugin/marketplace.json)
+          printf '\nInstall or update:\n\n```bash\nclaude plugin marketplace add %s\nclaude plugin install %s@%s\n```\n' "$GITHUB_REPOSITORY" "$name" "$marketplace" >> notes.md
 
           gh release create "$TAG" --title "$name $version" --notes-file notes.md --verify-tag
diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
index 277319d..03e9ee1 100644
--- a/.github/workflows/validate.yml
+++ b/.github/workflows/validate.yml
@@ -33,8 +33,15 @@ jobs:
             fi
             echo "::endgroup::"
           done
+      - name: Catalog is consistent
+        run: node --experimental-strip-types scripts/catalog.mts --check
       - name: Generated assets are up to date
-        run: node --experimental-strip-types scripts/render-buddy-gallery.mts --check
+        run: |
+          set -e
+          for script in scripts/assets/*.mts; do
+            [ -e "$script" ] || continue
+            node --experimental-strip-types "$script" --check
+          done
       - name: Changed plugins bumped their version
         run: |
           if [ "${{ github.event_name }}" = "pull_request" ]; then
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..e15c7cb
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,19 @@
+# claude-plugins
+
+A Claude Code plugin marketplace (`samarth`). Each plugin lives in `plugins/<name>/`. Read CONTRIBUTING.md before changing structure or releasing.
+
+## Rules
+
+- Keep the root README neutral. Never feature one plugin there. Its catalog table is generated: edit `.claude-plugin/marketplace.json`, then run `node --experimental-strip-types scripts/catalog.mts`.
+- Keep each plugin self-contained, in Claude Code's standard layout, with its own README.md and CHANGELOG.md. Dev-only tooling goes in `scripts/`, never inside a plugin.
+- Never rename a plugin's `name`. Leave `version` out of marketplace entries.
+- Any change to a plugin's shipped files needs a version bump and a CHANGELOG section. README, CHANGELOG, `assets/` and tests are exempt.
+- Before reporting work done, run `claude plugin validate .`, `claude plugin validate plugins/<name>`, `claude plugin test plugins/<name>` (if it has tests) and `node --experimental-strip-types scripts/catalog.mts --check`.
+- Before writing a mod, load the `plugin-authoring` skill.
+- Guides in `docs/` summarize the official docs at code.claude.com. Link to the source and don't state behavior you haven't checked.
+
+## Commands
+
+- New plugin: `node --experimental-strip-types scripts/new-plugin.mts <name> --with skill,agent,hooks,mcp,mod --description "..."`
+- Regenerate assets: `node --experimental-strip-types scripts/assets/<script>.mts`
+- Release: `/release <name>` (bump, changelog, tag)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0ea8fe2..690bea7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,49 +1,60 @@
 # Working on this repo
 
-Every plugin lives in `plugins/<name>/`, has an entry in `.claude-plugin/marketplace.json` and a row in the README table. CI validates and tests every plugin on each push and pull request.
+Every plugin lives in `plugins/<name>/` and has an entry in `.claude-plugin/marketplace.json`. The README catalog is generated from those entries. On each push and pull request, CI validates the marketplace and every plugin, runs the tests, and checks that the catalog, generated assets and versions are up to date.
+
+## Conventions
+
+- **One plugin per folder, self-contained.** Everything a plugin needs lives under `plugins/<name>/`. Installed plugins are copied into a cache, so a plugin can't reach files outside its folder. Refer to bundled files with `${CLAUDE_PLUGIN_ROOT}`. Keep state that must survive updates in `${CLAUDE_PLUGIN_DATA}`.
+- **Standard layout.** Put components in Claude Code's default locations (`skills/`, `agents/`, `hooks/hooks.json`, `.mcp.json`, and so on) rather than custom paths. Only `plugin.json` goes in `.claude-plugin/`. See [docs/plugin-anatomy.md](docs/plugin-anatomy.md).
+- **Every plugin has a README and a CHANGELOG.** The README covers what it adds, how to use it, its configuration and how to develop it. The root README stays neutral: one generated catalog row per plugin, nothing more.
+- **Names.** Use kebab-case and keep `name` the same in the folder, `plugin.json` and the marketplace entry. Names that start with `claude-` or `anthropic-` are reserved.
+- **Marketplace entries** carry `name`, `source`, `description`, `category` and `tags`. Leave `version` out: `plugin.json` holds it. Suggested categories: `mods`, `skills`, `agents`, `hooks`, `mcp`, `output-styles`, `themes`, `bundles` (several kinds at once).
+- **No `CLAUDE.md` inside a plugin.** Claude Code doesn't load it from a plugin. Put instructions for Claude in a skill.
+- **Dev-only files stay outside plugins.** Asset generators and other tooling go in `scripts/`, because everything under `plugins/<name>/` ships to users.
 
 ## Add a plugin
 
-1. Create `plugins/<name>/` with at least `.claude-plugin/plugin.json`:
-
-   ```json
-   {
-     "name": "<name>",
-     "displayName": "<Name>",
-     "version": "0.1.0",
-     "description": "<one line>",
-     "author": { "name": "Samarth Rayar", "url": "https://github.com/Samarth2001" },
-     "homepage": "https://github.com/Samarth2001/claude-plugins/tree/main/plugins/<name>",
-     "repository": "https://github.com/Samarth2001/claude-plugins",
-     "license": "MIT",
-     "keywords": []
-   }
-   ```
+Scaffold it:
+
+```bash
+node --experimental-strip-types scripts/new-plugin.mts <name> --with skill --description "One line on what it does"
+```
 
-   - **A mod** adds `hooks/hooks.json` (`{ "modules": ["./register.tsx"] }`), `hooks/register.tsx` and `hooks/*.test.tsx`. If it keeps values in `$.state`, add `types/index.d.ts` and `"types": "./types/index.d.ts"` to the manifest. In a Claude Code session, load the `plugin-authoring` skill before writing one.
-   - **Skills** go in `skills/<skill>/SKILL.md`.
+`--with` takes a comma-separated list of `skill`, `agent`, `hooks`, `mcp` and `mod`. The script creates `plugins/<name>/` from [`templates/`](templates) with a manifest, a README, a CHANGELOG and the chosen components. It also adds the marketplace entry and regenerates the README catalog. Then fill in the TODOs.
 
-2. Add `README.md` and a `CHANGELOG.md` with a `0.1.0` section.
-3. Add the entry to `.claude-plugin/marketplace.json` (`name`, `source: "./plugins/<name>"`, `description`, `category`, `tags`). Keep `version` out of the entry: `plugin.json` holds it.
-4. Add a row to the table in the root `README.md`.
+- **Skills** live in `skills/<skill>/SKILL.md` and run as `/<plugin>:<skill>`. See [docs/writing-skills.md](docs/writing-skills.md).
+- **Subagents** live in `agents/<agent>.md`.
+- **Hooks** go in `hooks/hooks.json` under `"hooks"`, in the same shape as `settings.json` hooks. Reference scripts as `"${CLAUDE_PLUGIN_ROOT}"/scripts/...`.
+- **MCP servers** go in `.mcp.json`.
+- **A mod** puts `"modules": ["./register.ts"]` in `hooks/hooks.json`, with the hooks module and `*.test.ts` files beside it. If it keeps values in `$.state`, also add `types/index.d.ts` and `"types": "./types/index.d.ts"` to the manifest. In a Claude Code session, load the `plugin-authoring` skill before you write one.
+
+If you edit the marketplace by hand, run `node --experimental-strip-types scripts/catalog.mts` to regenerate the catalog and check that everything agrees.
 
 ## Try it
 
 ```bash
 claude plugin validate .                     # the marketplace
 claude plugin validate plugins/<name>        # the plugin
-claude plugin test plugins/<name>            # its tests
-claude --plugin-dir plugins/<name>           # a session with it loaded; saving reloads it
+claude plugin test plugins/<name>            # its tests (mods)
+claude --plugin-dir plugins/<name>           # a session with it loaded; mods hot-reload on save
 ```
 
-`claude --debug` shows why a hook was skipped or a drawing refused. Loading a plugin from disk writes its types to `plugins/<name>/.claude-plugin/types/` (gitignored), which the plugin's `tsconfig.json` extends, so an editor or `npx tsc -p plugins/<name>` type-checks it.
+`claude --debug` shows why a hook was skipped or a drawing refused. When Claude Code loads a mod from disk, it writes the mod's types to `plugins/<name>/.claude-plugin/types/` (gitignored). The mod's `tsconfig.json` extends them, so an editor or `npx tsc -p plugins/<name>` can type-check it.
+
+## Generated assets
+
+A script in `scripts/assets/` that renders a file into a plugin, such as a README image, must accept `--check`. With that flag it exits non-zero when the committed file is stale, and CI runs every such script that way. After changing what an asset is drawn from, run:
+
+```bash
+node --experimental-strip-types scripts/assets/<script>.mts
+```
 
 ## Release
 
-Users only receive a change when the plugin's `version` changes.
+Users only get a change when the plugin's `version` changes. CI fails when a plugin's shipped files change without a version bump. Docs, `assets/` and tests don't count as shipped files.
 
-1. Bump `version` in `plugins/<name>/.claude-plugin/plugin.json` ([semver](https://semver.org/): patch for fixes, minor for features, major for breaking changes such as renamed commands or settings).
-2. Move the changes into a new section of `plugins/<name>/CHANGELOG.md` and update the version in the README table.
+1. Bump `version` in `plugins/<name>/.claude-plugin/plugin.json` ([semver](https://semver.org/)): a patch for fixes, a minor for features, a major for breaking changes such as renamed commands or settings.
+2. Move the changes into a new `## [<version>] - <date>` section of `plugins/<name>/CHANGELOG.md`.
 3. Validate and test, then commit and push to `main`.
 4. Tag the release and push the tag:
 
@@ -51,7 +62,7 @@ Users only receive a change when the plugin's `version` changes.
    claude plugin tag plugins/<name> --push
    ```
 
-   This creates `<name>--v<version>`, after checking that `plugin.json` and the marketplace entry agree and that the tree is clean. The tag convention is what dependency version ranges resolve against. Pushing it runs the Release workflow, which publishes a GitHub release with that version's changelog section.
+   This creates `<name>--v<version>`. Before tagging, it checks that `plugin.json` and the marketplace entry agree and that the tree is clean. Dependency version ranges resolve against this tag convention. Pushing the tag runs the Release workflow, which publishes a GitHub release with that version's changelog section.
 
 5. Update your own install:
 
@@ -62,8 +73,8 @@ Users only receive a change when the plugin's `version` changes.
 
 ## Rename or remove a plugin
 
-Never change a plugin's `name`: it is the install id. Change `displayName` instead. If a rename or removal is unavoidable, record it in the `renames` map of `marketplace.json` (`"old": "new"` or `"old": null`), which is append-only history.
+Never change a plugin's `name`, because it is the install id. Change `displayName` instead. If a rename or removal can't be avoided, record it in the `renames` map of `marketplace.json` (`"old": "new"` or `"old": null`). That map is append-only history.
 
 ## Commits
 
-Commit as `Samarth Rayar <samarthsr2001@gmail.com>`. One change per commit, with the plugin name first in the subject (`buddy: ...`).
+Commit as `Samarth Rayar <samarthsr2001@gmail.com>`. Make one change per commit. Start the subject with the plugin name for plugin changes (`buddy: ...`) and describe the area for repo-wide changes (`Release workflow: ...`).
diff --git a/README.md b/README.md
index cc28fa3..4fc85a9 100644
--- a/README.md
+++ b/README.md
@@ -2,11 +2,9 @@
 
 [![Validate](https://github.com/Samarth2001/claude-plugins/actions/workflows/validate.yml/badge.svg)](https://github.com/Samarth2001/claude-plugins/actions/workflows/validate.yml)
 
-My Claude Code plugins, mods and skills in one place, published as a [plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces) so any of them installs with two commands.
+A collection of Claude Code extensions by Samarth Rayar: plugins, mods, skills, subagents, hooks and MCP servers, along with notes on building them well. The repo is a [plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces), so you can install each plugin on its own and keep it updated from Claude Code.
 
-![buddy](plugins/buddy/assets/moods.svg)
-
-## Install
+## Quick start
 
 Add the marketplace once:
 
@@ -14,53 +12,62 @@ Add the marketplace once:
 claude plugin marketplace add Samarth2001/claude-plugins
 ```
 
-Then install what you want, and run `/reload-plugins` in an open session (or start a new one):
+Browse it with `/plugin` in a session, or install a plugin by its id from the [catalog](#catalog):
 
 ```bash
-claude plugin install buddy@samarth
+claude plugin install <plugin>@samarth
 ```
 
-Updates arrive when a plugin's version changes. To get them automatically, open `/plugin`, go to **Marketplaces**, select `samarth` and choose **Enable auto-update**. Otherwise:
+Then run `/reload-plugins` in an open session, or start a new one. Inside a session, `/plugin marketplace add` and `/plugin install` do the same.
+
+Plugins update when their version changes. To update automatically, open `/plugin`, go to **Marketplaces**, select `samarth` and choose **Enable auto-update**. To update by hand:
 
 ```bash
 claude plugin marketplace update samarth
-claude plugin update buddy@samarth
+claude plugin update <plugin>@samarth
 ```
 
-In the Claude desktop app (Code tab, local sessions), installed plugins load too; manage them from **+** next to the prompt, then **Plugins**.
+Installed plugins also load in the Claude desktop app (Code tab, local sessions). Manage them from **+** next to the prompt, then **Plugins**.
 
-## Mods
+## Catalog
 
-Mods are plugins with function hooks that draw inside Claude Code. See [Getting started with Claude Code mods](https://claude.dev/blog/getting-started-with-claude-code-mods/).
+<!-- catalog:start -->
+| Plugin | Install id | Type | What it does |
+| --- | --- | --- | --- |
+| [Buddy](plugins/buddy) | `buddy` | mods | A pixel-art companion above the prompt that acts out what Claude is doing, with a sprout that wilts as context fills, a context sparkline, usage limits and cost |
+<!-- catalog:end -->
 
-| Plugin | Version | What it does |
-| --- | --- | --- |
-| [`buddy`](plugins/buddy) | 0.3.0 | A pixel-art companion above the prompt that acts out what Claude is doing, with a sprout that wilts as context fills, a context sparkline, usage limits and cost |
+Each plugin has its own README covering what it adds, how to use and configure it, and its changelog. This table is generated from [`marketplace.json`](.claude-plugin/marketplace.json) by `scripts/catalog.mts`.
 
-## Skills
+## Guides
 
-None yet.
+Notes on building Claude Code extensions, linked to the official docs:
 
-## Layout
+- [Plugin anatomy](docs/plugin-anatomy.md): what each component is, where its files go, and how to pick one
+- [Writing skills](docs/writing-skills.md): structure and habits for `SKILL.md` files that trigger reliably
+
+## Repository layout
 
 ```
 .claude-plugin/marketplace.json   the catalog: one entry per plugin
-plugins/<name>/                   one plugin per mod or skill bundle
-  .claude-plugin/plugin.json      its manifest (name, version, display fields)
-  hooks/                          mod code (hooks.json, register.tsx) and *.test.tsx
-  types/index.d.ts                the $.state contract of a mod
-  skills/<skill>/SKILL.md         skills, run as /<plugin>:<skill>
+plugins/<name>/                   one self-contained plugin per folder
+  .claude-plugin/plugin.json      its manifest: name, version, description
+  skills/ agents/ hooks/ ...      its components, in Claude Code's standard layout
+  README.md                       what it does and how to use it
   CHANGELOG.md                    one section per release
-  README.md
-scripts/                          repo tooling (asset generators)
-.github/workflows/                validate + test on every push, GitHub release per tag
+templates/                        starting files for new plugins
+scripts/                          scaffolding, catalog and release checks, asset generators
+docs/                             guides and best practices
+.github/workflows/                validate and test on every push; a GitHub release per tag
 ```
 
-## Develop and release
+## Contributing
+
+To start a new plugin, run `node --experimental-strip-types scripts/new-plugin.mts <name> --with skill`. [CONTRIBUTING.md](CONTRIBUTING.md) covers the conventions, local testing and releases.
 
-See [CONTRIBUTING.md](CONTRIBUTING.md): adding a plugin, trying it with hot reload, and the release steps (bump `version`, changelog, `claude plugin tag --push`).
+## Security
 
-Mods run as code inside Claude Code with the same access it has. Read a plugin's source before installing it.
+Plugins run inside Claude Code with your permissions. Hooks, mods and MCP servers execute code on your machine. Read a plugin's source before you install it.
 
 ## License
 
diff --git a/docs/plugin-anatomy.md b/docs/plugin-anatomy.md
new file mode 100644
index 0000000..5f26f3a
--- /dev/null
+++ b/docs/plugin-anatomy.md
@@ -0,0 +1,92 @@
+# Plugin anatomy
+
+A plugin is a folder that Claude Code loads components from. This page covers what each component does, where its files go, and the rules that keep a plugin loading for everyone who installs it. It summarizes the official [plugin manifest reference](https://code.claude.com/docs/en/plugins-reference) and [marketplace reference](https://code.claude.com/docs/en/plugins/marketplace-reference). When this page and those docs disagree, trust the docs.
+
+## Pick a component
+
+| You want Claude Code to | Use | Files |
+| --- | --- | --- |
+| Follow a procedure or know conventions when a task calls for it, or when you type `/plugin:skill` | Skill | `skills/<skill>/SKILL.md` |
+| Hand a focused task to a separate context with its own prompt and tools | Subagent | `agents/<agent>.md` |
+| Run a script at a fixed point, such as before a tool call, after an edit or at session start | Hooks | `hooks/hooks.json` |
+| Draw in the interface, add commands or tools, or change behavior with code | Mod | `hooks/hooks.json` (`modules`) and a hooks module |
+| Reach an external service or API as tools | MCP server | `.mcp.json` |
+| Get code intelligence for a language | LSP server | `.lsp.json` |
+| Change how Claude writes its answers | Output style | `output-styles/` |
+| Give Claude a command-line tool to run as a bare command | Executable | `bin/` |
+
+Skills replace the older `commands/` folder for new plugins. One plugin can mix components. A plugin that mixes several kinds goes in the `bundles` category.
+
+## Standard layout
+
+Only the manifest goes in `.claude-plugin/`. Everything else sits at the plugin root:
+
+```text
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json        manifest (name, version, description, ...)
+├── skills/
+│   └── <skill>/SKILL.md   one folder per skill, run as /my-plugin:<skill>
+├── agents/
+│   └── <agent>.md         subagents, named my-plugin:<agent>
+├── hooks/
+│   └── hooks.json         settings hooks under "hooks", and a mod's "modules"
+├── output-styles/         output style Markdown files
+├── bin/                   executables put on the Bash tool's PATH
+├── scripts/               scripts your hooks call
+├── settings.json          `agent` and `subagentStatusLine` defaults
+├── .mcp.json              MCP servers
+├── .lsp.json              LSP servers
+├── README.md
+└── CHANGELOG.md
+```
+
+Components in their default locations load without being listed in the manifest. List a path in `plugin.json` only to load something from somewhere else. For `commands`, `agents` and `outputStyles`, a manifest path replaces the default folder instead of adding to it.
+
+## The manifest
+
+`name` is the only required field, but every plugin here sets these:
+
+```json
+{
+  "name": "my-plugin",
+  "displayName": "My Plugin",
+  "version": "0.1.0",
+  "description": "One line on what it does",
+  "author": { "name": "Samarth Rayar", "url": "https://github.com/Samarth2001" },
+  "homepage": "https://github.com/Samarth2001/claude-plugins/tree/main/plugins/my-plugin",
+  "repository": "https://github.com/Samarth2001/claude-plugins",
+  "license": "MIT",
+  "keywords": []
+}
+```
+
+- **`name`** is the install id and the namespace for every component, so never change it after release. Use kebab-case. Names that start with `claude-`, `anthropic-` or `cc-plugin-` are reserved.
+- **`version`** pins users to that version until it changes. A change that doesn't bump it never reaches anyone who already installed the plugin.
+- **`userConfig`** declares values Claude Code asks the user for, such as an API endpoint or a token. Mark secrets `"sensitive": true` so they go to secure storage instead of `settings.json`.
+- **`dependencies`** lists other plugins that must be enabled for this one to work.
+
+## Paths and variables
+
+- Every path in the manifest is relative to the plugin root and starts with `./`. A path can't leave the plugin folder.
+- **`${CLAUDE_PLUGIN_ROOT}`** is the installed plugin's folder. Use it for bundled scripts and config. It changes on every update, so don't write state there.
+- **`${CLAUDE_PLUGIN_DATA}`** is a per-plugin folder that survives updates. Use it for caches, generated files and installed dependencies.
+- **`${CLAUDE_PROJECT_DIR}`** is the project root.
+- In shell-form hook commands, quote the variable so a path with spaces stays one word: `"\"${CLAUDE_PLUGIN_ROOT}\"/scripts/check.sh"`.
+
+## Rules of thumb
+
+- **Run `claude plugin validate` on every change.** It is the authoritative check for manifests, hooks files, MCP entries and mod modules. Add `--strict` to fail on warnings.
+- **Keep a plugin self-contained.** Users get a copy of the plugin folder, so it can't reach files outside it.
+- **Don't put a `CLAUDE.md` in a plugin.** It isn't loaded. Put instructions in a skill.
+- **Think twice about `bin/`.** claude.ai and Cowork don't install a plugin that has a top-level `bin/` folder.
+- **Say what a plugin runs.** Hooks, mods and MCP servers execute code with the user's permissions. Each plugin's README should say what runs and when.
+- **For mods, test the code and say which Claude Code version you tested with.** `claude plugin test` runs `*.test.ts` files without a session. The mods API can change between releases.
+
+## Further reading
+
+- [Create a plugin](https://code.claude.com/docs/en/plugins/create)
+- [Plugin components](https://code.claude.com/docs/en/plugins/components)
+- [Hooks reference](https://code.claude.com/docs/en/hooks)
+- [Mods: create](https://code.claude.com/docs/en/plugins/mods/create), [test](https://code.claude.com/docs/en/plugins/mods/test) and [reference](https://code.claude.com/docs/en/plugins/mods/reference)
+- [Host and maintain a marketplace](https://code.claude.com/docs/en/plugins/host-marketplace)
diff --git a/docs/writing-skills.md b/docs/writing-skills.md
new file mode 100644
index 0000000..d5fbd6e
--- /dev/null
+++ b/docs/writing-skills.md
@@ -0,0 +1,47 @@
+# Writing skills
+
+A skill is a `SKILL.md` file that Claude loads when a task matches its description, or when you type its command. In a plugin, `skills/<skill>/SKILL.md` runs as `/<plugin>:<skill>`. This page summarizes the official [skills docs](https://code.claude.com/docs/en/skills).
+
+## Shape
+
+```markdown
+---
+name: review-pr
+description: Review a pull request for correctness and style. Use when asked to review a PR, a diff or a branch.
+---
+
+1. Read the diff with `git diff main...HEAD`.
+2. ...
+```
+
+The frontmatter starts on the first line. If it doesn't parse, the whole file is treated as the skill body.
+
+## Frontmatter worth knowing
+
+| Field | Use it to |
+| --- | --- |
+| `description` | Say what the skill does and when to use it. Claude picks skills by this text, so include the words a user would actually say |
+| `disable-model-invocation: true` | Run the skill only when you type it, for anything with side effects such as a release or a deploy |
+| `user-invocable: false` | Hide it from the `/` menu when it's background knowledge for Claude only |
+| `allowed-tools` | Pre-approve tools for the turn the skill runs in, such as `Bash(git *)` |
+| `argument-hint`, `arguments` | Take arguments, used as `$ARGUMENTS`, `$0` or named `$name` |
+| `context: fork` with `agent` | Run in a separate subagent context that doesn't see the conversation |
+| `paths` | Limit when the skill applies, such as `"*.py"` |
+
+## Habits
+
+- **Keep `SKILL.md` under 500 lines.** Every line is loaded each time the skill runs. Move long reference material into files beside it and link them from `SKILL.md`, so Claude reads them only when needed.
+- **State what to do, not why.** Use short numbered steps for procedures and bullet rules for conventions.
+- **Put scripts in the skill folder** and reference them with `${CLAUDE_SKILL_DIR}` or `${CLAUDE_PLUGIN_ROOT}`, so they work wherever the plugin is installed.
+- **Inject live context with `` !`command` ``** when the skill needs fresh facts, such as the current diff. The output replaces the placeholder before Claude reads the skill.
+- **Test the trigger.** Ask for the task in plain words without naming the skill, and check that Claude picks it up. If it doesn't, rewrite the description.
+
+## Layout
+
+```text
+skills/review-pr/
+├── SKILL.md          overview and steps
+├── reference.md      details, read on demand
+└── scripts/
+    └── collect.sh    run, not read
+```
diff --git a/plugins/buddy/README.md b/plugins/buddy/README.md
index 6b57587..5196e18 100644
--- a/plugins/buddy/README.md
+++ b/plugins/buddy/README.md
@@ -78,7 +78,7 @@ From the repository root:
 claude plugin validate plugins/buddy
 claude plugin test plugins/buddy
 claude --plugin-dir plugins/buddy                              # try it, hot-reloads on save
-node --experimental-strip-types scripts/render-buddy-gallery.mts  # after changing the sprite
+node --experimental-strip-types scripts/assets/buddy-moods.mts   # after changing the sprite
 ```
 
 See [CHANGELOG.md](CHANGELOG.md) for releases.
diff --git a/scripts/render-buddy-gallery.mts b/scripts/assets/buddy-moods.mts
similarity index 82%
rename from scripts/render-buddy-gallery.mts
rename to scripts/assets/buddy-moods.mts
index 71dff81..bb15db0 100644
--- a/scripts/render-buddy-gallery.mts
+++ b/scripts/assets/buddy-moods.mts
@@ -1,15 +1,15 @@
 // Renders plugins/buddy/assets/moods.svg, the animated mood gallery in buddy's
 // README, from the same sprite code the mod draws with.
 //
-//   node --experimental-strip-types scripts/render-buddy-gallery.mts
-//   node --experimental-strip-types scripts/render-buddy-gallery.mts --check   (CI: fail if stale)
+//   node --experimental-strip-types scripts/assets/buddy-moods.mts
+//   node --experimental-strip-types scripts/assets/buddy-moods.mts --check   (CI: fail if stale)
 
 import { readFileSync, writeFileSync } from 'node:fs'
 
-import { animation, svg } from '../plugins/buddy/hooks/sprite.ts'
-import type { Mood } from '../plugins/buddy/types/index.d.ts'
+import { animation, svg } from '../../plugins/buddy/hooks/sprite.ts'
+import type { Mood } from '../../plugins/buddy/types/index.d.ts'
 
-const OUT = new URL('../plugins/buddy/assets/moods.svg', import.meta.url)
+const OUT = new URL('../../plugins/buddy/assets/moods.svg', import.meta.url)
 
 const CELLS: { mood: Mood; percent: number; label: string }[] = [
   { mood: 'idle', percent: 20, label: 'ready' },
@@ -50,7 +50,7 @@ const gallery =
 if (process.argv.includes('--check')) {
   const current = readFileSync(OUT, 'utf8')
   if (current !== gallery) {
-    console.error('plugins/buddy/assets/moods.svg is stale: run node --experimental-strip-types scripts/render-buddy-gallery.mts')
+    console.error('plugins/buddy/assets/moods.svg is stale: run node --experimental-strip-types scripts/assets/buddy-moods.mts')
     process.exit(1)
   }
   console.log('moods.svg is up to date')
diff --git a/scripts/catalog.mts b/scripts/catalog.mts
new file mode 100644
index 0000000..9e2ad85
--- /dev/null
+++ b/scripts/catalog.mts
@@ -0,0 +1,26 @@
+// Checks that every plugin folder, marketplace entry, manifest and changelog
+// agree, and regenerates the catalog table in the root README from the
+// marketplace.
+//
+//   node --experimental-strip-types scripts/catalog.mts           write the table
+//   node --experimental-strip-types scripts/catalog.mts --check   CI: fail on drift
+
+import { MARKETPLACE, catalogErrors, isReadmeCurrent, readJson, updateReadme } from './lib.mts'
+import type { Marketplace } from './lib.mts'
+
+const marketplace = readJson<Marketplace>(MARKETPLACE)
+const errors = catalogErrors(marketplace)
+for (const error of errors) console.error(`::error::${error}`)
+
+if (process.argv.includes('--check')) {
+  if (!isReadmeCurrent(marketplace)) {
+    console.error('::error::The README catalog is stale: run node --experimental-strip-types scripts/catalog.mts')
+    process.exit(1)
+  }
+  if (errors.length > 0) process.exit(1)
+  console.log(`catalog is consistent: ${marketplace.plugins.length} plugin(s)`)
+} else {
+  updateReadme(marketplace)
+  console.log('updated the README catalog')
+  if (errors.length > 0) process.exit(1)
+}
diff --git a/scripts/check-version-bumps.sh b/scripts/check-version-bumps.sh
index d616a40..48e29d7 100644
--- a/scripts/check-version-bumps.sh
+++ b/scripts/check-version-bumps.sh
@@ -4,14 +4,16 @@
 #
 #   scripts/check-version-bumps.sh <base-ref> [head-ref]
 #
-# Docs, assets and tests don't count as shipped changes.
+# A plugin's README, CHANGELOG, assets and tests don't count as shipped
+# changes. Skills and agents are Markdown too, so other .md files do.
 set -euo pipefail
 
 base="${1:?usage: check-version-bumps.sh <base-ref> [head-ref]}"
 head="${2:-HEAD}"
 
+# Empty when the manifest doesn't exist at that commit (a new plugin).
 version_at() {
-  git show "$1:$2" 2>/dev/null | sed -n 's/.*"version": *"\([^"]*\)".*/\1/p' | head -1
+  { git show "$1:$2" 2>/dev/null || true; } | sed -n 's/.*"version": *"\([^"]*\)".*/\1/p' | head -1
 }
 
 status=0
@@ -21,7 +23,7 @@ for dir in $(git diff --name-only "$base" "$head" -- plugins | cut -d/ -f1-2 | s
   [ -n "$(git ls-tree "$head" -- "$manifest")" ] || continue # removed plugin
 
   shipped=$(git diff --name-only "$base" "$head" -- "$dir" |
-    grep -vE '\.md$|/assets/|\.test\.(ts|tsx)$' || true)
+    grep -vE "^$dir/(README|CHANGELOG)\.md$|/assets/|\.test\.(ts|tsx)$" || true)
   [ -n "$shipped" ] || continue
 
   before=$(version_at "$base" "$manifest")
diff --git a/scripts/lib.mts b/scripts/lib.mts
new file mode 100644
index 0000000..c5039f9
--- /dev/null
+++ b/scripts/lib.mts
@@ -0,0 +1,137 @@
+// Shared helpers for the repo scripts: reading and writing the marketplace,
+// and the catalog checks and README table that CI keeps in sync with it.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+
+export const ROOT = new URL('../', import.meta.url)
+export const MARKETPLACE = '.claude-plugin/marketplace.json'
+const README = 'README.md'
+const START = '<!-- catalog:start -->'
+const END = '<!-- catalog:end -->'
+
+export type Entry = {
+  name: string
+  source: string | { source: string }
+  description?: string
+  displayName?: string
+  category?: string
+  tags?: string[]
+  version?: string
+}
+export type Marketplace = { name: string; owner: { name: string; url?: string }; plugins: Entry[] }
+export type Manifest = { name: string; displayName?: string; version?: string; description?: string }
+
+export const path = (p: string) => new URL(p, ROOT)
+export const exists = (p: string) => existsSync(path(p))
+export const read = (p: string) => readFileSync(path(p), 'utf8')
+export function write(p: string, text: string): void {
+  mkdirSync(new URL('./', path(p)), { recursive: true })
+  writeFileSync(path(p), text)
+}
+export const readJson = <T,>(p: string): T => JSON.parse(read(p))
+export const writeJson = (p: string, value: unknown) => write(p, formatJson(value) + '\n')
+
+// JSON.stringify with two-space indents, except that an array or object that
+// fits on one line and holds no nested array or object stays on one line, the
+// way the manifests in this repo are written by hand.
+export function formatJson(value: unknown, indent = ''): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value)
+  const isArray = Array.isArray(value)
+  const items = isArray
+    ? (value as unknown[]).map(v => [undefined, v] as const)
+    : Object.entries(value as Record<string, unknown>)
+  const [open, close] = isArray ? ['[', ']'] : ['{', '}']
+  if (items.length === 0) return open + close
+  const key = (k: string | undefined) => (k === undefined ? '' : `${JSON.stringify(k)}: `)
+  const isFlat = items.every(([, v]) => v === null || typeof v !== 'object')
+  if (isFlat) {
+    const inner = items.map(([k, v]) => key(k) + JSON.stringify(v)).join(', ')
+    const line = isArray ? `[${inner}]` : `{ ${inner} }`
+    if (indent.length + line.length <= 100) return line
+  }
+  const next = indent + '  '
+  const lines = items.map(([k, v]) => next + key(k) + formatJson(v, next))
+  return `${open}\n${lines.join(',\n')}\n${indent}${close}`
+}
+
+export const pluginDirs = () =>
+  readdirSync(path('plugins/'), { withFileTypes: true })
+    .filter(d => d.isDirectory())
+    .map(d => d.name)
+    .sort()
+
+// Every way the catalog can drift: a plugin folder without an entry, an entry
+// without a folder, mismatched names, or a release without its changelog.
+export function catalogErrors(marketplace: Marketplace): string[] {
+  const errors: string[] = []
+  const dirs = new Set(pluginDirs())
+  const listed = new Set<string>()
+
+  for (const entry of marketplace.plugins) {
+    const { name } = entry
+    if (typeof entry.source !== 'string') continue // hosted elsewhere
+    listed.add(name)
+    const dir = `plugins/${name}`
+    if (entry.source !== `./${dir}`) errors.push(`${name}: source should be "./${dir}", not "${entry.source}"`)
+    if (!dirs.has(name)) {
+      errors.push(`${name}: listed in ${MARKETPLACE} but ${dir}/ does not exist`)
+      continue
+    }
+    if (entry.version !== undefined) errors.push(`${name}: remove "version" from the marketplace entry; plugin.json holds it`)
+    if (!entry.description) errors.push(`${name}: the marketplace entry needs a "description"`)
+    if (!entry.category) errors.push(`${name}: the marketplace entry needs a "category"`)
+
+    const manifestPath = `${dir}/.claude-plugin/plugin.json`
+    if (!exists(manifestPath)) {
+      errors.push(`${name}: ${manifestPath} is missing`)
+      continue
+    }
+    const manifest = readJson<Manifest>(manifestPath)
+    if (manifest.name !== name) errors.push(`${name}: plugin.json name is "${manifest.name}"; it must match the entry and folder`)
+    if (!manifest.version) errors.push(`${name}: plugin.json needs a "version"`)
+    if (!exists(`${dir}/README.md`)) errors.push(`${name}: ${dir}/README.md is missing`)
+    if (!exists(`${dir}/CHANGELOG.md`)) {
+      errors.push(`${name}: ${dir}/CHANGELOG.md is missing`)
+    } else if (manifest.version && !read(`${dir}/CHANGELOG.md`).includes(`## [${manifest.version}]`)) {
+      errors.push(`${name}: ${dir}/CHANGELOG.md has no "## [${manifest.version}]" section`)
+    }
+  }
+
+  for (const dir of dirs) {
+    if (!listed.has(dir)) errors.push(`plugins/${dir}/ has no entry in ${MARKETPLACE}`)
+  }
+  return errors
+}
+
+const cell = (text: string) => text.replace(/\|/g, '\\|').replace(/\s*\n\s*/g, ' ')
+
+export function catalogTable(marketplace: Marketplace): string {
+  if (marketplace.plugins.length === 0) return 'Nothing published yet.'
+  const rows = marketplace.plugins.map(entry => {
+    const local = typeof entry.source === 'string'
+    const manifestPath = `plugins/${entry.name}/.claude-plugin/plugin.json`
+    const manifest = local && exists(manifestPath) ? readJson<Manifest>(manifestPath) : undefined
+    const title = entry.displayName ?? manifest?.displayName ?? entry.name
+    const link = local ? `[${title}](plugins/${entry.name})` : title
+    const description = entry.description ?? manifest?.description ?? ''
+    return `| ${link} | \`${entry.name}\` | ${entry.category ?? ''} | ${cell(description)} |`
+  })
+  return ['| Plugin | Install id | Type | What it does |', '| --- | --- | --- | --- |', ...rows].join('\n')
+}
+
+// The README with its catalog table replaced, or null when it has no markers.
+export function renderReadme(marketplace: Marketplace): string | null {
+  const readme = read(README)
+  const start = readme.indexOf(START)
+  const end = readme.indexOf(END)
+  if (start === -1 || end < start) return null
+  return `${readme.slice(0, start + START.length)}\n${catalogTable(marketplace)}\n${readme.slice(end)}`
+}
+
+export function updateReadme(marketplace: Marketplace): void {
+  const next = renderReadme(marketplace)
+  if (next === null) throw new Error(`${README} has no ${START} ... ${END} markers`)
+  write(README, next)
+}
+
+export const isReadmeCurrent = (marketplace: Marketplace) => renderReadme(marketplace) === read(README)
diff --git a/scripts/new-plugin.mts b/scripts/new-plugin.mts
new file mode 100644
index 0000000..99ea751
--- /dev/null
+++ b/scripts/new-plugin.mts
@@ -0,0 +1,113 @@
+// Scaffolds plugins/<name>/ from templates/, adds its marketplace entry and
+// regenerates the README catalog.
+//
+//   node --experimental-strip-types scripts/new-plugin.mts <name> [options]
+//
+//   --with <list>          components, comma separated: skill, agent, hooks, mcp, mod (default: skill)
+//   --description <text>   one line for the manifest, the marketplace and the README
+//   --category <text>      catalog type (default: from the first component)
+//   --display-name <text>  name shown in the UI (default: <name> in title case)
+
+import { parseArgs } from 'node:util'
+
+import { MARKETPLACE, exists, read, readJson, updateReadme, write, writeJson } from './lib.mts'
+import type { Marketplace } from './lib.mts'
+
+const COMPONENTS = {
+  skill: { category: 'skills', line: (n: string) => `- Skill \`/${n}:${n}\`: TODO` },
+  agent: { category: 'agents', line: (n: string) => `- Subagent \`${n}:${n}\`: TODO` },
+  hooks: { category: 'hooks', line: () => '- Hooks in `hooks/hooks.json`: TODO' },
+  mcp: { category: 'mcp', line: () => '- MCP servers in `.mcp.json`: TODO' },
+  mod: { category: 'mods', line: (n: string) => `- A mod with the command \`/${n}\`: TODO` },
+} as const
+type Component = keyof typeof COMPONENTS
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    with: { type: 'string', default: 'skill' },
+    description: { type: 'string', default: 'TODO: one line on what it does' },
+    category: { type: 'string' },
+    'display-name': { type: 'string' },
+  },
+})
+
+function fail(message: string): never {
+  console.error(message)
+  process.exit(1)
+}
+
+const name = positionals[0] ?? fail('usage: scripts/new-plugin.mts <name> [--with skill,agent,hooks,mcp,mod] [--description ...]')
+if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(name)) fail(`"${name}" is not kebab-case`)
+// claude plugin validate refuses names that pass as Anthropic's own.
+if (/^(claude|anthropics?|cc-plugin)(-|$)/.test(name) || name === 'claude-code') fail(`"${name}" is reserved by Claude Code`)
+
+const dir = `plugins/${name}`
+if (exists(dir)) fail(`${dir}/ already exists`)
+
+const components = values.with.split(',').map(c => c.trim()).filter(Boolean)
+for (const c of components) if (!(c in COMPONENTS)) fail(`unknown component "${c}"; use ${Object.keys(COMPONENTS).join(', ')}`)
+const chosen = components as Component[]
+if (chosen.length === 0) fail('--with needs at least one component')
+
+const marketplace = readJson<Marketplace>(MARKETPLACE)
+if (marketplace.plugins.some(p => p.name === name)) fail(`${name} is already in ${MARKETPLACE}`)
+
+const displayName = values['display-name'] ?? name.split('-').map(w => w[0].toUpperCase() + w.slice(1)).join(' ')
+const description = values.description.replace(/\.$/, '')
+const category = values.category ?? COMPONENTS[chosen[0]].category
+const repo = 'https://github.com/Samarth2001/claude-plugins'
+
+const vars: Record<string, string> = {
+  name,
+  displayName,
+  description,
+  date: new Date().toISOString().slice(0, 10),
+  components: chosen.map(c => COMPONENTS[c].line(name)).join('\n'),
+}
+const fill = (text: string) => text.replace(/\{\{(\w+)\}\}/g, (_, key: string) => vars[key] ?? fail(`no value for {{${key}}}`))
+
+const emit = (from: string, to: string) => write(`${dir}/${to}`, fill(read(`templates/${from}`)))
+
+const manifest: Record<string, unknown> = {
+  name,
+  displayName,
+  version: '0.1.0',
+  description,
+  author: marketplace.owner,
+  homepage: `${repo}/tree/main/${dir}`,
+  repository: repo,
+  license: 'MIT',
+  keywords: [],
+}
+
+emit('plugin/README.md', 'README.md')
+emit('plugin/CHANGELOG.md', 'CHANGELOG.md')
+if (chosen.includes('skill')) emit('skill/SKILL.md', `skills/${name}/SKILL.md`)
+if (chosen.includes('agent')) emit('agent/agent.md', `agents/${name}.md`)
+if (chosen.includes('mcp')) writeJson(`${dir}/.mcp.json`, { mcpServers: {} })
+if (chosen.includes('mod')) {
+  emit('mod/register.ts', 'hooks/register.ts')
+  emit('mod/register.test.ts', 'hooks/register.test.ts')
+  write(`${dir}/tsconfig.json`, '{ "extends": "./.claude-plugin/types/tsconfig.json" }\n')
+}
+// A mod and settings hooks share hooks/hooks.json: `modules` for the mod,
+// `hooks` for the event map.
+if (chosen.includes('mod') || chosen.includes('hooks')) {
+  const hooks: Record<string, unknown> = {}
+  if (chosen.includes('mod')) hooks.modules = ['./register.ts']
+  if (chosen.includes('hooks')) hooks.hooks = {}
+  writeJson(`${dir}/hooks/hooks.json`, hooks)
+}
+writeJson(`${dir}/.claude-plugin/plugin.json`, manifest)
+
+marketplace.plugins.push({ name, source: `./${dir}`, description, category, tags: [...chosen] })
+writeJson(MARKETPLACE, marketplace)
+updateReadme(marketplace)
+
+console.log(`Created ${dir}/ (${chosen.join(', ')}), added it to ${MARKETPLACE} and the README catalog.
+
+Next:
+  1. Fill in the TODOs: grep -rn TODO ${dir}
+  2. claude plugin validate ${dir}${chosen.includes('mod') ? `\n     claude plugin test ${dir}` : ''}
+  3. claude --plugin-dir ${dir}`)
diff --git a/templates/agent/agent.md b/templates/agent/agent.md
new file mode 100644
index 0000000..d25d8fb
--- /dev/null
+++ b/templates/agent/agent.md
@@ -0,0 +1,11 @@
+---
+name: {{name}}
+description: {{description}}. Use when TODO.
+---
+
+You are TODO. When invoked:
+
+1. TODO
+2. TODO
+
+Report back with TODO.
diff --git a/templates/mod/register.test.ts b/templates/mod/register.test.ts
new file mode 100644
index 0000000..9526ae3
--- /dev/null
+++ b/templates/mod/register.test.ts
@@ -0,0 +1,6 @@
+import { expect, test } from 'claude-code/testing'
+
+test('/{{name}} answers', async $ => {
+  const answer = await $.command.run({ command: '{{name}}', args: '' })
+  expect(answer.text).toBe('Hello from {{name}}')
+})
diff --git a/templates/mod/register.ts b/templates/mod/register.ts
new file mode 100644
index 0000000..964ef24
--- /dev/null
+++ b/templates/mod/register.ts
@@ -0,0 +1,12 @@
+import type { Register } from 'claude-code'
+
+export const register: Register = on => {
+  on('session.start', async ($, e, next) => {
+    await $.command.register({ name: '{{name}}', description: '{{description}}' })
+    return next(e)
+  })
+
+  on('command.run', { command: '{{name}}' }, async () => {
+    return { text: 'Hello from {{name}}' }
+  })
+}
diff --git a/templates/plugin/CHANGELOG.md b/templates/plugin/CHANGELOG.md
new file mode 100644
index 0000000..2e3b6c8
--- /dev/null
+++ b/templates/plugin/CHANGELOG.md
@@ -0,0 +1,9 @@
+# Changelog
+
+All notable changes to {{name}}. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and versions follow [Semantic Versioning](https://semver.org/). Each release is tagged `{{name}}--v<version>`.
+
+## [0.1.0] - {{date}}
+
+### Added
+
+- First release.
diff --git a/templates/plugin/README.md b/templates/plugin/README.md
new file mode 100644
index 0000000..d3cce20
--- /dev/null
+++ b/templates/plugin/README.md
@@ -0,0 +1,35 @@
+# {{displayName}}
+
+{{description}}
+
+## Install
+
+```bash
+claude plugin marketplace add Samarth2001/claude-plugins
+claude plugin install {{name}}@samarth
+```
+
+Then run `/reload-plugins` in an open session, or start a new one.
+
+## What it adds
+
+{{components}}
+
+## Usage
+
+TODO: how to use it, with an example.
+
+## Configuration
+
+None.
+
+## Develop
+
+From the repository root:
+
+```bash
+claude plugin validate plugins/{{name}}
+claude --plugin-dir plugins/{{name}}     # a session with it loaded
+```
+
+See [CHANGELOG.md](CHANGELOG.md) for releases.
diff --git a/templates/skill/SKILL.md b/templates/skill/SKILL.md
new file mode 100644
index 0000000..1a3b5de
--- /dev/null
+++ b/templates/skill/SKILL.md
@@ -0,0 +1,9 @@
+---
+name: {{name}}
+description: {{description}}. Use when TODO (the words a user would say).
+---
+
+# {{displayName}}
+
+TODO: what Claude should do, as short numbered steps or rules. State what to do, not why.
+Keep this file under 500 lines; move long reference material into files beside it and link them.