diff --git a/plugins/.claude-plugin/README.md b/plugins/.claude-plugin/README.md
index 0a173c49..8aca646c 100644
--- a/plugins/.claude-plugin/README.md
+++ b/plugins/.claude-plugin/README.md
@@ -10,6 +10,27 @@ This README is for community users who want to install or reuse the plugin packa
 - Cursor
 - Codex
 
+## Prerequisites
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/Hawksight-AI/semantica.git
+cd semantica
+```
+
+2. Ensure the plugin bundle exists at:
+
+```text
+plugins/
+  skills/
+  agents/
+  hooks/
+  .claude-plugin/
+  .cursor-plugin/
+  .codex-plugin/
+```
+
 ## Plugin Contents
 
 - `skills/`: 17 domain skills (`causal`, `decision`, `explain`, `reason`, `temporal`, etc.)
@@ -20,7 +41,9 @@ This README is for community users who want to install or reuse the plugin packa
 - `.codex-plugin/plugin.json`: Codex manifest
 - `*/marketplace.json`: local marketplace definitions
 
-## Use In Claude Code
+## Install and Use in Claude Code
+
+### Local install (fastest)
 
 From the repository root:
 
@@ -28,19 +51,38 @@ From the repository root:
 claude --plugin-dir ./plugins
 ```
 
-Or add a marketplace hosted in a git repo:
+If your Claude setup uses plugin commands in-session, use:
+
+```bash
+/plugin install ./plugins
+```
+
+### Install from a GitHub marketplace
+
+Add a marketplace hosted in git:
 
 ```bash
 /plugin marketplace add <owner>/semantica
 ```
 
-Then install the plugin from that marketplace:
+Install Semantica from that marketplace:
 
 ```bash
 /plugin install semantica@<marketplace-name>
 ```
 
-## Use In Codex
+### Verify in Claude
+
+Run one of these in chat:
+
+```text
+/semantica:decision list
+/semantica:explain decision <decision_id>
+```
+
+If the plugin is installed correctly, Claude should recognize the `/semantica:*` skills.
+
+## Install and Use in Codex
 
 1. Ensure your repo marketplace exists at `.agents/plugins/marketplace.json`.
 2. Point the plugin entry `source.path` to `./plugins` (or your chosen plugin directory).
@@ -50,7 +92,15 @@ Codex manifest used by this bundle:
 
 - `.codex-plugin/plugin.json`
 
-## Use In Cursor
+### Verify in Codex
+
+After install, run a Semantica skill command in chat, for example:
+
+```text
+/semantica:causal chain --subject <decision_id> --depth 3
+```
+
+## Install and Use in Cursor
 
 Cursor reads plugin metadata from:
 
@@ -59,6 +109,25 @@ Cursor reads plugin metadata from:
 
 If you maintain a team/community plugin repo, publish this `plugins/` directory and refresh/reinstall in Cursor Marketplace to pick up updates.
 
+### Verify in Cursor
+
+Try one of these commands:
+
+```text
+/semantica:reason deductive "IF Person(x) THEN Mortal(x)"
+/semantica:visualize topology
+```
+
+## First Commands to Try
+
+After installing on any platform, these are good smoke tests:
+
+1. `/semantica:decision record <category> "<scenario>" "<reasoning>" <outcome> <confidence>`
+2. `/semantica:decision list`
+3. `/semantica:causal chain --subject <decision_id> --depth 3`
+4. `/semantica:explain decision <decision_id>`
+5. `/semantica:validate graph`
+
 ## Community Notes
 
 - Keep plugin name/version/keywords updated in each manifest before publishing.