{"id":41748385,"url":"https://github.com/sjnims/plugin-dev","last_synced_at":"2026-01-30T06:52:02.461Z","repository":{"id":328083512,"uuid":"1111913953","full_name":"sjnims/plugin-dev","owner":"sjnims","description":"Comprehensive toolkit for developing Claude Code plugins. Includes 8 expert skills covering hooks, MCP integration, commands, agents, and best practices.","archived":false,"fork":false,"pushed_at":"2026-01-25T01:49:32.000Z","size":767,"stargazers_count":8,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-25T12:14:18.876Z","etag":null,"topics":["ai-tools","claude","claude-code","developer-tools","mcp","plugin-development"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sjnims.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-07T21:34:40.000Z","updated_at":"2026-01-25T01:49:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sjnims/plugin-dev","commit_stats":null,"previous_names":["sjnims/plugin-dev"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/sjnims/plugin-dev","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjnims%2Fplugin-dev","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjnims%2Fplugin-dev/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjnims%2Fplugin-dev/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjnims%2Fplugin-dev/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sjnims","download_url":"https://codeload.github.com/sjnims/plugin-dev/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjnims%2Fplugin-dev/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28907053,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-30T06:42:00.998Z","status":"ssl_error","status_checked_at":"2026-01-30T06:41:58.659Z","response_time":66,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tools","claude","claude-code","developer-tools","mcp","plugin-development"],"created_at":"2026-01-25T01:07:15.386Z","updated_at":"2026-01-30T06:52:02.452Z","avatar_url":"https://github.com/sjnims.png","language":"Shell","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/banner-terminal.svg\" alt=\"plugin-dev - The complete toolkit for Claude Code plugins\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n# Plugin Development Toolkit\n\n[![CI](https://github.com/sjnims/plugin-dev/actions/workflows/component-validation.yml/badge.svg)](https://github.com/sjnims/plugin-dev/actions/workflows/component-validation.yml)\n[![Markdown](https://github.com/sjnims/plugin-dev/actions/workflows/markdownlint.yml/badge.svg)](https://github.com/sjnims/plugin-dev/actions/workflows/markdownlint.yml)\n[![Version](https://img.shields.io/github/v/release/sjnims/plugin-dev?label=version\u0026color=blue)](https://github.com/sjnims/plugin-dev/releases)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n\nA comprehensive toolkit for developing Claude Code plugins with expert guidance on hooks, MCP integration, plugin structure, and marketplace publishing.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Skills](#skills)\n- [Guided Workflows](#guided-workflows)\n- [Validation Agents](#validation-agents)\n- [Utility Scripts](#utility-scripts)\n- [Development Workflow](#development-workflow)\n- [Use Cases](#use-cases)\n- [Best Practices](#best-practices)\n- [FAQ](#faq)\n- [Contributing](#contributing)\n- [Getting Help](#getting-help)\n- [Attribution](#attribution)\n- [Changelog](#changelog)\n- [License](#license)\n\n## Overview\n\nThe plugin-dev toolkit provides **10 specialized skills**, **3 validation agents**, and **4 slash commands** to help you build high-quality Claude Code plugins:\n\n- **Skills** provide domain expertise loaded on-demand via trigger phrases\n- **Agents** automate validation and generation tasks\n- **Workflows** guide you through complete plugin or marketplace creation\n\nEach component follows progressive disclosure: lean core documentation with detailed references and working examples available when needed.\n\n## Prerequisites\n\n### Required\n\n- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and configured\n- Git (for version control and marketplace publishing)\n\n### For Utility Scripts\n\nThe plugin includes utility scripts for validation and testing. These require:\n\n| Tool | Version | Purpose                               |\n| ---- | ------- | ------------------------------------- |\n| bash | 3.2+    | Shell scripting (macOS default works) |\n| jq   | 1.6+    | JSON parsing and validation           |\n| grep | -       | Pattern matching (with `-E` support)  |\n| sed  | -       | Stream editing (GNU or BSD)           |\n\n**Check your environment:**\n\n```bash\nbash --version | head -1\njq --version\ngrep --version 2\u003e\u00261 | head -1\n```\n\n\u003e **Note**: `jq` may need to be installed. macOS: `brew install jq`, Linux: `apt install jq`\n\n## Installation\n\nAdd this marketplace and install the plugin:\n\n```bash\n/plugin marketplace add sjnims/plugin-dev\n/plugin install plugin-dev@sjnims/plugin-dev\n```\n\nOr for development, use directly:\n\n```bash\nclaude --plugin-dir /path/to/plugin-dev/plugins/plugin-dev\n```\n\n## Quick Start\n\n**New to plugin development?** Start with the guided entry point:\n\n```bash\n/plugin-dev:start\n```\n\nThis will help you choose between creating a **plugin** (most users) or a **marketplace** (for distributing multiple plugins).\n\n### Learning by Asking\n\nYou can also learn progressively by asking questions. Skills load automatically:\n\n1. **Plan your plugin structure:**\n   - Ask: \"What's the best directory structure for a plugin with commands and MCP integration?\"\n   - The plugin-structure skill will guide you\n\n2. **Add MCP integration (if needed):**\n   - Ask: \"How do I add an MCP server for database access?\"\n   - The mcp-integration skill provides examples and patterns\n\n3. **Implement hooks (if needed):**\n   - Ask: \"Create a PreToolUse hook that validates file writes\"\n   - The hook-development skill gives working examples and utilities\n\n## Skills\n\nSkills load automatically when you ask relevant questions. Each skill includes core documentation, reference guides, working examples, and utility scripts.\n\n| Skill                     | Trigger Phrases                                                                                           | Use For                                                             |\n| ------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |\n| **Hook Development**      | `create a hook`, `PreToolUse hook`, `validate tool use`, `prompt-based hooks`, `block dangerous commands` | Event-driven automation, operation validation, policy enforcement   |\n| **MCP Integration**       | `add MCP server`, `integrate MCP`, `.mcp.json`, `Model Context Protocol`, `stdio/SSE server`              | External service integration, API connections, database access      |\n| **LSP Integration**       | `add LSP server`, `configure language server`, `set up LSP`, `code intelligence`, `pyright-lsp`           | Language server integration, code navigation, type information      |\n| **Plugin Structure**      | `plugin structure`, `plugin.json`, `auto-discovery`, `component organization`                             | Starting new plugins, organizing components, manifest configuration |\n| **Plugin Settings**       | `plugin settings`, `.local.md files`, `YAML frontmatter`, `per-project settings`                          | Configuration storage, user preferences, per-project state          |\n| **Command Development**   | `create a slash command`, `command frontmatter`, `command arguments`                                      | Slash commands, argument handling, command organization             |\n| **Agent Development**     | `create an agent`, `write a subagent`, `agent frontmatter`, `autonomous agent`                            | Autonomous agents, AI-assisted generation, agent behavior           |\n| **Skill Development**     | `create a skill`, `add a skill`, `skill description`, `progressive disclosure`                            | Creating new skills, improving skill quality                        |\n| **Marketplace Structure** | `create a marketplace`, `marketplace.json`, `distribute plugins`, `host plugins`                          | Marketplace creation, plugin distribution, team sharing             |\n\n### Skill Resources\n\nEach skill provides:\n\n- **Core SKILL.md** (~1,500-2,500 words) - Essential API reference\n- **references/** - Detailed guides and patterns\n- **examples/** - Complete working code for copy-paste\n- **scripts/** - Validation and testing utilities\n\nFor detailed documentation on any skill, ask Claude Code or browse the `skills/` directory.\n\n## Guided Workflows\n\n### /plugin-dev:start\n\nA guided entry point to help you choose between creating a **plugin** (most users) or a **marketplace** (for distributing multiple plugins).\n\n### /plugin-dev:create-plugin\n\nA comprehensive, end-to-end workflow for creating plugins from scratch.\n\n**8-Phase Process:**\n\n1. **Discovery** - Understand plugin purpose and requirements\n2. **Component Planning** - Determine needed skills, commands, agents, hooks, MCP\n3. **Detailed Design** - Specify each component and resolve ambiguities\n4. **Structure Creation** - Set up directories and manifest\n5. **Component Implementation** - Create each component using AI-assisted agents\n6. **Validation** - Run plugin-validator and component-specific checks\n7. **Testing** - Verify plugin works in Claude Code\n8. **Documentation** - Finalize README and prepare for distribution\n\n**Usage:**\n\n```bash\n/plugin-dev:create-plugin [optional description]\n\n# Examples:\n/plugin-dev:create-plugin\n/plugin-dev:create-plugin A plugin for managing database migrations\n```\n\n### /plugin-dev:create-marketplace\n\nA guided workflow for creating plugin marketplaces to distribute plugins.\n\n**8-Phase Process:**\n\n1. **Discovery** - Understand marketplace purpose and audience\n2. **Plugin Planning** - Determine plugins to include\n3. **Metadata Design** - Configure marketplace metadata and branding\n4. **Structure Creation** - Create directory and manifest\n5. **Plugin Entry Configuration** - Configure each plugin entry (paths, repos, versions)\n6. **Distribution Setup** - Configure team settings or community guidelines\n7. **Validation** - Run marketplace validators\n8. **Testing \u0026 Finalization** - Test installation and finalize\n\n**Usage:**\n\n```bash\n/plugin-dev:create-marketplace [optional description]\n\n# Examples:\n/plugin-dev:create-marketplace\n/plugin-dev:create-marketplace A marketplace for our team's internal tools\n```\n\n## Validation Agents\n\nUse these agents proactively after creating components:\n\n| Agent                | Purpose                                                           | Trigger                                        |\n| -------------------- | ----------------------------------------------------------------- | ---------------------------------------------- |\n| **plugin-validator** | Validates entire plugin structure, manifest, and marketplace.json | \"validate my plugin\", \"check plugin structure\" |\n| **skill-reviewer**   | Reviews skill quality, triggering reliability, and best practices | \"review my skill\", \"check skill quality\"       |\n| **agent-creator**    | Generates new agents from natural language descriptions           | \"create an agent\", \"generate an agent that...\" |\n\n**Example usage:**\n\n```\n\u003e validate my plugin at plugins/my-plugin\n\u003e review the skill I just created\n\u003e create an agent that reviews code for security issues\n```\n\n## Utility Scripts\n\nAll scripts are located in `plugins/plugin-dev/skills/*/scripts/` and can be run directly:\n\n### Agent Development\n\n```bash\n# Create a new agent skeleton\n./skills/agent-development/scripts/create-agent-skeleton.sh my-agent agents/\n\n# Validate agent frontmatter and structure\n./skills/agent-development/scripts/validate-agent.sh agents/my-agent.md\n\n# Test agent trigger phrases\n./skills/agent-development/scripts/test-agent-trigger.sh agents/my-agent.md\n```\n\n### Command Development\n\n```bash\n# Validate command structure\n./skills/command-development/scripts/validate-command.sh commands/my-command.md\n\n# Check frontmatter fields\n./skills/command-development/scripts/check-frontmatter.sh commands/my-command.md\n```\n\n### Hook Development\n\n```bash\n# Validate hooks.json schema\n./skills/hook-development/scripts/validate-hook-schema.sh hooks/hooks.json\n\n# Test a hook with sample input\n./skills/hook-development/scripts/test-hook.sh hooks/my-hook.sh input.json\n\n# Lint hook scripts\n./skills/hook-development/scripts/hook-linter.sh hooks/my-hook.sh\n```\n\n### Plugin Settings\n\n```bash\n# Validate settings file structure\n./skills/plugin-settings/scripts/validate-settings.sh .claude/plugin.local.md\n\n# Parse frontmatter from settings\n./skills/plugin-settings/scripts/parse-frontmatter.sh .claude/plugin.local.md\n```\n\n## Development Workflow\n\n```mermaid\ngraph TD\n    A[Design Structure] --\u003e B[Add Components]\n    B --\u003e C[Integrate Services]\n    C --\u003e D[Add Automation]\n    D --\u003e E[Test \u0026 Validate]\n\n    A -.- A1[plugin-structure skill]\n    B -.- B1[command/agent/skill skills]\n    C -.- C1[mcp-integration skill]\n    D -.- D1[hook-development skill]\n    E -.- E1[validation agents + scripts]\n```\n\n\u003c!-- Text fallback for viewers that don't render mermaid --\u003e\n\u003cdetails\u003e\n\u003csummary\u003eWorkflow diagram (text version)\u003c/summary\u003e\n\n```\nDesign Structure → Add Components → Integrate Services → Add Automation → Test \u0026 Validate\n       ↓                 ↓                  ↓                  ↓                ↓\nplugin-structure   command/agent/     mcp-integration    hook-development   validation\n    skill          skill skills           skill              skill         agents + scripts\n```\n\n\u003c/details\u003e\n\n| Phase          | Skill/Tool                      | What You Do                         |\n| -------------- | ------------------------------- | ----------------------------------- |\n| **Design**     | plugin-structure                | Define manifest, directory layout   |\n| **Components** | command/agent/skill development | Create commands, agents, skills     |\n| **Services**   | mcp-integration                 | Configure MCP servers               |\n| **Automation** | hook-development                | Add hooks for validation/automation |\n| **Validate**   | Agents + scripts                | Run validators, test components     |\n\n## Use Cases\n\n### Building a Database Plugin\n\n| Step | Ask Claude Code                                           | Skill Used       |\n| ---- | --------------------------------------------------------- | ---------------- |\n| 1    | \"What's the structure for a plugin with MCP integration?\" | plugin-structure |\n| 2    | \"Configure an stdio MCP server for PostgreSQL\"            | mcp-integration  |\n| 3    | \"Add a Stop hook to ensure connections close properly\"    | hook-development |\n\n### Creating a Validation Plugin\n\n| Step | Ask Claude Code                                           | Skill Used                  |\n| ---- | --------------------------------------------------------- | --------------------------- |\n| 1    | \"Create hooks that validate all file writes for security\" | hook-development            |\n| 2    | \"Test my hooks before deploying\"                          | Use validate-hook-schema.sh |\n| 3    | \"Organize my hooks and configuration files\"               | plugin-structure            |\n\n### Integrating External Services\n\n| Step | Ask Claude Code                             | Skill Used       |\n| ---- | ------------------------------------------- | ---------------- |\n| 1    | \"Add Asana MCP server with OAuth\"           | mcp-integration  |\n| 2    | \"Use Asana tools in my commands\"            | mcp-integration  |\n| 3    | \"Structure my plugin with commands and MCP\" | plugin-structure |\n\n## Best Practices\n\n### Security First\n\n- Input validation in all hooks\n- HTTPS/WSS for MCP servers\n- Environment variables for credentials\n- Principle of least privilege\n- Use `[BANG]` placeholder in skill documentation for shell patterns (see [SECURITY.md](SECURITY.md))\n\n### Portability\n\n- Use `${CLAUDE_PLUGIN_ROOT}` for all paths\n- Relative paths only within plugin\n- Environment variable substitution for secrets\n\n### Testing\n\n- Validate configurations before deployment\n- Test hooks with sample inputs\n- Use debug mode (`claude --debug`)\n- Create separate test repositories to avoid polluting development\n\n### Documentation\n\n- Clear README files for each plugin\n- Document all environment variables\n- Include usage examples\n\n### What to Avoid\n\n| Anti-Pattern                        | Why It's Bad                            | Better Approach                          |\n| ----------------------------------- | --------------------------------------- | ---------------------------------------- |\n| Hardcoded absolute paths            | Breaks portability                      | Use `${CLAUDE_PLUGIN_ROOT}`              |\n| Overly broad hook matchers (`*`)    | Unexpected triggers, performance impact | Use specific patterns like `Write\\|Edit` |\n| Large SKILL.md files (\u003e2,000 words) | Slow loading, context bloat             | Use `references/` for detailed docs      |\n| Storing secrets in manifests        | Security risk                           | Use environment variables                |\n| Testing in your main dev repo       | File pollution, git noise               | Use dedicated test repositories          |\n\n## FAQ\n\n**Q: How do I test my plugin without affecting my development environment?**\n\nCreate a separate test repository and load the plugin from there. See [CONTRIBUTING.md](CONTRIBUTING.md#test-repository) for detailed instructions.\n\n**Q: My skill isn't loading when I ask trigger questions. What's wrong?**\n\nCheck that your skill description includes the specific phrases users might say. The description should start with \"This skill should be used when...\" and include example queries like `\"create a hook\"`, `\"add MCP server\"`.\n\n**Q: What's the `[BANG]` placeholder I see in documentation?**\n\nDue to a Claude Code issue, inline bash patterns (`!` followed by backtick) can execute during skill loading. The `[BANG]` placeholder prevents this. See [SECURITY.md](SECURITY.md#shell-pattern-escaping-with-bang-placeholder) for details.\n\n**Q: How do I structure a plugin with both commands and MCP integration?**\n\nStart with `/plugin-dev:create-plugin` for a guided walkthrough, or ask: \"What's the best directory structure for a plugin with commands and MCP integration?\" The plugin-structure skill will guide you.\n\n**Q: Can I restrict which tools my skill or agent can use?**\n\nYes, use the `allowed-tools` frontmatter field. For example: `allowed-tools: Read, Grep, Glob` creates a read-only skill.\n\n## Contributing\n\nTo contribute improvements:\n\n1. Fork this repository\n2. Make changes to `plugins/plugin-dev/`\n3. Test locally with `claude --plugin-dir plugins/plugin-dev`\n4. Run linters: `markdownlint '**/*.md'` and `shellcheck plugins/plugin-dev/skills/*/scripts/*.sh`\n5. Create a PR with your changes\n\n## Getting Help\n\n- **Issues**: [GitHub Issues](https://github.com/sjnims/plugin-dev/issues)\n- **Documentation**: [Claude Code Plugins](https://docs.anthropic.com/en/docs/claude-code/plugins)\n- **Skills Reference**: [Claude Code Skills](https://docs.anthropic.com/en/docs/claude-code/skills)\n\n## Attribution\n\nThis plugin was originally developed by [Daisy Hollman](mailto:daisy@anthropic.com) at Anthropic. The original plugin can be found at:\n\n- [claude-code/plugins/plugin-dev](https://github.com/anthropics/claude-code/tree/main/plugins/plugin-dev)\n- [claude-plugins-official/plugins/plugin-dev](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/plugin-dev)\n\nThis repository ([sjnims/plugin-dev](https://github.com/sjnims/plugin-dev)) is an expanded version with:\n\n- Enhanced skill descriptions with stronger trigger phrases\n- Additional utility scripts (test-agent-trigger.sh, create-agent-skeleton.sh)\n- Expanded MCP integration documentation\n- Comprehensive command development references\n- CI/CD workflows for validation and quality assurance\n- Improved cross-references between skills\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for release history and version details.\n\n## License\n\nMIT License - See [LICENSE](LICENSE) for details\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsjnims%2Fplugin-dev","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsjnims%2Fplugin-dev","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsjnims%2Fplugin-dev/lists"}