@amsterdamdatalabs/enact-extensions 0.1.42 → 0.1.47

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

@@ -1,505 +0,0 @@
----
-name: create-plugin
-description: >-
-  Guided workflow to create a complete Enact plugin from concept to tested
-  implementation. Use when someone says "create a plugin", "build a plugin",
-  "/create-plugin", or describes plugin functionality they want to scaffold.
----
-
-# Plugin Creation Workflow
-
-> **Commands are skills.** Enact plugins have no separate "commands" component.
-> A user-initiated action (e.g. `/create-plugin`) is an *invocable skill* — a
-> skill whose `SKILL.md` carries an invocable frontmatter and `$ARGUMENTS`.
-> Wherever you'd reach for a "command", create a skill instead.
-
-Guide the user through creating a complete, high-quality Claude Code plugin from initial concept to tested implementation. Follow a systematic approach: understand requirements, design components, clarify details, implement following best practices, validate, and test.
-
-## Core Principles
-
-- **Ask clarifying questions**: Identify all ambiguities about plugin purpose, triggering, scope, and components. Ask specific, concrete questions rather than making assumptions. Wait for user answers before proceeding with implementation.
-- **Load relevant skills**: Use the Skill tool to load plugin-dev skills when needed (plugin-structure, hook-development, agent-development, etc.)
-- **Use specialized agents**: Leverage agent-creator, plugin-validator, and skill-reviewer agents for AI-assisted development
-- **Follow best practices**: Apply patterns from plugin-dev's own implementation
-- **Progressive disclosure**: Create lean skills with references/examples
-- **Use Task tools**: Track all progress throughout all phases using TaskCreate, TaskUpdate, and TaskList
-
-**Initial request:** $ARGUMENTS
-
-**Security note:** This workflow has broad file system access to create plugin structures. It can write files and create directories within your permission scope. Review the target directory before starting, and see [docs/workflow-security.md](../../../docs/workflow-security.md) for details.
-
----
-
-## Phase 1: Discovery
-
-**Goal**: Understand what plugin needs to be built and what problem it solves
-
-**Actions**:
-
-1. Create task list with all 8 phases
-2. If plugin purpose is clear from arguments:
-   - Summarize understanding
-   - Identify plugin type (integration, workflow, analysis, toolkit, etc.)
-3. If plugin purpose is unclear, ask user:
-   - What problem does this plugin solve?
-   - Who will use it and when?
-   - What should it do?
-   - Any similar plugins to reference?
-4. Summarize understanding and confirm with user before proceeding
-
-**Output**: Clear statement of plugin purpose and target users
-
----
-
-## Phase 2: Component Planning
-
-**Goal**: Determine what plugin components are needed
-
-**MUST load plugin-structure skill** using Skill tool before this phase.
-
-**Actions**:
-
-1. Load plugin-structure skill to understand component types
-2. Analyze plugin requirements and determine needed components:
-   - **Skills**: Specialized knowledge AND user-initiated actions. A skill can
-     be passive (auto-triggered by its description) or *invocable* (a slash
-     entry point like `/deploy` carrying `$ARGUMENTS`). There is no separate
-     "command" component — invocable skills replace commands.
-   - **Agents**: Autonomous tasks? (validation, generation, analysis)
-   - **Hooks**: Event-driven automation? (validation, notifications)
-   - **MCP**: External service integration? (databases, APIs)
-   - **LSP**: Code intelligence? (go-to-definition, find references)
-   - **Settings**: User configuration? (.local.md files)
-3. For each component type needed, identify:
-   - How many of each type
-   - What each one does
-   - Rough triggering/usage patterns
-4. Present component plan to user as table:
-   ```
-   | Component Type     | Count | Purpose |
-   |--------------------|-------|---------|
-   | Skills (passive)   | 2     | Hook patterns, MCP usage |
-   | Skills (invocable) | 3     | /deploy, /configure, /validate |
-   | Agents             | 1     | Autonomous validation |
-   | Hooks              | 0     | Not needed |
-   | MCP                | 1     | Database integration |
-   ```
-5. Get user confirmation or adjustments
-
-**Output**: Confirmed list of components to create
-
----
-
-## Phase 3: Detailed Design & Clarifying Questions
-
-**Goal**: Specify each component in detail and resolve all ambiguities
-
-**CRITICAL**: This is one of the most important phases. DO NOT SKIP.
-
-**Actions**:
-
-1. For each component in the plan, identify underspecified aspects:
-   - **Skills (passive)**: What triggers them? What knowledge do they provide? How detailed?
-   - **Skills (invocable)**: What slash name? What `$ARGUMENTS`? Interactive or automated?
-   - **Agents**: When to trigger (proactive/reactive)? What tools? Output format?
-   - **Hooks**: Which events? Prompt or command based? Validation criteria?
-   - **MCP**: What server type? Authentication? Which tools?
-   - **Settings**: What fields? Required vs optional? Defaults?
-
-2. **Present all questions to user in organized sections** (one section per component type)
-
-3. **Wait for answers before proceeding to implementation**
-
-4. If user says "whatever you think is best", provide specific recommendations and get explicit confirmation
-
-**Example questions for a skill**:
-
-- What specific user queries should trigger this skill?
-- Should it include utility scripts? What functionality?
-- How detailed should the core SKILL.md be vs references/?
-- Any real-world examples to include?
-
-**Example questions for an agent**:
-
-- Should this agent trigger proactively after certain actions, or only when explicitly requested?
-- What tools does it need (Read, Write, Bash, etc.)?
-- What should the output format be?
-- Any specific quality standards to enforce?
-
-**Output**: Detailed specification for each component
-
----
-
-## Phase 4: Plugin Structure Creation
-
-**Goal**: Create plugin directory structure and manifest
-
-**Actions**:
-
-1. Determine plugin name (kebab-case, descriptive)
-2. Choose plugin location:
-   - Ask user: "Where should I create the plugin?"
-   - Offer options: current directory, ../new-plugin-name, custom path
-3. Create directory structure using bash:
-   ```bash
-   mkdir -p plugin-name/.agents
-   mkdir -p plugin-name/skills     # passive + invocable skills (no commands/ dir)
-   mkdir -p plugin-name/agents     # if needed
-   mkdir -p plugin-name/hooks      # if needed
-   ```
-4. Create **canonical** `.agents/plugin.json` (see `plugin-structure` skill and `spec/enact.json`). Declare only the components that exist on disk — an undeclared dir silently fails to install, and a declared-but-empty component (e.g. `"hooks"` pointing at `{ "hooks": {} }`) is a guard error:
-   ```json
-   {
-     "name": "plugin-name",
-     "version": "0.1.0",
-     "description": "[brief description]",
-     "targets": ["claude", "codex", "cursor"],
-     "skills": "./skills/",
-     "hooks": "./hooks/hooks.json",
-     "mcpServers": "./.mcp.json",
-     "author": { "name": "[author]" }
-   }
-   ```
-   There is no `commands` field — that field is banned by the repo guard.
-5. Sync and validate host manifests:
-   ```bash
-   cd /path/to/plugin-name
-   enact-extensions sync
-   enact-extensions validate
-   ```
-6. Create README.md template
-7. Create .gitignore if needed
-8. Initialize git repo if creating new directory (only `git init` is available; additional git operations are left to the user)
-
-**Output**: Plugin directory structure created and ready for components
-
-**Post-workflow git operations** (user can run after completion):
-
-```bash
-git add .
-git commit -m "feat: initial plugin structure"
-```
-
----
-
-## Phase 5: Component Implementation
-
-**Goal**: Create each component following best practices
-
-**LOAD RELEVANT SKILLS** before implementing each component type:
-
-- Skills (passive + invocable): Load skill-development skill
-- Agents: Load agent-development skill
-- Hooks: Load hook-development skill
-- MCP: Load mcp-integration skill
-- LSP: Load lsp-integration skill
-- Settings: Load plugin-settings skill
-
-**Actions for each component**:
-
-### For Skills
-
-1. Load skill-development skill using Skill tool
-2. For each skill:
-   - Ask user for concrete usage examples (or use from Phase 3)
-   - Plan resources (scripts/, references/, examples/)
-   - Create skill directory structure
-   - Write SKILL.md with:
-     - Third-person description with specific trigger phrases
-     - Lean body (1,500-2,000 words) in imperative form
-     - References to supporting files
-   - Create reference files for detailed content
-   - Create example files for working code
-   - Create utility scripts if needed
-3. Use skill-reviewer agent to validate each skill
-
-### For Invocable Skills (slash entry points — formerly "commands")
-
-1. Load skill-development skill using Skill tool
-2. For each invocable skill, create a normal `skills/<name>/SKILL.md` and:
-   - Give it invocable frontmatter (slash name, `argument-hint`, optional
-     `allowed-tools` kept minimal)
-   - Consume user input via `$ARGUMENTS`
-   - Write the body as instructions FOR Claude (not TO the user)
-   - Provide usage examples; reference passive skills where useful
-   - Use `references/` and `scripts/` for progressive disclosure
-3. Use skill-reviewer agent to validate it like any other skill
-
-### For Agents
-
-1. Load agent-development skill using Skill tool
-2. For each agent, use agent-creator agent:
-   - Provide description of what agent should do
-   - Agent-creator generates: identifier, whenToUse with examples, systemPrompt
-   - Create agent markdown file with frontmatter and system prompt
-   - Add appropriate model, color, and tools
-   - Validate using plugin-validator agent
-
-### For Hooks
-
-1. Load hook-development skill using Skill tool
-2. For each hook:
-   - Create hooks/hooks.json with hook configuration
-   - Prefer prompt-based hooks for complex logic
-   - Use ${CLAUDE_PLUGIN_ROOT} for portability
-   - Create hook scripts if needed (in examples/ not scripts/)
-   - Validate using plugin-validator agent (handles hook schema validation)
-
-### For MCP
-
-1. Load mcp-integration skill using Skill tool
-2. Create .mcp.json configuration with:
-   - Server type (stdio for local, SSE for hosted)
-   - Command and args (with ${CLAUDE_PLUGIN_ROOT})
-   - extensionToLanguage mapping if LSP
-   - Environment variables as needed
-3. Document required env vars in README
-4. Provide setup instructions
-
-### For LSP
-
-1. Load lsp-integration skill using Skill tool
-2. Add lspServers configuration to plugin.json:
-   - Server command and args
-   - extensionToLanguage mapping
-   - Environment variables if needed
-3. Bundle LSP server binary if self-contained
-4. Or document external server installation in README
-5. Test with language files matching configured extensions
-
-### For Settings
-
-1. Load plugin-settings skill using Skill tool
-2. Create settings template in README
-3. Create example .claude/plugin-name.local.md file (as documentation)
-4. Implement settings reading in hooks/skills as needed
-5. Add to .gitignore: `.claude/*.local.md`
-
-**Progress tracking**: Update tasks as each component is completed
-
-**Output**: All plugin components implemented
-
----
-
-## Phase 6: Validation & Quality Check
-
-**Goal**: Ensure plugin meets quality standards and works correctly
-
-**Actions**:
-
-1. **Run plugin-validator agent**:
-   - Use plugin-validator agent to comprehensively validate plugin
-   - Check: manifest, structure, naming, components, security
-   - Review validation report
-
-2. **Fix critical issues**:
-   - Address any critical errors from validation
-   - Fix any warnings that indicate real problems
-
-3. **Review with skill-reviewer** (if plugin has skills):
-   - For each skill, use skill-reviewer agent
-   - Check description quality, progressive disclosure, writing style
-   - Apply recommendations
-
-4. **Test agent triggering** (if plugin has agents):
-   - For each agent, verify <example> blocks are clear
-   - Check triggering conditions are specific
-   - Verify via plugin-validator agent
-
-5. **Test hook configuration** (if plugin has hooks):
-   - Validate via plugin-validator agent (checks hook schema and scripts)
-   - Verify ${CLAUDE_PLUGIN_ROOT} usage
-
-6. **Present findings**:
-   - Summary of validation results
-   - Any remaining issues
-   - Overall quality assessment
-
-7. **Ask user**: "Validation complete. Issues found: [count critical], [count warnings]. Would you like me to fix them now, or proceed to testing?"
-
-**Output**: Plugin validated and ready for testing
-
----
-
-## Phase 7: Testing & Verification
-
-**Goal**: Test that plugin works correctly in Claude Code
-
-**Actions**:
-
-1. **Installation instructions**:
-   - Show user how to test locally:
-     ```bash
-     claude --plugin-dir /path/to/plugin-name
-     ```
-   - Or copy to `.claude-plugin/` for project testing
-
-2. **Verification checklist** for user to perform:
-   - [ ] Skills load when triggered (ask questions with trigger phrases)
-   - [ ] Invocable skills appear in `/help` and execute correctly
-   - [ ] Agents trigger on appropriate scenarios
-   - [ ] Hooks activate on events (if applicable)
-   - [ ] MCP servers connect (if applicable)
-   - [ ] Settings files work (if applicable)
-
-3. **Testing recommendations**:
-   - For skills: Ask questions using trigger phrases from descriptions
-   - For invocable skills: Run `/plugin-name:skill-name` with various arguments
-   - For agents: Create scenarios matching agent examples
-   - For hooks: Use `claude --debug` to see hook execution
-   - For MCP: Use `/mcp` to verify servers and tools
-
-4. **Ask user**: "I've prepared the plugin for testing. Would you like me to guide you through testing each component, or do you want to test it yourself?"
-
-5. **If user wants guidance**, walk through testing each component with specific test cases
-
-**Output**: Plugin tested and verified working
-
----
-
-## Phase 8: Documentation & Next Steps
-
-**Goal**: Ensure plugin is well-documented and ready for distribution
-
-**Actions**:
-
-1. **Verify README completeness**:
-   - Check README has: overview, features, installation, prerequisites, usage
-   - For MCP plugins: Document required environment variables
-   - For hook plugins: Explain hook activation
-   - For settings: Provide configuration templates
-
-2. **Ask about marketplace publishing**:
-   - Ask user: "Would you like to publish this plugin to a marketplace?"
-   - If yes, proceed with marketplace integration
-   - If no, skip to step 4
-
-3. **Marketplace integration** (if publishing):
-   - Load marketplace-structure skill using Skill tool
-   - Determine target marketplace:
-     - Ask: "Which marketplace? (existing marketplace path, create new, or skip)"
-   - If existing marketplace:
-     - Read marketplace.json
-     - Draft plugin entry:
-
-       ```json
-       {
-         "name": "[plugin-name]",
-         "source": "[relative-path-or-github]",
-         "description": "[from plugin.json]",
-         "version": "[from plugin.json]",
-         "category": "[suggest based on plugin type]"
-       }
-       ```
-
-     - Show diff of marketplace.json before/after addition
-     - Ask user to confirm entry
-     - Update marketplace.json with new plugin entry
-     - Update marketplace metadata.version (bump patch version)
-
-   - If create new marketplace:
-     - Suggest using the `/plugin-dev:create-marketplace` skill
-     - Or create minimal marketplace.json with this plugin as first entry
-   - Validate marketplace after update using plugin-validator agent
-
-4. **Create summary**:
-   - Mark all tasks complete
-   - List what was created:
-     - Plugin name and purpose
-     - Components created (X skills incl. invocable, Y agents, etc.)
-     - Key files and their purposes
-     - Total file count and structure
-   - If added to marketplace:
-     - Marketplace name and location
-     - Plugin entry details
-   - Next steps:
-     - Testing recommendations
-     - Publishing to marketplace (if not done)
-     - Iteration based on usage
-
-5. **Suggest improvements** (optional):
-   - Additional components that could enhance plugin
-   - Integration opportunities
-   - Testing strategies
-
-**Output**: Complete, documented plugin ready for use or publication
-
----
-
-## Important Notes
-
-### Throughout All Phases
-
-- **Use Task tools** to track progress at every phase (TaskCreate, TaskUpdate, TaskList)
-- **Load skills with Skill tool** when working on specific component types
-- **Use specialized agents** (agent-creator, plugin-validator, skill-reviewer)
-- **Ask for user confirmation** at key decision points
-- **Follow plugin-dev's own patterns** as reference examples
-- **Apply best practices**:
-  - Third-person descriptions for skills
-  - Imperative form in skill bodies
-  - Commands written FOR Claude
-  - Strong trigger phrases
-  - ${CLAUDE_PLUGIN_ROOT} for portability
-  - Progressive disclosure
-  - Security-first (HTTPS, no hardcoded credentials)
-
-### Key Decision Points (Wait for User)
-
-1. After Phase 1: Confirm plugin purpose
-2. After Phase 2: Approve component plan
-3. After Phase 3: Proceed to implementation
-4. After Phase 6: Fix issues or proceed
-5. After Phase 7: Continue to documentation
-
-### Skills to Load by Phase
-
-- **Phase 2**: plugin-structure
-- **Phase 5**: skill-development, agent-development, hook-development, mcp-integration, lsp-integration, plugin-settings (as needed)
-- **Phase 6**: (agents will use skills automatically)
-- **Phase 8**: marketplace-structure (if publishing to marketplace)
-
-### Quality Standards
-
-Every component must meet these standards:
-
-- ✅ Follows plugin-dev's proven patterns
-- ✅ Uses correct naming conventions
-- ✅ Has strong trigger conditions (skills/agents)
-- ✅ Includes working examples
-- ✅ Properly documented
-- ✅ Validated with utilities
-- ✅ Tested in Claude Code
-
----
-
-## Example Workflow
-
-### User Request
-
-"Create a plugin for managing database migrations"
-
-### Phase 1: Discovery
-
-- Understand: Migration management, database schema versioning
-- Confirm: User wants to create, run, rollback migrations
-
-### Phase 2: Component Planning
-
-- Skills: 1 (migration best practices)
-- Invocable skills: 3 (create-migration, run-migrations, rollback)
-- Agents: 1 (migration-validator)
-- MCP: 1 (database connection)
-
-### Phase 3: Clarifying Questions
-
-- Which databases? (PostgreSQL, MySQL, etc.)
-- Migration file format? (SQL, code-based?)
-- Should agent validate before applying?
-- What MCP tools needed? (query, execute, schema)
-
-### Phase 4-8: Implementation, Validation, Testing, Documentation
-
----
-
-Begin with Phase 1: Discovery.