diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 59cbd8bd..08f86c28 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -22,6 +22,8 @@ Skills are Markdown-only — no Python, no `uv`, no test infrastructure required
 5. Open a PR. CI validates frontmatter, MCP tool names, and `pipefy` CLI
    subcommands referenced in each `SKILL.md`.
 
+> **Try your skill in Claude Code before opening the PR.** Point the plugin marketplace at your local clone so your branch loads live — see [Test the Claude Code plugin from a local checkout](README.md#test-the-claude-code-plugin-from-a-local-checkout).
+
 ### Frontmatter requirements
 
 Every `SKILL.md` must have valid YAML frontmatter with:
diff --git a/README.md b/README.md
index 20a5604f..3e48aa1f 100644
--- a/README.md
+++ b/README.md
@@ -219,6 +219,19 @@ npx @modelcontextprotocol/inspector uv --directory . run pipefy-mcp-server
 
 **Adding an MCP tool:** implement under `packages/mcp/src/pipefy_mcp/tools/`, register in `ToolRegistry`, add the name to `PIPEFY_TOOL_NAMES`, and ship the matching CLI command (or document a deferral in `docs/parity.md`). See [`AGENTS.md`](AGENTS.md) for the full TDD workflow.
 
+### Test the Claude Code plugin from a local checkout
+
+The [Claude Code install](#claude-code) adds the marketplace from the `pipefy/ai-toolkit` GitHub repo, which tracks `main`. To run **your local branch** (e.g. `dev`) as the plugin instead, point the marketplace at your clone:
+
+```text
+/plugin marketplace add /absolute/path/to/ai-toolkit
+/plugin install pipefy@pipefy
+```
+
+Whatever is checked out in that clone — any branch — is what loads. Use the `plugin@marketplace` form (`pipefy@pipefy`) since the marketplace and the plugin share the name `pipefy`. After editing plugin files (skills, commands), run `/reload-plugins` to pick up changes without restarting.
+
+> **Already installed the GitHub version?** A marketplace named `pipefy` can be registered only once, and a marketplace declared in `~/.claude/settings.json` under `extraKnownMarketplaces` is locked — `/plugin marketplace add` becomes a no-op (`already on disk — declared in user settings`) and keeps pointing at GitHub. Run `/plugin marketplace remove pipefy` first (or delete that `extraKnownMarketplaces` entry), **then** add the local path.
+
 ---
 
 ## Contributing
diff --git a/commands/pipefy-login.md b/commands/pipefy-login.md
index 95c90df1..7be22259 100644
--- a/commands/pipefy-login.md
+++ b/commands/pipefy-login.md
@@ -13,4 +13,4 @@ Otherwise prompt the user to confirm running:
 pipefy auth login $ARGUMENTS
 ```
 
-Requires `PIPEFY_AUTH_URL` set in the shell environment (the OIDC issuer URL).
+This targets Pipefy production by default. Only set `PIPEFY_AUTH_URL` (the OIDC issuer URL) in the shell environment when logging in to a non-prod IdP; it defaults to `https://signin.pipefy.com/realms/pipefy`.