From 5ab70549762392e2c37565d7e554e9e3154a8c9d Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Sat, 20 Jun 2026 13:41:00 +0000 Subject: [PATCH] feat: expand hello-world into a complete cross-compat plugin scaffold Adds every cross-compatible component between Claude Code and Copilot CLI: skills (shared), agents (per-tool .md vs .agent.md), hooks (per-tool paths), and .mcp.json (shared). Both plugin.json manifests now carry all shared identity fields (name, description, author, license, keywords) with Copilot-specific component paths only in the root manifest. Updates validate.sh sync check to verify shared identity fields rather than demanding content equality, since component path declarations legitimately diverge between tools. Co-Authored-By: Claude Sonnet 4.6 --- .../marketplace-architect/scripts/validate.sh | 21 +++++- .../hello-world/.claude-plugin/plugin.json | 7 +- plugins/hello-world/.mcp.json | 9 +++ plugins/hello-world/README.md | 66 +++++++++++++++---- .../hello-world/agents/hello-world.agent.md | 13 ++++ plugins/hello-world/agents/hello-world.md | 10 +++ plugins/hello-world/hooks.json | 8 +++ plugins/hello-world/hooks/hooks.json | 15 +++++ plugins/hello-world/plugin.json | 9 ++- 9 files changed, 142 insertions(+), 16 deletions(-) create mode 100644 plugins/hello-world/.mcp.json create mode 100644 plugins/hello-world/agents/hello-world.agent.md create mode 100644 plugins/hello-world/agents/hello-world.md create mode 100644 plugins/hello-world/hooks.json create mode 100644 plugins/hello-world/hooks/hooks.json diff --git a/.agents/skills/marketplace-architect/scripts/validate.sh b/.agents/skills/marketplace-architect/scripts/validate.sh index b844dff..83595f4 100755 --- a/.agents/skills/marketplace-architect/scripts/validate.sh +++ b/.agents/skills/marketplace-architect/scripts/validate.sh @@ -147,10 +147,25 @@ validate_plugin_dir() { validate_plugin_json "$claude_manifest" "$marketplace_json" validate_plugin_json "$root_manifest" "$marketplace_json" - # Sync check + # Sync check — shared identity fields must match; component path fields legitimately diverge if [[ -f "$claude_manifest" && -f "$root_manifest" ]]; then - if ! diff <(jq -S . "$claude_manifest") <(jq -S . "$root_manifest") >/dev/null 2>&1; then - warn "$pd: .claude-plugin/plugin.json and plugin.json differ — keep them in sync" + local field cv rv + for field in name description version license; do + cv=$(jq -r ".$field // empty" "$claude_manifest") + rv=$(jq -r ".$field // empty" "$root_manifest") + if [[ ( -n "$cv" || -n "$rv" ) && "$cv" != "$rv" ]]; then + error "$pd: '$field' differs between .claude-plugin/plugin.json ('$cv') and plugin.json ('$rv')" + fi + done + cv=$(jq -r '.author.name // empty' "$claude_manifest") + rv=$(jq -r '.author.name // empty' "$root_manifest") + if [[ ( -n "$cv" || -n "$rv" ) && "$cv" != "$rv" ]]; then + error "$pd: 'author.name' differs between .claude-plugin/plugin.json ('$cv') and plugin.json ('$rv')" + fi + cv=$(jq -r '.keywords // [] | sort | join(",")' "$claude_manifest") + rv=$(jq -r '.keywords // [] | sort | join(",")' "$root_manifest") + if [[ "$cv" != "$rv" ]]; then + error "$pd: 'keywords' differs between .claude-plugin/plugin.json and plugin.json" fi fi fi diff --git a/plugins/hello-world/.claude-plugin/plugin.json b/plugins/hello-world/.claude-plugin/plugin.json index b99fbe8..33e1b5a 100644 --- a/plugins/hello-world/.claude-plugin/plugin.json +++ b/plugins/hello-world/.claude-plugin/plugin.json @@ -1,4 +1,9 @@ { "name": "hello-world", - "description": "A minimal example plugin to validate marketplace scaffolding." + "displayName": "Hello World", + "description": "A complete scaffold demonstrating every cross-compatible plugin feature for the holocron marketplace.", + "author": { "name": "Your Name", "url": "https://github.com/your-org/ai-development" }, + "homepage": "https://github.com/your-org/ai-development", + "license": "MIT", + "keywords": ["scaffold", "example", "holocron"] } diff --git a/plugins/hello-world/.mcp.json b/plugins/hello-world/.mcp.json new file mode 100644 index 0000000..3b65e41 --- /dev/null +++ b/plugins/hello-world/.mcp.json @@ -0,0 +1,9 @@ +{ + "mcpServers": { + "hello-world": { + "type": "stdio", + "command": "node", + "args": ["${CLAUDE_PLUGIN_ROOT}/bin/mcp-server.js"] + } + } +} diff --git a/plugins/hello-world/README.md b/plugins/hello-world/README.md index c743288..2bc2ac4 100644 --- a/plugins/hello-world/README.md +++ b/plugins/hello-world/README.md @@ -1,33 +1,77 @@ # hello-world -Minimal proof-of-concept plugin for the `holocron` marketplace. Install it to confirm the marketplace scaffolding works, then replace it with real plugins. +Complete scaffold plugin for the **holocron** marketplace. Every cross-compatible component +is included with a working stub. Copy this directory, rename it, and replace the stubs with +your actual content. + +## Directory layout + +``` +hello-world/ +├── plugin.json # Copilot CLI manifest — declares component paths +├── .claude-plugin/ +│ └── plugin.json # Claude Code manifest — no component paths (uses defaults) +├── skills/ +│ └── hello-world/ +│ └── SKILL.md # ✅ identical for both tools +├── agents/ +│ ├── hello-world.md # Claude Code agent (no frontmatter) +│ └── hello-world.agent.md # Copilot CLI agent (YAML frontmatter + tools:) +├── hooks/ +│ └── hooks.json # Claude Code hooks (PostToolUse / PreToolUse events) +├── hooks.json # Copilot CLI hooks (session_start / session_end events) +├── .mcp.json # ✅ MCP server config — identical for both tools +└── README.md +``` + +## Cross-compatibility notes + +| Component | Claude Code path | Copilot CLI path | Portable? | +|---|---|---|---| +| Plugin manifest | `.claude-plugin/plugin.json` | `plugin.json` at root | Ship both | +| Skills | `skills//SKILL.md` | `skills//SKILL.md` | ✅ Identical | +| Agents | `agents/.md` | `agents/.agent.md` | Ship both | +| Hooks | `hooks/hooks.json` | `hooks.json` at root | Ship both | +| MCP servers | `.mcp.json` at root | `.mcp.json` at root | ✅ Identical | ## Install via marketplace -### Claude Code ```bash +# Claude Code claude plugin marketplace add /ai-development claude plugin install hello-world@holocron -``` -### GitHub Copilot CLI -```bash +# GitHub Copilot CLI copilot plugin marketplace add /ai-development copilot plugin install hello-world ``` ## Local dev install -### Claude Code ```bash +# Claude Code claude --plugin-dir ./plugins/hello-world -``` -### GitHub Copilot CLI -```bash +# GitHub Copilot CLI copilot plugin install ./plugins/hello-world ``` -## Verify +## Validate (Claude Code) -After install, open a new session and type `/hello-world` or "test plugin install". +```bash +claude plugin validate ./plugins/hello-world +``` + +Copilot CLI has no validate command — run `copilot plugin install ./plugins/hello-world` +and check that `/skills list` and `/agent` surface the expected entries. + +## Creating a new plugin from this scaffold + +1. Copy `plugins/hello-world/` → `plugins//` +2. Update `name` in both `plugin.json` files +3. Replace `skills/hello-world/SKILL.md` with your skill(s) +4. Replace or remove `agents/` files — only include if your plugin ships an agent +5. Replace or remove `hooks/` files — only include if your plugin reacts to events +6. Replace or remove `.mcp.json` — only include if your plugin ships an MCP server +7. Add the new plugin to `.claude-plugin/marketplace.json` +8. Run `claude plugin validate ./plugins/` diff --git a/plugins/hello-world/agents/hello-world.agent.md b/plugins/hello-world/agents/hello-world.agent.md new file mode 100644 index 0000000..4323f08 --- /dev/null +++ b/plugins/hello-world/agents/hello-world.agent.md @@ -0,0 +1,13 @@ +--- +name: hello-world +description: A demonstration agent for the holocron marketplace scaffold. Confirms agent loading works in GitHub Copilot CLI. +tools: + - read_file + - list_directory +--- + +You are a demonstration agent included in the `hello-world` scaffold plugin for the **holocron** marketplace. + +When invoked, greet the user, confirm the agent is loaded, and list the components available in this plugin: skills (`skills/`), agents (`agents/`), hooks (`hooks.json`), and MCP servers (`.mcp.json`). + +Replace this file with your agent's actual system prompt and instructions. diff --git a/plugins/hello-world/agents/hello-world.md b/plugins/hello-world/agents/hello-world.md new file mode 100644 index 0000000..da7f6e9 --- /dev/null +++ b/plugins/hello-world/agents/hello-world.md @@ -0,0 +1,10 @@ +--- +name: hello-world +description: A demonstration agent for the holocron marketplace scaffold. Confirms agent loading works in Claude Code. +--- + +You are a demonstration agent included in the `hello-world` scaffold plugin for the **holocron** marketplace. + +When invoked, greet the user, confirm the agent is loaded, and list the components available in this plugin: skills (`skills/`), agents (`agents/`), hooks (`hooks/hooks.json`), and MCP servers (`.mcp.json`). + +Replace this file with your agent's actual system prompt and instructions. diff --git a/plugins/hello-world/hooks.json b/plugins/hello-world/hooks.json new file mode 100644 index 0000000..d01a9f2 --- /dev/null +++ b/plugins/hello-world/hooks.json @@ -0,0 +1,8 @@ +{ + "hooks": [ + { + "event": "session_start", + "command": "echo '[hello-world] session started'" + } + ] +} diff --git a/plugins/hello-world/hooks/hooks.json b/plugins/hello-world/hooks/hooks.json new file mode 100644 index 0000000..c67f7cb --- /dev/null +++ b/plugins/hello-world/hooks/hooks.json @@ -0,0 +1,15 @@ +{ + "hooks": { + "PostToolUse": [ + { + "matcher": "*", + "hooks": [ + { + "type": "command", + "command": "echo '[hello-world] PostToolUse fired'" + } + ] + } + ] + } +} diff --git a/plugins/hello-world/plugin.json b/plugins/hello-world/plugin.json index b99fbe8..50797c7 100644 --- a/plugins/hello-world/plugin.json +++ b/plugins/hello-world/plugin.json @@ -1,4 +1,11 @@ { "name": "hello-world", - "description": "A minimal example plugin to validate marketplace scaffolding." + "description": "A complete scaffold demonstrating every cross-compatible plugin feature for the holocron marketplace.", + "author": { "name": "Your Name", "email": "you@example.com" }, + "license": "MIT", + "keywords": ["scaffold", "example", "holocron"], + "agents": "agents/", + "skills": ["skills/"], + "hooks": "hooks.json", + "mcpServers": ".mcp.json" }