dotharness/dotcraft/plugin-creator

Plugin Creator

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

For a managed .NET extension, read references/dotnet-authoring.md and use the .NET authoring mode. For a Desktop extension, 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>, which comes with this workspace:

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 ~/.craft/plugins for a plugin available in every workspace:

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 extension 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 extensions 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 in-process behavior, such as native Tools, through the .NET extension contribution points.
• 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.