plugin-creator

name	plugin-creator
description	Create and scaffold DotCraft local plugins, including project-local managed .NET plugins, Desktop Plugins, plugin-contained skills, MCP configuration, hooks, and assets. Use when developing or maintaining a DotCraft plugin bundle.

Plugin Creator

Use this skill when the user wants to create, scaffold, or maintain a DotCraft plugin directory.

For a managed .NET plugin, read references/dotnet-authoring.md and use the .NET authoring mode. For a Desktop Plugin, read references/desktop-authoring.md and use --with-desktop. When one plugin needs both, read both references and use --dotnet --with-desktop; the creator generates one bundle and one plugin id. For other plugin contributions, use the local bundle workflow below.

Quick Start

Default to a workspace-local plugin under <workspace>/.craft/plugins/<plugin-id>:

python .craft/skills/plugin-creator/scripts/create_basic_plugin.py "My Plugin"

If reading the skill from the source tree instead of a deployed workspace skill, use the source-tree script path from the repo root:

python src/DotCraft.Core/Skills/BuiltIn/plugin-creator/scripts/create_basic_plugin.py "My Plugin"

Use --path when the user asks for another parent directory, such as a user-global plugin container:

python .craft/skills/plugin-creator/scripts/create_basic_plugin.py "My Plugin" --path "$HOME/.craft/plugins"

Defaults

• Normalize plugin ids to lowercase hyphen-case, max 64 characters.
• Create <parent>/<plugin-id>/.craft-plugin/plugin.json.
• Create a skill plugin by default with skills: "./skills/".
• Create skills/<skill-name>/SKILL.md; --skill-name defaults to the plugin id.
• Add --with-mcp to create a plugin-bundled .mcp.json placeholder.
• Add --with-hooks to create a plugin-bundled hooks/hooks.json placeholder.
• Add --with-desktop to create a source-based Desktop Plugin with one main view, including alongside --dotnet.
• Add --with-assets to create plugin-level icon/logo placeholders.

Manifest Rules

DotCraft schema version 1 allows a plugin to contribute skills, MCP servers, lifecycle hooks, Desktop UI, interface metadata, or a combination of these.

• Skill-only plugins are valid when skills points to a plugin-contained skills directory.
• MCP-only plugins are valid when mcpServers points to a plugin-bundled MCP config or a root .mcp.json exists.
• Hooks-only plugins are valid when hooks points to plugin hook files or a root hooks/hooks.json exists.
• Desktop Plugins declare one inline desktop entry, an optional contribution description, and optional styles inside ./desktop/dist/.
• Interface-only plugins are valid for catalog or UI metadata.
• Managed plugins declare dotnet metadata and contribute native Tools from their C# implementation.
• Manifest fields tools, functions, and processes are unsupported and must not be generated.
• Out-of-process executable capabilities can be exposed through MCP.
• Thread-scoped AppServer client callbacks should use Runtime Dynamic Tools, not plugin manifest fields.
• Manifest-relative paths must start with ./, stay inside the plugin root, and never contain ...

For exact examples, read references/plugin-json-spec.md.

MCP Plugin Template

Use this when creating a plugin that bundles MCP configuration:

python .craft/skills/plugin-creator/scripts/create_basic_plugin.py review-tools --with-mcp

After generation, replace placeholder descriptions and edit .mcp.json to point at the real MCP server command or HTTPS endpoint.

Hooks Plugin Template

Use this when creating a plugin that bundles lifecycle hooks:

python .craft/skills/plugin-creator/scripts/create_basic_plugin.py audit-hooks --without-skill --with-hooks

After generation, replace placeholder descriptions, edit hooks/hooks.json, and update helper scripts under hooks/. Plugin hook commands can use ${DOTCRAFT_PLUGIN_ROOT} and ${DOTCRAFT_PLUGIN_DATA}. First run still requires user trust through Desktop Hooks settings or hooks/setState.

Validation

After scaffolding:

1. Inspect .craft-plugin/plugin.json and replace TODO placeholders.
2. Confirm every manifest-relative path starts with ./.
3. If the plugin has skills, confirm each child skill has SKILL.md.
4. If the plugin has MCP servers, confirm .mcp.json uses the same schema as workspace McpServers.
5. If the plugin has hooks, confirm hooks/hooks.json uses the same shape as .craft/hooks.json.
6. If the plugin has Desktop source, run its build script and confirm the declared files exist under desktop/dist/.
7. If the plugin is managed .NET, use DotNetPlugin.Build and address its compiler or preflight diagnostics.
8. Run relevant DotCraft tests when changing the runtime, or start DotCraft and confirm the expected contributions are active.