Consuming Third-Party Marketplaces
Consuming Third-Party Marketplaces
Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.
AIWG can ingest plugins from any supported marketplace and deploy them across all configured providers. This document describes the design and implementation of the consumer side of the marketplace system.
Related issues: #787 (consumer side of #783), #2009 (Git-native exchange)
Status: The legacy source-adapter design below remains useful background. The implemented Git-native provenance, catalog, trust, offline exchange, and scope contract is documented in `git-native-marketplace.md`.
Concept
Today the agent-owned use operation deploys AIWG's own bundled frameworks. This extension makes AIWG a universal adapter: install a plugin from any marketplace, deploy it everywhere.
Use AIWG to complete this documented outcome: Today the agent-owned use operation <framework deploys AIWG's own bundled frameworks. This extension makes AIWG a universal adapter: install a plugin from any marketplace, deploy it everywhere.
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.Key property: AIWG already deploys to 11 providers. If it can also ingest from multiple marketplace sources, any compatible plugin from any supported marketplace becomes deployable everywhere — install once, deploy everywhere.
Supported Marketplace Sources
| Source | Identifier format | Install mechanism |
|---|---|---|
| ClawHub | `clawhub:<owner>/<package>` | ClawHub CLI or API |
| Cursor | `cursor:<publisher>.<package>` | cursor.com API (partner-only, local cache fallback) |
| Codex | `codex:<package>` | Read from `.agents/plugins/marketplace.json` |
| Claude Code | `claude:<user>/<repo>#<plugin>` | Git clone + `.claude-plugin/` |
| Git (generic) | `git:<url>` | Git clone + manifest detection |
Install + Deploy Flow
Use AIWG to complete this documented outcome: Install + Deploy Flow
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.Architecture
MarketplaceSource interface
Each source adapter implements a common interface:
interface MarketplaceSource {
/** Source identifier (e.g. 'clawhub', 'cursor', 'codex', 'claude', 'git') */
readonly source: string;
/** Fetch a package by identifier */
fetch(packageId: string, version?: string): Promise<PackageBundle>;
/** Search the marketplace */
search(query: string, options?: SearchOptions): Promise<PackageSummary[]>;
/** Validate a package manifest against the source's schema */
validate(manifest: unknown): ValidationResult;
/** List available versions of a package */
getVersions(packageId: string): Promise<string[]>;
}
interface PackageBundle {
/** Normalized AIWG-internal metadata */
metadata: {
name: string;
version: string;
namespace: string; // 'aiwg' or third-party
source: string; // marketplace source
description: string;
license: string;
};
/** Artifacts in AIWG-internal layout */
artifacts: {
agents?: string[]; // paths to agent files
commands?: string[];
skills?: string[];
rules?: string[];
behaviors?: string[];
};
/** Raw manifest from the source marketplace (for update detection) */
rawManifest: Record<string, unknown>;
}Source adapters
Implementation location: `src/marketplace/sources/<source>.ts`
| Source | Adapter file | Status |
|---|---|---|
| ClawHub | `src/marketplace/sources/clawhub.ts` | Scaffold (fetch + validate) |
| Cursor | `src/marketplace/sources/cursor.ts` | Scaffold (validate only — API submission partner-only) |
| Codex | `src/marketplace/sources/codex.ts` | Scaffold (read local marketplace.json) |
| Claude Code | `src/marketplace/sources/claude-code.ts` | Scaffold (git clone) |
| Git (generic) | `src/marketplace/sources/git.ts` | Scaffold (clone + manifest detection) |
Each adapter handles:
- Source-specific fetch (git clone, API call, local file read)
- Manifest parsing and normalization to AIWG's internal format
- Version resolution (SHA, semver, tag)
- Rate limiting / auth (if the source requires it)
Local cache
~/.aiwg/marketplace-cache/
├── clawhub/
│ └── aiwg/
│ └── sdlc/
│ ├── 2026.4.0/
│ │ ├── manifest.json # normalized AIWG manifest
│ │ ├── raw-manifest.json # original source manifest
│ │ ├── agents/
│ │ ├── commands/
│ │ └── skills/
│ └── 2026.3.0/ # older version
├── cursor/
│ └── some-publisher/
│ └── some-plugin/
│ └── 1.2.0/
├── codex/
├── claude/
└── git/Cache invalidation:
- Version-based: new version = new cache entry (old versions retained for rollback)
- Manual: the agent-owned cache operation removes a specific package
- Age-based: optional TTL via the agent-owned cache operation
Namespace isolation
Third-party plugins install under their own namespace, not `aiwg/`:
{baseDir}/{namespace}/{namespace}-{name}/SKILL.mdExamples:
- `.claude/skills/aiwg/aiwg-sdlc/SKILL.md` — AIWG-owned
- `.claude/skills/acme/acme-auth-toolkit/SKILL.md` — third-party
The collision detector (`src/smiths/skillsmith/collision-detector.js`) handles namespace isolation:
| Case | Severity | Behavior |
|---|---|---|
| AIWG file overwriting AIWG file | info | Overwrite silently |
| Third-party file overwriting AIWG file | warn | Prompt user before overwrite |
| Third-party file overwriting third-party file | warn | Prompt user before overwrite |
| First install (no existing file) | n/a | Install cleanly |
CLI Commands
| Command | Description |
|---|---|
| the agent-owned install operation | Fetch and cache a marketplace plugin |
| the agent-owned install operation | Fetch, cache, and deploy to all configured providers |
| the agent-owned install operation | Fetch, cache, and deploy to specific provider |
| the agent-owned uninstall operation | Remove cached plugin + deployed artifacts |
| the agent-owned marketplace operation | Search across all configured marketplaces |
| the agent-owned marketplace operation | List installed marketplace plugins |
| the agent-owned cache operation | List cached marketplace entries |
| the agent-owned cache operation | Clean cache |
Manifest Normalization
Each source has its own manifest format. The consumer normalizes to AIWG's internal format on ingest.
Normalization rules
| Source field | AIWG internal field | Notes |
|---|---|---|
| `name` (all sources) | `metadata.name` | Preserve dashes (e.g. `aiwg-sdlc`) |
| `version` | `metadata.version` | Use SemVer; convert non-semver to pre-release tags |
| `publisher` (Cursor) / `author` (others) | `metadata.publisher` | Normalized string |
| `contents` / `entry` / inferred | `artifacts.*` | Map to AIWG's agents/commands/skills/rules/behaviors |
| Plugin-specific fields | `metadata.sourceSpecific` | Preserved for update detection |
Validation
Each source adapter validates:
- Required fields present
- Version format (semver or source-specific)
- Namespace collision with `aiwg/` (third-party plugins cannot claim the `aiwg` namespace)
- File paths in manifest resolve to actual files in the package
Integration with the agent-owned use operation Pipeline
Marketplace plugins flow through the same smith pipeline as AIWG frameworks:
Use AIWG to complete this documented outcome: Marketplace plugins flow through the same smith pipeline as AIWG frameworks
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.This means marketplace plugins automatically benefit from AIWG's multi-provider deployment — install once from any marketplace, get deployment to all 11 providers.
Implementation Status
This is a design document + scaffold. The full implementation involves:
Phase 1 (scaffold — this commit)
- [x] Design document (this file)
- [x] Interface definitions
- [x] Source adapter skeletons
- [ ] CLI command registration
Phase 2 (MVP)
- [ ] ClawHub source adapter (full fetch + validate)
- [ ] Git source adapter (clone + manifest detection)
- [ ] the agent-owned install operation command
- [ ] the agent-owned uninstall operation command
- [ ] Local cache management
- [ ] Collision detector integration
Phase 3 (expanded coverage)
- [ ] Codex source adapter (read local marketplace.json)
- [ ] Claude Code source adapter (git clone)
- [ ] Cursor source adapter (validate-only, no API)
- [ ] the agent-owned marketplace operation across all sources
Phase 4 (polish)
- [ ] Auto-update via `FORCE_AUTOUPDATE_PLUGINS` equivalent
- [ ] Version pinning and rollback
- [ ] Package signing / verification
- [ ] Marketplace ranking / trust scoring
Open Design Questions
1. Cross-source namespace conflicts: If a ClawHub plugin named `foo/bar` and a Cursor plugin named `foo.bar` are both installed, how do we resolve namespace conflicts? Proposal: source prefix in the namespace — `clawhub/foo-bar` vs `cursor/foo-bar`.
2. Dependency chains: A marketplace plugin might depend on another marketplace plugin. Do we resolve transitive dependencies automatically, or require explicit install? Proposal: explicit for MVP; automatic resolution in later phase.
3. Update policy: Auto-update on the agent-owned refresh operation or explicit the agent-owned update operation? Proposal: explicit for MVP; auto-update as opt-in via config flag.
4. Signing: Marketplace plugins could be signed to prevent supply chain attacks. MVP: no signing, rely on source reputation. Later: GPG signature verification.
Related
- #783 — Producer side (publishing AIWG to marketplaces)
- #787 — This issue (consumer side)
- ADR-016 — Claude Code plugin distribution architecture
- `docs/providers/marketplace.md` — Producer-side marketplace reference
- `src/smiths/skillsmith/collision-detector.js` — Existing collision detection