From 8f93352982f57229925b9fc696d76cd0d26f46c4 Mon Sep 17 00:00:00 2001 From: Jamie McGregor Nelson Date: Sun, 15 Mar 2026 09:51:47 -0400 Subject: [PATCH] docs(claude-import): add user-facing marketplace import guide --- .../gsd/docs/claude-marketplace-import.md | 225 ++++++++++++++++++ .../gsd/docs/preferences-reference.md | 1 + 2 files changed, 226 insertions(+) create mode 100644 src/resources/extensions/gsd/docs/claude-marketplace-import.md diff --git a/src/resources/extensions/gsd/docs/claude-marketplace-import.md b/src/resources/extensions/gsd/docs/claude-marketplace-import.md new file mode 100644 index 000000000..74d8b28b4 --- /dev/null +++ b/src/resources/extensions/gsd/docs/claude-marketplace-import.md @@ -0,0 +1,225 @@ +# Claude Marketplace Import + +This document explains how GSD imports Claude Code marketplaces and plugins, how that maps to Anthropic's documented plugin model, and what gets persisted into GSD/Pi settings. + +--- + +## Overview + +Claude Code plugins are distributed through **marketplaces**. Per Anthropic's docs, users add a marketplace source with: + +```text +/plugin marketplace add +``` + +A marketplace contains a catalog at: + +```text +.claude-plugin/marketplace.json +``` + +That catalog lists one or more plugins and where each plugin should be fetched from. + +GSD's Claude import flow reads those marketplace catalogs, inspects the referenced plugins, and imports the parts that map cleanly into GSD/Pi today. + +--- + +## Claude Code model vs GSD model + +### Claude Code concepts + +Anthropic distinguishes between: + +- **Marketplace source** — where Claude fetches `marketplace.json` +- **Plugin source** — where Claude fetches each plugin listed in that marketplace +- **Installed plugin cache** — Claude copies installed plugin payloads into: + +```text +~/.claude/plugins/cache +``` + +Claude also stores user-added marketplace sources under: + +```text +~/.claude/plugins/marketplaces +``` + +### GSD import model + +GSD treats Claude marketplaces as **plugin catalogs**, not generic npm-style packages. + +For imported Claude components, GSD preserves canonical namespaced identity: + +- skills: `plugin-name:skill-name` +- agents: `plugin-name:agent-name` + +This avoids flattening Claude plugin components into anonymous global names. + +--- + +## Discovery order + +When GSD looks for Claude plugin/marketplace material, it prefers Claude-managed locations first: + +1. `~/.claude/plugins/marketplaces` +2. `~/.claude/plugins/cache` +3. `~/.claude/plugins` + +After that, GSD may still look at local clone-style convenience paths such as sibling repos or `~/repos/...` locations. Those are useful for developer workflows and examples, but they are **not** the primary Claude storage model. + +--- + +## What the import flow does + +The interactive entry point is: + +```text +/gsd prefs import-claude +``` + +You can also choose scope explicitly: + +```text +/gsd prefs import-claude global +/gsd prefs import-claude project +``` + +The flow is: + +1. discover Claude skills and/or marketplace roots +2. identify marketplace roots by checking for `.claude-plugin/marketplace.json` +3. inspect discovered plugins and inventory components +4. let you select components to import +5. validate for canonical conflicts and shorthand ambiguity +6. persist imported resources into GSD/Pi settings + +--- + +## What gets imported today + +### Imported + +- **Skills** + - persisted into GSD/Pi skill paths + - available for use in GSD/Pi +- **Marketplace-derived skills** + - imported with canonical plugin namespace preserved +- **Marketplace-derived agents** + - discovered, modeled, validated, and preserved in the import manifest + +### Discovered but not fully imported into Pi-native runtime behavior + +- hooks +- MCP server definitions +- LSP server definitions +- other Claude plugin metadata that does not directly map to current GSD/Pi runtime surfaces + +These are still important for truthful discovery, but not all of them are currently translated into active Pi runtime behavior. + +--- + +## Important behavior: marketplace agents are not stored as package sources + +Claude plugin agent directories are usually markdown agent-definition directories, for example: + +```text +.../plugins/python3-development/agents +``` + +These are **not** loadable Pi extension packages. + +GSD therefore does **not** persist imported marketplace agent directories into: + +```json +settings.packages +``` + +This is intentional. + +### Why + +If an `.../agents` directory is written into `settings.packages`, Pi can treat it like an extension/package root during startup. That leads to extension loader failures such as: + +```text +Cannot find module '.../agents' +``` + +GSD now avoids writing those entries. + +--- + +## Settings effects + +### Skills + +Imported skills are persisted into Pi skill settings and may also be added to GSD preferences depending on what you choose during import. + +### Marketplace agents + +Marketplace agents are preserved in the import model and validated, but GSD does **not** persist their `agents/` directories as package sources. + +This prevents startup breakage and keeps the imported state aligned with Claude's plugin semantics. + +--- + +## Namespace behavior + +GSD preserves Claude plugin namespace semantics. + +### Canonical references + +Use canonical names when you need the authoritative unique reference: + +```text +python3-development:stinkysnake +scientific-method:experiment-protocol +``` + +### Shorthand + +GSD may allow shorthand when it is safe and unambiguous. + +### Local-first resolution + +If a namespaced component refers to another component by bare name, GSD tries the same plugin namespace first before broader lookup. + +--- + +## Diagnostics + +GSD distinguishes between: + +- **canonical conflicts** — hard errors +- **shorthand overlaps** — warnings when canonical names are still distinct +- **alias conflicts** — warnings/errors depending on the collision shape + +This keeps the operational surface honest without over-reporting valid marketplace content as broken. + +--- + +## Testing model + +GSD uses three levels of validation for this feature: + +1. **Contract/unit tests** for parsing, namespacing, resolution, diagnostics, and import behavior +2. **Portable integration-style tests** that can clone marketplace repos when local examples are absent +3. **Real host validation** against the installed `gsd` binary and actual Claude-managed directories on the host machine + +The test model is intentionally moving away from assumptions like `../claude_skills` always existing on the contributor's machine. + +--- + +## Current limitations + +- GSD does not yet fully translate every Claude plugin component type into active Pi runtime behavior +- marketplace-derived agents are not persisted as package roots, by design +- Claude-managed cache contents may be useful for discovery, but they should not be confused with generic package roots +- some test and discovery surfaces still carry developer-convenience fallback paths for local clone workflows + +--- + +## References + +- Anthropic: Claude Code settings +- Anthropic: Create and distribute a plugin marketplace +- Anthropic: Plugins and plugin reference diff --git a/src/resources/extensions/gsd/docs/preferences-reference.md b/src/resources/extensions/gsd/docs/preferences-reference.md index 9033bcb0f..d07db23b9 100644 --- a/src/resources/extensions/gsd/docs/preferences-reference.md +++ b/src/resources/extensions/gsd/docs/preferences-reference.md @@ -10,6 +10,7 @@ Full documentation for `~/.gsd/preferences.md` (global) and `.gsd/preferences.md - Prefer explicit skill names or absolute paths. - Use absolute paths for personal/local skills when you want zero ambiguity. - These preferences guide which skills GSD should load and follow; they do not override higher-priority instructions in the current conversation. +- For Claude marketplace/plugin import behavior, see `~/.gsd/agent/extensions/gsd/docs/claude-marketplace-import.md`. ---