name	xpert-plugin-development
description	Guidance for developing, installing, testing, versioning, and submitting Xpert plugins. Use this skill when working in xpert-plugins on general plugins, model plugins, skill-only plugins, integrations, middlewares, plugin-managed MCP tools, or MCP Apps.

Xpert Plugin Development

Use this skill when the task involves plugin work in the Xpert plugin repository:

creating a new plugin
updating an existing plugin
installing a local plugin into the platform
validating plugin config, runtime behavior, or packaging
developing plugin-managed MCP tools or MCP Apps
preparing commits, version updates, or PRs

Repository:

Official upstream: https://github.com/xpert-ai/xpert-plugins.git
Local plugin repository root: discover from the current workspace instead of assuming a fixed absolute path
Local platform backend root: discover from the current workspace instead of assuming a fixed absolute path

Workflow

Identify the plugin type first: general tool plugin, model plugin, integration plugin, middleware plugin, skill-only plugin, plugin-managed MCP server, or MCP App plugin.
Discover the actual local paths for the plugin repository, the target plugin directory, and the platform backend before running commands.
Read references/general.md for repository layout, install flow, test flow, versioning, and PR rules.
If the task is about model providers, yaml, assets, or packaging, also read references/model-plugins.md.
If the task is about callbacks, bindings, notifications, or third-party platform connectivity, also read references/integration-middleware.md.
If the task is about plugin background jobs, BullMQ, delayed/retry jobs, Redis queue state, or multi-tenant queue isolation, also read references/managed-queue.md.
If the task is about plugin file inputs, workspace files, sandbox /workspace paths, file upload/download/send flows, platform file references, or queued file retries, also read references/workspace-files.md.
If the task is about .xpertai-plugin/plugin.json, plugin-managed MCP servers, MCP tool metadata, ui:// resources, MCP Apps, or ChatKit inline app rendering, also read references/mcp-tools-and-apps.md.
If the task is about Xpert skill-only plugins, Codex-to-Xpert skill conversion, skill marketplace cards, skill resource installation, skill document dialogs, or ClawXpert skill trial flows, also read references/skill-only-plugins.md.
Prefer local installation via source=code + workspacePath during development.
Before finishing, verify build output, installation, runtime behavior, and submit only relevant files.

Rules

Keep package metadata, exported entrypoints, schema, and runtime behavior aligned.
Do not commit secrets, tokens, passwords, temporary callback URLs, or local-only debug values.
Do not expose platform capabilities as tools unless the upstream platform APIs are confirmed to exist and are stable enough for users.
Treat createTools() and runtime tool execution as separate contracts and verify both.
When the platform backend code changes, restart the backend before concluding installation or loading is broken.
Do not hardcode machine-specific absolute paths in docs, scripts, or instructions. Use discovered paths or placeholders such as <plugin-repo-root> and <platform-root>.
For plugin-managed MCP servers, use stable manifest placeholders such as ${PLUGIN_ROOT} and ${PLUGIN_DATA} instead of installed runtime paths.
For MCP Apps, keep tool metadata and resource metadata separate: tool _meta.ui carries resourceUri / visibility; resource _meta.ui carries display metadata (title, description, icon) plus CSP, permissions, domain, and prefersBorder.
Treat plugin-managed stdio MCP servers as platform-controlled runtimes: production must be explicitly enabled, commands must be policy-checked, mutable state belongs in ${PLUGIN_DATA}, and MCP App resource/RPC requests must carry the host-issued appInstanceToken.
Style MCP Apps with host-injected CSS variables using the public --mcp-app-* contract. Do not hardcode ChatKit internals, private theme tokens, or tenant-specific colors in iframe HTML.
Localize MCP App iframe UI from the host ui/initialize language context instead of hardcoding one language in app HTML.
Do not use broad TypeScript escape hatches as normal implementation strategy: avoid as any, as unknown as, : any, : unknown, Record<string, any>, untyped callbacks, and untyped test mocks. First inspect the SDK, platform, React, MCP, or domain-library types; import concrete types, derive callback/event shapes with Parameters<> / ReturnType<>, add narrow type guards, or define small boundary DTOs. If a compatibility assertion is unavoidable, isolate it in a named helper at the boundary and keep downstream code typed.
For new plugin background jobs, use the platform Managed Queue abstraction instead of plugin-owned BullMQ queues or Redis connections.

Output expectations

When using this skill, prefer this order:

