docs: add skill registration and cache invalidation workflow

README.md

@@ -35,20 +35,6 @@ claude plugin uninstall <plugin>@numencore-toolkit
 
 ## Development
 
-After editing skills in the source directory, reinstall the plugin to update the cache:
-
-```bash
-claude plugin install <plugin>@numencore-toolkit
-```
-
-In an active session, run `/reload-plugins` to pick up changes.
-
-For faster iteration, bypass the cache entirely:
-
-```bash
-claude --plugin-dir ~/numencore-toolkit/plugins/<plugin-name>
-```
-
 ### Structure
 
 ```
@@ -57,13 +43,57 @@ plugins/<plugin-name>/
 └── skills/<skill-name>/SKILL.md
 ```
 
+### Cache and skill registration
+
+Claude Code caches plugin contents at install time under `~/.claude/plugins/cache/`. The harness loads skills from the cache at startup, not from the source directory. This means:
+
+- **Adding or editing a skill requires re-caching.** The source files on disk are not read at runtime.
+- **`claude plugin update` compares version strings**, not file contents. If `plugin.json` still has the same version, `update` reports "already at latest" and the cache stays stale.
+
+To refresh the cache after adding or changing skills:
+
+```bash
+# Option A: bump version in plugin.json, then update
+claude plugin update <plugin>@numencore-toolkit
+
+# Option B: force re-cache via reinstall (no version bump needed)
+claude plugin uninstall <plugin>@numencore-toolkit
+claude plugin install <plugin>@numencore-toolkit
+```
+
+After re-caching, **restart Claude Code** — the harness loads skills at startup.
+
+For faster iteration during development, bypass the cache entirely:
+
+```bash
+claude --plugin-dir ~/numencore-toolkit/plugins/<plugin-name>
+```
+
+### Permissions whitelist
+
+Each skill needs a permission entry in `.claude/settings.local.json` to run without manual approval:
+
+```
+"Skill(<plugin-name>:<skill-name>)"
+```
+
+Add this when creating a new skill.
+
+### Adding a new skill to an existing plugin
+
+1. Create `plugins/<plugin>/skills/<skill-name>/SKILL.md`
+2. Add `Skill(<plugin>:<skill-name>)` to `.claude/settings.local.json`
+3. Re-cache: `claude plugin uninstall <plugin>@numencore-toolkit && claude plugin install <plugin>@numencore-toolkit`
+4. Restart Claude Code
+
 ### Adding a new plugin
 
 1. Create `plugins/<name>/.claude-plugin/plugin.json`
 2. Add skills under `plugins/<name>/skills/<skill-name>/SKILL.md`
 3. Register in `.claude-plugin/marketplace.json`
-4. Run `claude plugin marketplace update numencore-toolkit`
+4. Add `Skill(<name>:<skill-name>)` entries to `.claude/settings.local.json`
-5. Run `claude plugin install <name>@numencore-toolkit`
+5. Run `claude plugin marketplace update numencore-toolkit`
+6. Run `claude plugin install <name>@numencore-toolkit`
 
 ## Plugins