Add agent plugin system for custom agent creation#95
Merged
PAMulligan merged 20 commits intoMay 28, 2026
Conversation
Approved design for a Markdown + Node tooling layer that lets users author, validate, install, and dependency-resolve custom Claude Code agents. Covers manifest schema, registry, scaffolding CLI, and a static-assertion testing framework. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Bite-sized, TDD-ordered plan for the Markdown + Node tooling layer: shared lib, manifest schema, validator, registry with dependency resolution and lifecycle hooks, scaffolding CLI, and static-assertion test runner. Each task has complete code, exact paths, and expected commands. References superpowers:executing-plans to run. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…nd schema error detail buildCatalog now skips unreadable/malformed plugin.json entries so one bad plugin can't abort an --all scan. The validator seeds its catalog from sibling plugins in --dir mode (no false-positive missing-dep errors), adds a --plugins-root override, rejects --dir+--all, and surfaces the offending property in schema errors via formatSchemaError. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…tall, lifecycle hooks
…on, cover hook paths
…e tools, roll back writes
Add docs/guides/agent-plugins.md (authoring guide: layout, manifest reference, the four CLIs, dependency model, lifecycle hooks, assertion catalog), and wire the commands into scripts/README.md and CLAUDE.md. Bump the documented script count to reflect the new tooling. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add an `agent-plugins` check that runs validate-agent-plugin.js --all and test-agent-plugin.js --all via verify-agent-plugins.sh. It skips (like bundle-size) when no plugins exist under .claude/agent-plugins/, so it is a no-op on repos without plugins. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Un-ignore .claude/agent-plugins/ so authored plugins (and installed.json) are version-controlled — the "versioned plugins" premise was broken because .claude/* ignored the whole tree. Also validate each plugin before copying its agent.md into .claude/agents/, so a structurally invalid agent can no longer install with exit 0. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
PAMulligan
added
enhancement
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements a plugin architecture for authoring, validating, dependency-resolving, installing, and testing custom Claude Code agents as versioned plugins. A plugin lives under
.claude/agent-plugins/<name>/(plugin.json+agent.md+ optionalhooks/+tests/); installing copies the agent into.claude/agents/where Claude Code reads it.Delivers all four pieces from the issue:
.claude/agent-plugin.schema.json(strict JSON Schema 2020) + structural rules in the validator.create-agent-plugin.jsgenerates a valid plugin skeleton (house-styleagent.md, default tests, optional hook stubs).agent-registry.jsresolves the transitive agent-dependency graph (semver, topological order, missing/version/cycle detection), installs/uninstalls with management-lifecycle hooks, and records state ininstalled.json. Skills/tools deps are existence-checked.validate-agent-plugin.js(schema + structural checks) andtest-agent-plugin.js(deterministic static assertions; no Claude invocation, unknown assertions fail loudly).All four CLIs share
agent-plugin-lib.js(frontmatter/manifest parsing, catalog, semver, resolver, dir listing), use--json+ exit codes0/1/2, and a--plugins-root/--rootoverride for testing.Notes
verify-all.shas a conditionalagent-pluginscheck (no-op when no plugins exist).docs/guides/agent-plugins.md; design + plan underdocs/plans/2026-05-27-agent-plugin-system*.md.Test plan
pnpm vitest run scripts/__tests__/agent-plugin-*.test.js scripts/__tests__/{validate,agent-registry,create,test}-agent-plugin.test.js scripts/__tests__/verify-all.test.js— 82 tests passbash scripts/verify-all.sh --include agent-pluginsskips cleanly (no plugins in repo)Closes #9
🤖 Generated with Claude Code