identify plugin type and affected directories
make the minimum safe code changes
build and validate locally
install or reinstall into the local platform
verify runtime behavior
summarize risks, versioning impact, and PR readiness

Xpert Plugin Development

Use this skill when the task involves plugin work in the Xpert plugin repository:

creating a new plugin

updating an existing plugin

installing a local plugin into the platform

validating plugin config, runtime behavior, or packaging

developing plugin-managed MCP tools or MCP Apps

preparing commits, version updates, or PRs

Repository:

Official upstream: https://github.com/xpert-ai/xpert-plugins.git

Local plugin repository root: discover from the current workspace instead of assuming a fixed absolute path

Local platform backend root: discover from the current workspace instead of assuming a fixed absolute path

Workflow

Identify the plugin type first: general tool plugin, model plugin, integration plugin, middleware plugin, skill-only plugin, plugin-managed MCP server, or MCP App plugin.

Discover the actual local paths for the plugin repository, the target plugin directory, and the platform backend before running commands.

Read references/general.md for repository layout, install flow, test flow, versioning, and PR rules.

If the task is about model providers, yaml, assets, or packaging, also read references/model-plugins.md.

If the task is about callbacks, bindings, notifications, or third-party platform connectivity, also read references/integration-middleware.md.

If the task is about plugin background jobs, BullMQ, delayed/retry jobs, Redis queue state, or multi-tenant queue isolation, also read references/managed-queue.md.

If the task is about plugin file inputs, workspace files, sandbox /workspace paths, file upload/download/send flows, platform file references, or queued file retries, also read references/workspace-files.md.

If the task is about .xpertai-plugin/plugin.json, plugin-managed MCP servers, MCP tool metadata, ui:// resources, MCP Apps, or ChatKit inline app rendering, also read references/mcp-tools-and-apps.md.

If the task is about Xpert skill-only plugins, Codex-to-Xpert skill conversion, skill marketplace cards, skill resource installation, skill document dialogs, or ClawXpert skill trial flows, also read references/skill-only-plugins.md.

Prefer local installation via source=code + workspacePath during development.

Before finishing, verify build output, installation, runtime behavior, and submit only relevant files.

Rules

Keep package metadata, exported entrypoints, schema, and runtime behavior aligned.

Do not commit secrets, tokens, passwords, temporary callback URLs, or local-only debug values.

Do not expose platform capabilities as tools unless the upstream platform APIs are confirmed to exist and are stable enough for users.

Treat createTools() and runtime tool execution as separate contracts and verify both.

When the platform backend code changes, restart the backend before concluding installation or loading is broken.

Do not hardcode machine-specific absolute paths in docs, scripts, or instructions. Use discovered paths or placeholders such as <plugin-repo-root> and <platform-root>.

For plugin-managed MCP servers, use stable manifest placeholders such as ${PLUGIN_ROOT} and ${PLUGIN_DATA} instead of installed runtime paths.

For MCP Apps, keep tool metadata and resource metadata separate: tool _meta.ui carries resourceUri / visibility; resource _meta.ui carries display metadata (title, description, icon) plus CSP, permissions, domain, and prefersBorder.

Treat plugin-managed stdio MCP servers as platform-controlled runtimes: production must be explicitly enabled, commands must be policy-checked, mutable state belongs in ${PLUGIN_DATA}, and MCP App resource/RPC requests must carry the host-issued appInstanceToken.

Style MCP Apps with host-injected CSS variables using the public --mcp-app-* contract. Do not hardcode ChatKit internals, private theme tokens, or tenant-specific colors in iframe HTML.

Localize MCP App iframe UI from the host ui/initialize language context instead of hardcoding one language in app HTML.

Do not use broad TypeScript escape hatches as normal implementation strategy: avoid as any, as unknown as, : any, : unknown, Record<string, any>, untyped callbacks, and untyped test mocks. First inspect the SDK, platform, React, MCP, or domain-library types; import concrete types, derive callback/event shapes with Parameters<> / ReturnType<>, add narrow type guards, or define small boundary DTOs. If a compatibility assertion is unavoidable, isolate it in a named helper at the boundary and keep downstream code typed.

For new plugin background jobs, use the platform Managed Queue abstraction instead of plugin-owned BullMQ queues or Redis connections.

Output expectations

When using this skill, prefer this order:

identify plugin type and affected directories

make the minimum safe code changes

build and validate locally

install or reinstall into the local platform

verify runtime behavior

summarize risks, versioning impact, and PR readiness

xpert-plugin-development