diff --git a/README.md b/README.md
index dfdea03..1dc4a69 100644
--- a/README.md
+++ b/README.md
@@ -151,8 +151,9 @@ cargo build --release            # ~4 MB stripped binary at target/release/fj
 plugin so AI agents and developers using Claude Code can drive fj
 directly from natural-language requests.
 
-```sh
-/plugin install rasterandstate/fj-claude-plugin
+```text
+/plugin marketplace add rasterandstate/fj-claude-plugin
+/plugin install fj@rasterandstate
 ```
 
 The source of truth for the plugin lives in [`claude/`](claude/) inside
diff --git a/claude/.claude-plugin/marketplace.json b/claude/.claude-plugin/marketplace.json
new file mode 100644
index 0000000..aec64c2
--- /dev/null
+++ b/claude/.claude-plugin/marketplace.json
@@ -0,0 +1,16 @@
+{
+  "name": "rasterandstate",
+  "owner": {
+    "name": "Raster & State",
+    "email": "hello@rasterstate.com",
+    "url": "https://rasterstate.com"
+  },
+  "plugins": [
+    {
+      "name": "fj",
+      "source": ".",
+      "description": "Teach Claude Code to use fj, a CLI for Forgejo and Gitea-compatible instances. Activates when the user mentions fj, Forgejo, Gitea, or any forge-side action (issues, PRs, releases, code search, labels, milestones, webhooks).",
+      "keywords": ["fj", "forgejo", "gitea", "git", "cli"]
+    }
+  ]
+}
diff --git a/claude/README.md b/claude/README.md
index 85f71af..68b2405 100644
--- a/claude/README.md
+++ b/claude/README.md
@@ -10,16 +10,12 @@ issues, cut a release, request a review, etc.) on a non-GitHub host.
 
 ## Install
 
-This directory is itself a complete Claude Code plugin. Two ways to
-install:
+This directory is both a Claude Code plugin AND a single-plugin
+marketplace. Add the marketplace once, then install:
 
-```sh
-# From a local clone of the upstream fj repo:
-/plugin install /path/to/fj/claude
-
-# From the canonical mirror repo (preferred for users who aren't
-# already cloning fj for development):
-/plugin install rasterandstate/fj-claude-plugin
+```text
+/plugin marketplace add rasterandstate/fj-claude-plugin
+/plugin install fj@rasterandstate
 ```
 
 After install, the skill activates automatically when relevant.
@@ -29,11 +25,13 @@ After install, the skill activates automatically when relevant.
 ```
 claude/
 ├── .claude-plugin/
-│   └── plugin.json       plugin manifest (name, version, keywords)
-├── README.md             this file
+│   ├── plugin.json         plugin manifest (name, version, keywords)
+│   └── marketplace.json    makes this directory a single-plugin
+│                           marketplace; required for `/plugin install`
+├── README.md               this file
 └── skills/
     └── fj/
-        └── SKILL.md      the skill body — what Claude reads
+        └── SKILL.md        the skill body — what Claude reads
 ```
 
 ## Updating