@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.1

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

@@ -0,0 +1,705 @@
+---
+name: plugin-structure
+description: Use when the user asks to create/scaffold a plugin, understand Enact multi-platform plugin structure, set up plugin.json manifests, organize skills/commands/hooks, validate plugins, or configure Claude/Codex/Cursor plugin layouts.
+---
+
+# Enact multi-platform plugin structure
+
+## Overview
+
+Enact plugins use **one component tree** and **multiple host manifests**. Edit the canonical Enact manifest, then sync derived copies.
+
+**Key concepts:**
+
+- Canonical manifest: `.agents/plugin.json` (see `spec/enact.json`)
+- Derived manifests: `.claude-plugin/`, `.codex-plugin/`, `.cursor-plugin/` — same `skills/`, `commands/`, `hooks/`
+- Regenerate hosts: `enact-extensions sync` (from plugin root; cwd default)
+- Validate all: `enact-extensions validate`
+
+## Directory structure (all hosts)
+
+```
+plugin-name/
+├── .agents/
+│   └── plugin.json          # Canonical Enact manifest (source of truth)
+├── .claude-plugin/plugin.json
+├── .codex-plugin/plugin.json
+├── .cursor-plugin/plugin.json
+├── skills/
+│   └── skill-name/SKILL.md
+├── commands/                # Slash commands (optional)
+├── agents/                  # Subagents (optional)
+├── hooks/hooks.json
+├── .mcp.json
+└── assets/                  # logos (optional)
+```
+
+**Critical rules:**
+
+1. **Components live at plugin root** — never inside `.agents/` or host manifest dirs (only `plugin.json` goes there).
+2. **One copy** of `skills/`, `commands/`, `hooks/` — do not duplicate per host.
+3. **kebab-case** names for dirs, skills, and plugin `name`.
+4. Set `targets` in `.agents/plugin.json`: `["claude","codex","cursor"]` as needed.
+
+## Canonical manifest (`.agents/plugin.json`)
+
+Required: `name`. Recommended: `version`, `description`, `targets`, component paths, `interface` (registry UI), `factory` (Enact Factory plugins).
+
+```json
+{
+  "name": "my-plugin",
+  "version": "0.1.0",
+  "description": "What this plugin does",
+  "targets": ["claude", "codex", "cursor"],
+  "skills": "./skills/",
+  "commands": "./commands/",
+  "hooks": "./hooks/hooks.json",
+  "mcpServers": "./.mcp.json"
+}
+```
+
+Schemas: `spec/*.json`.
+
+---
+
+## Claude Code specifics
+
+Claude loads `.claude-plugin/plugin.json`. Portable paths may use `${CLAUDE_PLUGIN_ROOT}` in hooks and scripts.
+
+Legacy single-host layout (still valid if you only ship Claude):
+
+```
+plugin-name/
+├── .claude-plugin/plugin.json
+├── commands/
+├── skills/
+└── hooks/hooks.json
+```
+
+## Plugin manifest (Claude-only reference)
+
+For Claude-only plugins, the manifest lives at `.claude-plugin/plugin.json`:
+
+### Required Fields
+
+```json
+{
+  "name": "plugin-name"
+}
+```
+
+**Name requirements:**
+
+- Use kebab-case format (lowercase with hyphens)
+- Must be unique across installed plugins
+- No spaces or special characters
+- Example: `code-review-assistant`, `test-runner`, `api-docs`
+
+### Recommended Metadata
+
+```json
+{
+  "name": "plugin-name",
+  "version": "1.0.0",
+  "description": "Brief explanation of plugin purpose",
+  "author": {
+    "name": "Author Name",
+    "email": "author@example.com",
+    "url": "https://example.com"
+  },
+  "homepage": "https://docs.example.com",
+  "repository": "https://github.com/user/plugin-name",
+  "license": "MIT",
+  "keywords": ["testing", "automation", "ci-cd"]
+}
+```
+
+**Version format**: Follow semantic versioning (MAJOR.MINOR.PATCH)
+**Keywords**: Use for plugin discovery and categorization
+
+### Component Path Configuration
+
+Specify custom paths for components (supplements default directories):
+
+```json
+{
+  "name": "plugin-name",
+  "commands": "./custom-commands",
+  "agents": ["./agents", "./specialized-agents"],
+  "hooks": "./config/hooks.json",
+  "mcpServers": "./.mcp.json"
+}
+```
+
+**Important**: Custom paths supplement defaults—they don't replace them. Components in both default directories and custom paths will load.
+
+**Path rules:**
+
+- Must be relative to plugin root
+- Must start with `./`
+- Cannot use absolute paths
+- Support arrays for multiple locations
+
+## Component Organization
+
+### Commands
+
+**Location**: `commands/` directory
+**Format**: Markdown files with YAML frontmatter
+**Auto-discovery**: All `.md` files in `commands/` load automatically
+
+Simple, user-invocable prompts stored as single `.md` files. Use when you don't need bundled resources. Both commands and skills are invoked via the Skill tool—commands are essentially simple skills.
+
+**Example structure**:
+
+```
+commands/
+├── review.md        # /review command
+├── test.md          # /test command
+└── deploy.md        # /deploy command
+```
+
+**File format**:
+
+```markdown
+---
+name: command-name
+description: Command description
+---
+
+Command implementation instructions...
+```
+
+**Usage**: Commands integrate as native slash commands in Claude Code
+
+### Agents
+
+**Location**: `agents/` directory
+**Format**: Markdown files with YAML frontmatter
+**Auto-discovery**: All `.md` files in `agents/` load automatically
+
+**Example structure**:
+
+```
+agents/
+├── code-reviewer.md
+├── test-generator.md
+└── refactorer.md
+```
+
+**File format**:
+
+```markdown
+---
+description: Agent role and expertise
+capabilities:
+  - Specific task 1
+  - Specific task 2
+---
+
+Detailed agent instructions and knowledge...
+```
+
+**Usage**: Users can invoke agents manually, or Claude Code selects them automatically based on task context
+
+### Skills
+
+**Location**: `skills/` directory with subdirectories per skill
+**Format**: Each skill in its own directory with `SKILL.md` file
+**Auto-discovery**: All `SKILL.md` files in skill subdirectories load automatically
+
+Complex prompts with bundled resources (scripts, references, examples). Use when you need progressive disclosure or supporting files. Both skills and commands are invoked via the Skill tool.
+
+**Example structure**:
+
+```
+skills/
+├── api-testing/
+│   ├── SKILL.md
+│   ├── scripts/
+│   │   └── test-runner.py
+│   └── references/
+│       └── api-spec.md
+└── database-migrations/
+    ├── SKILL.md
+    └── examples/
+        └── migration-template.sql
+```
+
+**SKILL.md format**:
+
+```markdown
+---
+name: Skill Name
+description: When to use this skill
+---
+
+Skill instructions and guidance...
+```
+
+**Tool restrictions** (optional): Skills can include `allowed-tools` in frontmatter to limit tool access:
+
+```yaml
+---
+name: safe-reader
+description: Read-only file access skill
+allowed-tools: Read, Grep, Glob # Optional: restricts available tools
+---
+```
+
+Use for read-only workflows, security-sensitive tasks, or limited-scope operations.
+
+**Supporting files**: Skills can include scripts, references, examples, or assets in subdirectories
+
+**Usage**: Claude Code autonomously activates skills based on task context matching the description
+
+### Hooks
+
+**Location**: `hooks/hooks.json` or inline in `plugin.json`
+**Format**: JSON configuration defining event handlers
+**Registration**: Hooks register automatically when plugin enables
+
+**Example structure**:
+
+```
+hooks/
+├── hooks.json           # Hook configuration
+└── scripts/
+    ├── validate.sh      # Hook script
+    └── check-style.sh   # Hook script
+```
+
+**Configuration format**:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validate.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Available events**: PreToolUse, PermissionRequest, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification
+
+**Usage**: Hooks execute automatically in response to Claude Code events
+
+### MCP Servers
+
+**Location**: `.mcp.json` at plugin root or inline in `plugin.json`
+**Format**: JSON configuration for MCP server definitions
+**Auto-start**: Servers start automatically when plugin enables
+
+**Example format**:
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/server.js"],
+      "env": {
+        "API_KEY": "${API_KEY}"
+      }
+    }
+  }
+}
+```
+
+**Usage**: MCP servers integrate seamlessly with Claude Code's tool system
+
+### LSP Servers
+
+**Location**: Inline in `plugin.json` under `lspServers` field
+**Format**: JSON configuration for Language Server Protocol servers
+**Auto-start**: Servers start when files matching extensions are opened
+
+**Example format**:
+
+```json
+{
+  "lspServers": {
+    "python": {
+      "command": "pyright-langserver",
+      "args": ["--stdio"],
+      "extensionToLanguage": {
+        ".py": "python",
+        ".pyi": "python"
+      }
+    }
+  }
+}
+```
+
+**Usage**: LSP servers provide code intelligence (go-to-definition, find references, hover)
+
+For detailed LSP configuration, see the `lsp-integration` skill.
+
+### Output Styles
+
+**Location**: Path reference in `plugin.json` under `outputStyles` field
+**Format**: String path or array of paths to style files/directories
+**Purpose**: Customize how Claude formats responses
+
+**Example format**:
+
+```json
+{
+  "outputStyles": "./styles/"
+}
+```
+
+Or with multiple paths:
+
+```json
+{
+  "outputStyles": ["./styles/default.md", "./styles/compact.md"]
+}
+```
+
+**Usage**: Plugins can define consistent output formatting for their domain. Style files in the referenced path are loaded to customize Claude's output behavior.
+
+For comprehensive output styles guidance including frontmatter schema, file locations, and when to use styles vs other components, see `references/output-styles.md`.
+
+## Portable Path References
+
+### ${CLAUDE_PLUGIN_ROOT}
+
+Use `${CLAUDE_PLUGIN_ROOT}` environment variable for all intra-plugin path references:
+
+```json
+{
+  "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/run.sh"
+}
+```
+
+**Why it matters**: Plugins install in different locations depending on:
+
+- User installation method (marketplace, local, npm)
+- Operating system conventions
+- User preferences
+
+**Where to use it**:
+
+- Hook command paths
+- MCP server command arguments
+- Script execution references
+- Resource file paths
+
+**Never use**:
+
+- Hardcoded absolute paths (`/Users/name/plugins/...`)
+- Relative paths from working directory (`./scripts/...` in commands)
+- Home directory shortcuts (`~/plugins/...`)
+
+### Path Resolution Rules
+
+**In manifest JSON fields** (hooks, MCP servers):
+
+```json
+"command": "${CLAUDE_PLUGIN_ROOT}/scripts/tool.sh"
+```
+
+**In component files** (commands, agents, skills):
+
+```markdown
+Reference scripts at: ${CLAUDE_PLUGIN_ROOT}/scripts/helper.py
+```
+
+**In executed scripts**:
+
+```bash
+#!/bin/bash
+# ${CLAUDE_PLUGIN_ROOT} available as environment variable
+source "${CLAUDE_PLUGIN_ROOT}/lib/common.sh"
+```
+
+## File Naming Conventions
+
+### Component Files
+
+**Commands**: Use kebab-case `.md` files
+
+- `code-review.md` → `/code-review`
+- `run-tests.md` → `/run-tests`
+- `api-docs.md` → `/api-docs`
+
+**Agents**: Use kebab-case `.md` files describing role
+
+- `test-generator.md`
+- `code-reviewer.md`
+- `performance-analyzer.md`
+
+**Skills**: Use kebab-case directory names
+
+- `api-testing/`
+- `database-migrations/`
+- `error-handling/`
+
+### Supporting Files
+
+**Scripts**: Use descriptive kebab-case names with appropriate extensions
+
+- `validate-input.sh`
+- `generate-report.py`
+- `process-data.js`
+
+**Documentation**: Use kebab-case markdown files
+
+- `api-reference.md`
+- `migration-guide.md`
+- `best-practices.md`
+
+**Configuration**: Use standard names
+
+- `hooks.json`
+- `.mcp.json`
+- `plugin.json`
+
+## Auto-Discovery Mechanism
+
+Claude Code automatically discovers and loads components:
+
+1. **Plugin manifest**: Reads `.claude-plugin/plugin.json` when plugin enables
+2. **Commands**: Scans `commands/` directory for `.md` files
+3. **Agents**: Scans `agents/` directory for `.md` files
+4. **Skills**: Scans `skills/` for subdirectories containing `SKILL.md`
+5. **Hooks**: Loads configuration from `hooks/hooks.json` or manifest
+6. **MCP servers**: Loads configuration from `.mcp.json` or manifest
+
+**Discovery timing**:
+
+- Plugin installation: Components register with Claude Code
+- Plugin enable: Components become available for use
+- No restart required: Changes take effect on next Claude Code session
+
+**Override behavior**: Custom paths in `plugin.json` supplement (not replace) default directories
+
+## Best Practices
+
+### Organization
+
+1. **Logical grouping**: Group related components together
+   - Put test-related commands, agents, and skills together
+   - Create subdirectories in `scripts/` for different purposes
+
+2. **Minimal manifest**: Keep `plugin.json` lean
+   - Only specify custom paths when necessary
+   - Rely on auto-discovery for standard layouts
+   - Use inline configuration only for simple cases
+
+3. **Documentation**: Include README files
+   - Plugin root: Overall purpose and usage
+   - Component directories: Specific guidance
+   - Script directories: Usage and requirements
+
+### Naming
+
+1. **Consistency**: Use consistent naming across components
+   - If command is `test-runner`, name related agent `test-runner-agent`
+   - Match skill directory names to their purpose
+
+2. **Clarity**: Use descriptive names that indicate purpose
+   - Good: `api-integration-testing/`, `code-quality-checker.md`
+   - Avoid: `utils/`, `misc.md`, `temp.sh`
+
+3. **Length**: Balance brevity with clarity
+   - Commands: 2-3 words (`review-pr`, `run-ci`)
+   - Agents: Describe role clearly (`code-reviewer`, `test-generator`)
+   - Skills: Topic-focused (`error-handling`, `api-design`)
+
+### Portability
+
+1. **Always use ${CLAUDE_PLUGIN_ROOT}**: Never hardcode paths
+2. **Test on multiple systems**: Verify on macOS, Linux, Windows
+3. **Document dependencies**: List required tools and versions
+4. **Avoid system-specific features**: Use portable bash/Python constructs
+
+### Maintenance
+
+1. **Version consistently**: Update version in plugin.json for releases
+2. **Deprecate gracefully**: Mark old components clearly before removal
+3. **Document breaking changes**: Note changes affecting existing users
+4. **Test thoroughly**: Verify all components work after changes
+
+## Common Patterns
+
+### Minimal Plugin
+
+Single command with no dependencies:
+
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json    # Just name field
+└── commands/
+    └── hello.md       # Single command
+```
+
+### Full-Featured Plugin
+
+Complete plugin with all component types:
+
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+├── commands/          # User-facing commands
+├── agents/            # Specialized subagents
+├── skills/            # Auto-activating skills
+├── hooks/             # Event handlers
+│   ├── hooks.json
+│   └── scripts/
+├── .mcp.json          # External integrations
+└── scripts/           # Shared utilities
+```
+
+### Skill-Focused Plugin
+
+Plugin providing only skills:
+
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+└── skills/
+    ├── skill-one/
+    │   └── SKILL.md
+    └── skill-two/
+        └── SKILL.md
+```
+
+## Plugin Caching
+
+Claude Code caches plugin content for performance. Understanding caching behavior helps with development and debugging.
+
+### What Gets Cached
+
+- Plugin manifest (plugin.json)
+- Component files (commands, agents, skills)
+- Configuration files (hooks.json, .mcp.json)
+
+### Cache Invalidation
+
+Cached content refreshes when:
+
+- Claude Code session restarts
+- Plugin is reinstalled or updated
+- User runs `/plugins refresh` (if available)
+
+### Why External Paths Fail
+
+**Important:** Paths outside the plugin directory may not work reliably because:
+
+1. **Security boundary** - Plugins are sandboxed to their directory
+2. **Caching** - External paths aren't monitored for changes
+3. **Portability** - External paths break on different machines
+
+**Always use:**
+
+- `${CLAUDE_PLUGIN_ROOT}` for paths within the plugin
+- Bundled resources instead of external file references
+- Environment variables for user-specific paths
+
+### Development Workflow
+
+During development, reload plugins by:
+
+1. Exiting Claude Code
+2. Making changes to plugin files
+3. Restarting Claude Code
+
+Or use `--plugin-dir` for testing without installation:
+
+```bash
+claude --plugin-dir /path/to/plugin
+```
+
+## Runtime Contexts
+
+Plugins behave differently depending on the runtime context. Interactive sessions support slash commands and user prompts; headless mode (`claude -p`) and GitHub Actions provide non-interactive environments where some features are unavailable.
+
+- **Headless/CI mode:** See `references/headless-ci-mode.md` for designing plugins that work in `claude -p` and CI pipelines
+- **GitHub Actions:** See `references/github-actions.md` for integrating plugins with `claude-code-action@v1`
+- **Advanced topics:** See `references/advanced-topics.md` for caching behavior, installation scopes, CLI management, keybindings, status line, and auto-update behavior
+
+## Plugin Validation
+
+Claude Code provides built-in validation tools:
+
+- **`claude plugin validate`** (CLI) / **`/plugin validate`** (TUI): Validates plugin and marketplace structure, checking JSON syntax, required fields, component discovery, and path resolution
+- **`claude --debug`**: Shows detailed plugin loading logs, including which components were discovered, registration errors, and hook execution details
+- **`claude --verbose`**: Use `--verbose` for additional debugging output during plugin loading, including hook registration and MCP server connections
+- **`/plugins`**: View installed plugins, their status, and any errors in the Errors tab
+
+Use validation early and often during development.
+
+### Additional Source Types
+
+Beyond relative paths and git sources, plugins can also be installed from:
+
+- **npm**: `claude plugin install npm-package-name`
+- **pip**: `claude plugin install pip-package-name`
+
+These package managers handle versioning and dependency resolution automatically.
+
+## Troubleshooting
+
+**Component not loading**:
+
+- Verify file is in correct directory with correct extension
+- Check YAML frontmatter syntax (commands, agents, skills)
+- Ensure skill has `SKILL.md` (not `README.md` or other name)
+- Confirm plugin is enabled in Claude Code settings
+
+**Path resolution errors**:
+
+- Replace all hardcoded paths with `${CLAUDE_PLUGIN_ROOT}`
+- Verify paths are relative and start with `./` in manifest
+- Check that referenced files exist at specified paths
+- Test with `echo $CLAUDE_PLUGIN_ROOT` in hook scripts
+
+**Auto-discovery not working**:
+
+- Confirm directories are at plugin root (not in `.claude-plugin/`)
+- Check file naming follows conventions (kebab-case, correct extensions)
+- Verify custom paths in manifest are correct
+- Restart Claude Code to reload plugin configuration
+
+**Conflicts between plugins**:
+
+- Use unique, descriptive component names
+- Namespace commands with plugin name if needed
+- Document potential conflicts in plugin README
+- Consider command prefixes for related functionality
+
+---
+
+## Additional Resources
+
+### Reference Files
+
+- **`references/component-patterns.md`** - Detailed patterns for each component type
+- **`references/manifest-reference.md`** - Complete plugin.json field reference
+- **`references/headless-ci-mode.md`** - Headless and CI mode plugin compatibility
+- **`references/github-actions.md`** - GitHub Actions integration for plugins
+- **`references/advanced-topics.md`** - Caching, installation scopes, CLI commands, and more
+- **`references/output-styles.md`** - Output style frontmatter schema, file locations, and usage guidance
+
+### Example Files
+
+Working examples in `examples/`:
+
+- **`minimal-plugin.md`** - Single command plugin structure
+- **`standard-plugin.md`** - Typical plugin with multiple components
+- **`advanced-plugin.md`** - Full-featured plugin with all component types