feat: consolidate marketplace skills into kyberforge plugin
Moves create-plugin, marketplace-architect, write-skill, and write-eval from canonical .agents/skills/ into plugins/kyberforge/skills/, along with all bundled sub-files, evals, and the plugin-marketplace-architecture research doc. Bundles templates/plugin/ into create-plugin/assets/plugin-template/ so the skill is self-contained after install-time caching. Removes templates/plugin/ and docs/research/plugin-marketplace-architecture.md from the repo root as they are now exclusively in the plugin. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,169 @@
|
||||
# Claude Code Plugin Reference
|
||||
|
||||
Verified against code.claude.com/docs as of June 2026.
|
||||
|
||||
---
|
||||
|
||||
## Directory structure
|
||||
|
||||
```text
|
||||
plugin-root/
|
||||
├── .claude-plugin/
|
||||
│ └── plugin.json # ONLY plugin.json goes here; all other dirs at plugin root
|
||||
├── skills/ # skill directories: <name>/SKILL.md
|
||||
├── commands/ # legacy flat .md files; promote to skills/ for new plugins
|
||||
├── agents/ # agent definitions: <name>.md
|
||||
├── hooks/
|
||||
│ └── hooks.json
|
||||
├── .mcp.json
|
||||
├── .lsp.json
|
||||
├── monitors/
|
||||
│ └── monitors.json
|
||||
├── bin/ # executables added to PATH while plugin is enabled
|
||||
└── settings.json # default settings applied when plugin is enabled
|
||||
```
|
||||
|
||||
A plugin that ships exactly one skill may place `SKILL.md` directly at the plugin root.
|
||||
Use `skills/` for plugins that may grow beyond one skill.
|
||||
|
||||
---
|
||||
|
||||
## plugin.json schema
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin", // kebab-case, no spaces — also the skill namespace prefix
|
||||
"displayName": "My Plugin", // human-readable; shown in UI (v2.1.143+)
|
||||
"description": "What it does",
|
||||
"version": "1.0.0", // OPTIONAL — omit to use git SHA per commit
|
||||
"author": { "name": "Name", "url": "https://..." },
|
||||
"homepage": "https://...",
|
||||
"repository": "https://github.com/...",
|
||||
"license": "MIT",
|
||||
"keywords": [],
|
||||
"defaultEnabled": true, // set false to install disabled (v2.1.154+)
|
||||
"dependencies": [
|
||||
{ "name": "other-plugin", "version": "~2.1.0" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Only `name` is required. Add fields only when needed.
|
||||
|
||||
---
|
||||
|
||||
## marketplace.json schema
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-ai-marketplace",
|
||||
"owner": { "name": "Your Name", "email": "you@example.com" },
|
||||
"description": "Description",
|
||||
"version": "1.0.0",
|
||||
"plugins": [
|
||||
{
|
||||
"name": "startup-cto",
|
||||
"source": "./plugins/startup-cto",
|
||||
"description": "...",
|
||||
"strict": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`description` and `version` are also accepted under a `metadata` key for backward compatibility.
|
||||
|
||||
---
|
||||
|
||||
## Plugin source types
|
||||
|
||||
| Type | Format | Notes |
|
||||
|---|---|---|
|
||||
| Relative path | `"./plugins/my-plugin"` | Must start with `./`. Resolved from marketplace root. Only works with git-hosted marketplaces, not URL-based. |
|
||||
| GitHub | `{ "source": "github", "repo": "owner/repo", "ref": "main", "sha": "abc123" }` | sha pins exact commit; ref is branch/tag |
|
||||
| URL / git | `{ "source": "url", "url": "https://...", "ref": "main" }` | also accepts `owner/repo` shorthand and SSH URLs |
|
||||
| git-subdir | `{ "source": "git-subdir", "url": "...", "path": "packages/my-plugin" }` | sparse clone of a monorepo path |
|
||||
| npm | `{ "source": "npm", "package": "@scope/pkg", "version": "^2.0.0", "registry": "https://..." }` | installed via npm install |
|
||||
|
||||
When both `ref` and `sha` are set, `sha` is the effective pin.
|
||||
|
||||
---
|
||||
|
||||
## Strict mode
|
||||
|
||||
Controls whether `plugin.json` is the authority for component definitions.
|
||||
|
||||
- **`strict: true`** (default) — plugin has its own `plugin.json`; marketplace entry can add extra skills/hooks on top.
|
||||
- **`strict: false`** — marketplace entry is the entire definition; plugin needs no `plugin.json`. The entry declares `skills`, `agents`, `hooks`, `mcpServers` path arrays.
|
||||
|
||||
Do not use `strict: false` plus a component-declaring `plugin.json` — this is a conflict and fails to load.
|
||||
|
||||
---
|
||||
|
||||
## Reserved marketplace names
|
||||
|
||||
These names are blocked for third-party use:
|
||||
`claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`,
|
||||
`claude-plugins-community`, `claude-community`, `anthropic-marketplace`,
|
||||
`anthropic-plugins`, `agent-skills`, `anthropic-agent-skills`,
|
||||
`knowledge-work-plugins`, `life-sciences`, `claude-for-legal`,
|
||||
`claude-for-financial-services`, `financial-services-plugins`
|
||||
|
||||
Names that impersonate official marketplaces are also blocked (e.g. `official-claude-plugins`,
|
||||
`anthropic-tools-v2`).
|
||||
|
||||
Plugin names must be kebab-case (lowercase, digits, hyphens). Claude.ai marketplace sync
|
||||
rejects anything else even if the local CLI tolerates it.
|
||||
|
||||
---
|
||||
|
||||
## Version management
|
||||
|
||||
- If `version` is set in `plugin.json`, users receive updates only when you bump it.
|
||||
- If `version` is omitted, git commit SHA is used — every commit is a new version.
|
||||
- If `version` is set in both `plugin.json` and the marketplace entry, `plugin.json` wins silently.
|
||||
- **Recommendation:** omit `version` unless you need explicit release gates.
|
||||
|
||||
---
|
||||
|
||||
## Environment variables
|
||||
|
||||
- **`${CLAUDE_PLUGIN_ROOT}`** — absolute path to the plugin's installation directory. Use in hook commands and MCP/LSP configs for all in-plugin file references. This path changes on update.
|
||||
- **`${CLAUDE_PLUGIN_DATA}`** — persistent directory for plugin state that survives updates. Use for `node_modules`, generated code, caches.
|
||||
|
||||
---
|
||||
|
||||
## Validation and CLI commands
|
||||
|
||||
```bash
|
||||
# Validate plugin structure and manifest
|
||||
claude plugin validate ./my-plugin
|
||||
claude plugin validate ./my-plugin --strict # treat warnings as errors
|
||||
|
||||
# Install/manage
|
||||
claude plugin install <name>@<marketplace>
|
||||
claude plugin update <name>@<marketplace>
|
||||
claude plugin uninstall <name>
|
||||
claude plugin list
|
||||
claude plugin enable <name>
|
||||
claude plugin disable <name>
|
||||
|
||||
# Marketplace
|
||||
claude plugin marketplace add owner/repo
|
||||
claude plugin marketplace update
|
||||
|
||||
# Development
|
||||
claude --plugin-dir ./my-plugin # load without installing
|
||||
claude --plugin-dir ./my-plugin.zip # load from zip (v2.1.128+)
|
||||
claude plugin init my-tool # scaffold a skills-dir plugin
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key gotchas
|
||||
|
||||
1. **Plugins are copied to cache on install.** Cannot reference `../shared-utils` — those files are not copied. Duplicate shared files into each plugin or use symlinks.
|
||||
2. **`commands/` ≠ `skills/`.** Flat `foo.md` is a legacy command; `foo/SKILL.md` is a skill. Promote flat commands to skill directories during migration.
|
||||
3. **Only `plugin.json` in `.claude-plugin/`.** Skills, agents, hooks, and other directories must be at the plugin root, not inside `.claude-plugin/`.
|
||||
4. **Plugin names are skill namespace prefixes.** `name: my-plugin` means skills invoke as `/my-plugin:skill-name`.
|
||||
5. **`defaultEnabled: false` requires v2.1.154+.** Earlier versions ignore it and enable on install.
|
||||
Reference in New Issue
Block a user