@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.1

package/extensions/plugin-dev/skills/plugin-dev-guide/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: plugin-dev-guide
+description: Use when the user asks about Enact plugins, multi-platform plugin development, plugin architecture, or which skill to load. Meta-router for the Enact Plugin Manager toolkit.
+---
+
+# Enact Plugin Development Guide
+
+Routes to specialized skills for building plugins that run on **ENACT-native surfaces plus Claude Code, Codex, and Cursor** from one bundle.
+
+## Layout reminder
+
+- Canonical: `extensions/.agents/plugin.json` (or your plugin root)
+- Sync hosts: `enact-extensions sync` (from plugin root)
+- Validate: `enact-extensions validate`
+
+Skills and hooks authored in this bundle should work across all projected surfaces by default. Keep workflow language surface-neutral unless a host-specific behavior is genuinely required and clearly isolated.
+
+See `ORGANIZATION.md` in the enact-extensions repo root.
+
+### Active skills
+
+| Skill | Purpose |
+|-------|---------|
+| **plugin-structure** | Multi-platform layout and manifests |
+| **skill-development** | `skills/*/SKILL.md` |
+| **command-development** | Slash commands in `commands/` |
+| **hook-development** | `hooks/hooks.json` |
+| **mcp-integration** | `.mcp.json` |
+| **agent-development** | `agents/*.md` (Claude/Cursor) |
+
+### Archived (see `skills/_archive/`)
+
+`lsp-integration`, `plugin-settings`, `marketplace-structure` — restore when needed.
+
+## When to Use Each Skill
+
+### Starting a New Plugin
+
+**Skill: `plugin-structure`**
+
+Use when the user needs to:
+
+- Create a new plugin from scratch
+- Understand plugin directory layout
+- Configure plugin.json manifest
+- Learn about component auto-discovery
+- Use ${CLAUDE_PLUGIN_ROOT} for portable paths
+
+### Adding User-Facing Commands
+
+**Skill: `command-development`**
+
+Use when the user needs to:
+
+- Create slash commands (/command-name)
+- Configure command frontmatter (description, allowed-tools, model)
+- Use dynamic arguments ($ARGUMENTS, $1, $2)
+- Reference files with @ syntax
+- Execute bash inline with `[BANG]` backticks
+
+### Creating Autonomous Agents
+
+**Skill: `agent-development`**
+
+Use when the user needs to:
+
+- Create subagents for complex tasks
+- Write agent system prompts
+- Configure agent triggering (description with examples)
+- Choose agent models and colors
+- Restrict agent tool access
+
+### Building Skills
+
+**Skill: `skill-development`**
+
+Use when the user needs to:
+
+- Create skills that extend Claude's capabilities
+- Write SKILL.md with proper frontmatter
+- Organize skill content with progressive disclosure
+- Create references/, examples/, scripts/ directories
+- Write effective trigger phrases
+
+### Implementing Event Hooks
+
+**Skill: `hook-development`**
+
+Use when the user needs to:
+
+- React to Claude Code events (PreToolUse, Stop, SessionStart, etc.)
+- Create prompt-based or command-based hooks
+- Validate tool inputs before execution
+- Enforce completion standards
+- Block dangerous operations
+
+### Integrating External Services via MCP
+
+**Skill: `mcp-integration`**
+
+Use when the user needs to:
+
+- Add MCP servers to plugins
+- Configure stdio, SSE, HTTP, or WebSocket servers
+- Set up authentication (OAuth, tokens)
+- Use MCP tools in commands and agents
+- Discover existing MCP servers on PulseMCP
+
+### Adding Code Intelligence via LSP
+
+**Skill: `lsp-integration`**
+
+Use when the user needs to:
+
+- Add Language Server Protocol servers to plugins
+- Enable go-to-definition and find-references
+- Configure language-specific servers (pyright, gopls, rust-analyzer)
+- Set up extensionToLanguage mappings
+- Enhance Claude's code understanding
+
+### Managing Plugin Configuration
+
+**Skill: `plugin-settings`**
+
+Use when the user needs to:
+
+- Store user-configurable settings
+- Use .claude/plugin-name.local.md pattern
+- Parse YAML frontmatter in hooks
+- Create temporarily active hooks
+- Manage agent state
+
+### Creating Plugin Marketplaces
+
+**Skill: `marketplace-structure`**
+
+Use when the user needs to:
+
+- Create a marketplace for multiple plugins
+- Configure marketplace.json
+- Set up plugin sources (relative, GitHub, git URL)
+- Distribute plugins to teams
+- Organize plugin collections
+
+## Decision Tree for Skill Selection
+
+```
+User wants to...
+├── Create/organize a plugin structure? → plugin-structure
+├── Add a simple slash command (no bundled resources)? → command-development
+├── Create an autonomous agent? → agent-development
+├── Add a complex skill with scripts/references? → skill-development
+├── React to Claude Code events? → hook-development
+├── Integrate external service/API? → mcp-integration
+├── Add code intelligence/LSP? → lsp-integration
+├── Make plugin configurable? → plugin-settings
+└── Distribute multiple plugins? → marketplace-structure
+```
+
+## Common Multi-Skill Workflows
+
+### Building a Complete Plugin
+
+1. **Start**: Load `plugin-structure` skill to create directory layout
+2. **Add features**: Load `command-development` for user-facing commands
+3. **Automation**: Load `hook-development` for event-driven behavior
+4. **Configuration**: Load `plugin-settings` if user configuration needed
+5. **Validation**: Use plugin-validator agent to validate structure
+
+### Creating an MCP-Powered Plugin
+
+1. **Start**: Load `plugin-structure` for basic structure
+2. **Integration**: Load `mcp-integration` to configure MCP servers
+3. **Commands**: Load `command-development` to create commands that use MCP tools
+4. **Agents**: Load `agent-development` for autonomous MCP workflows
+
+### Building a Code Intelligence Plugin
+
+1. **Start**: Load `plugin-structure` for basic structure
+2. **LSP**: Load `lsp-integration` to configure language servers
+3. **Commands**: Load `command-development` for commands using LSP features
+
+### Building a Skill-Focused Plugin
+
+1. **Start**: Load `plugin-structure` for basic structure
+2. **Skills**: Load `skill-development` to create specialized skills
+3. **Validation**: Use skill-reviewer agent to validate skill quality
+
+## Available Agents
+
+The plugin-dev plugin also provides 3 agents:
+
+| Agent                | Purpose                                  |
+| -------------------- | ---------------------------------------- |
+| **plugin-validator** | Validates plugin structure and manifests |
+| **skill-reviewer**   | Reviews skill quality and triggering     |
+| **agent-creator**    | Generates new agents from descriptions   |
+
+Use agents proactively after creating components to ensure quality.
+
+## Available Commands
+
+| Command                          | Purpose                                             |
+| -------------------------------- | --------------------------------------------------- |
+| `/plugin-dev:plugin-dev-guide`   | Overview and skill routing                          |
+| `/plugin-dev:start`              | Entry point - choose plugin or marketplace creation |
+| `/plugin-dev:create-plugin`      | 8-phase guided plugin creation workflow             |
+| `/plugin-dev:create-marketplace` | 8-phase guided marketplace creation workflow        |
+
+---
+
+## User Request
+
+$ARGUMENTS
+
+If the user provided a request above, analyze it and either:
+
+1. **Route to a specific skill** if the request clearly matches one domain
+2. **Answer directly** using this guide's overview information
+3. **Ask for clarification** if the request is ambiguous
+
+If no request was provided, summarize the available plugin development capabilities and ask what the user wants to build or learn about.