WO

wox-plugin-creator

Provides scaffolding and official SDK templates for creating and publishing Wox plugins in Node.js or Python.

Install

mkdir -p .claude/skills/wox-plugin-creator && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/4484" && unzip -o skill.zip -d .claude/skills/wox-plugin-creator && rm skill.zip

Installs to .claude/skills/wox-plugin-creator

Activation

This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.

Create, scaffold, implement, and package Wox plugins (nodejs, python, script-nodejs, script-python). Use when cloning official SDK templates, generating script plugin templates, editing plugin.json metadata, defining SettingDefinitions and validators, wiring i18n, implementing plugin APIs, or preparing plugin repositories for local packaging. If the user wants to publish a plugin to the official Wox store or check whether it is already listed, prefer wox-plugin-submit2store.
479 chars✓ has a “when” triggerlonger than Claude Code's old 250-char listing cap (fine on current versions)
Intermediate

Key capabilities

  • →Scaffold Node.js and Python Wox plugins
  • →Generate single-file script plugins
  • →Replace metadata placeholders in templates
  • →Search and fetch Iconify SVG constants
  • →Validate plugin settings and requirements

How it works

It clones official SDK templates or copies local script templates, then populates metadata placeholders based on user-provided configuration.

Inputs & outputs

You give it
Plugin type, name, and trigger keywords
You get back
Scaffolded plugin directory or single-file script

When to use wox-plugin-creator

  • →Creating a new Wox plugin
  • →Scaffolding a Python Wox plugin
  • →Setting up a Node.js script plugin
  • →Preparing a plugin for distribution

About this skill

Wox Plugin Creator

Quick Start

  • Scaffold a Node.js plugin (clones template repo):
    • python3 scripts/scaffold_wox_plugin.py --type nodejs --output-dir ./MyPlugin --name "My Plugin" --trigger-keywords my
  • Scaffold a Python plugin (clones template repo):
    • python3 scripts/scaffold_wox_plugin.py --type python --output-dir ./MyPlugin --name "My Plugin" --trigger-keywords my
  • Scaffold a single-file SDK plugin (uses local templates; plugin-id auto-generated; writes one file into the live user plugin directory so a running Wox instance can load it immediately). Omit --output-dir; default is ~/.wox/wox-user/plugins/single-file/ (Windows: %USERPROFILE%\.wox\wox-user\plugins\single-file\):
    • Auto-detect this machine: python3 scripts/scaffold_wox_plugin.py --type singlefile --name "Weather" --trigger-keywords weather
    • Explicit Node.js: python3 scripts/scaffold_wox_plugin.py --type singlefile-nodejs --name "Weather" --trigger-keywords weather
    • Explicit Python: python3 scripts/scaffold_wox_plugin.py --type singlefile-python --name "Weather" --trigger-keywords weather

Toolbar status and Toast notifications

Choose the API by lifetime and scope:

  • ShowToolbarMsg / show_toolbar_msg displays immediate status in the current launcher toolbar. It is available while the plugin owns the current context: a trigger-keyword query, a query scoped to this one plugin, or a global query while one of this plugin's results is selected. The same selected-result rule applies to ownerless selection and multi-plugin scoped queries. This includes plugins whose only trigger keyword is *. For global results, use OnEnterPluginQuery / on_enter_plugin_query and its callback context to publish the status once a result is selected; the initial global query runs before selection. Result actions also receive the selected result's context.
  • A toolbar message disappears after 10 seconds by default; each update resets the timer. For ongoing work or actionable errors, set IsPersist: true / is_persist=True and explicitly call ClearToolbarMsg(ctx, id) / clear_toolbar_msg(ctx, id) when it is no longer needed. Wox also automatically clears messages when the user leaves the plugin context. In a global or other ownerless query, selecting another plugin or having no selected result leaves that context; switching between results from the same plugin keeps the message. Preserve the original session and query context for asynchronous updates. If the user leaves a plugin and later returns to it in the same query, an earlier callback can still update the toolbar; name the relevant object in messages about a particular item.
  • ShowToastMsg / show_toast_msg displays an independent global notification and does not require an active plugin context. Use it for one-off events and optional notification actions. The legacy Notify / notify API is deprecated and also displays a Toast.

Choose a plugin type

  • Single-file SDK plugin: one .py or CommonJS .js file with full Public API, loaded into the existing Python/Node runtime host. No extra process per query. Create and edit only ~/.wox/wox-user/plugins/single-file/Wox.Plugin.<Name>.js (or .py); Wox watches that directory and reloads on save. Requires Wox 2.4.2+; header MinWoxVersion must be "2.4.2".
  • SDK plugin (.wox): multi-file package with dependencies, resources, TypeScript, and plugin.json.

Node.js first version must stay CommonJS (module.exports.plugin) and must not import @wox-launcher/wox-plugin.

Choose a runtime language

Honor an explicit Python or Node.js request from the user, including a .py or .js output filename.

When the user does not specify a language, detect this machine before scaffolding. Do not default to Python.

  1. Run python3 scripts/detect_local_runtime.py (use python if python3 is missing). It prints nodejs, python, or none.
  2. If that script cannot run, check the floors yourself: node --version for Node.js 20+, and python3 --version for Python 3.10+. On Windows also try py -3 --version and python --version.
  3. Decision:
    • Only one runtime meets the floor → use that runtime
    • Both meet the floor → use Node.js
    • Neither meets the floor → ask the user which language they want
  4. Map the choice to --type: singlefile-nodejs / singlefile-python, or nodejs / python. --type singlefile applies the same detection inside the scaffold.

Workflow

1) Scaffold plugin files

  • Use scripts/scaffold_wox_plugin.py for nodejs, python, singlefile, singlefile-python, or singlefile-nodejs.
  • Pass --name and --trigger-keywords for every runtime. The scaffold exits without them. --output-dir is required for packaged SDK plugins; omit it for single-file SDK plugins so the file lands in ~/.wox/wox-user/plugins/single-file/.
  • For Node.js and Python packages, the scaffold clones the official template repos and replaces placeholders like {{.ID}}, {{.Name}}, {{.Description}}, {{.TriggerKeywordsJSON}}, {{.Author}}.
  • Before starting work in a new SDK plugin project, run make init in the project root when the project has not been initialized yet.
  • Single-file SDK plugins are single-file host-loaded plugins. Prefer filenames like Wox.Plugin.<Name>.js or Wox.Plugin.<Name>.py.
  • Single-file SDK destination: create and implement the plugin as one file in ~/.wox/wox-user/plugins/single-file/ (Windows: %USERPROFILE%\.wox\wox-user\plugins\single-file\). That directory is what a running Wox instance loads; saving reloads after about 500ms, so the user can query the trigger keyword immediately. Omit --output-dir when using the scaffold, or write the file there directly from assets/single_file_plugin_templates/. Do not also create a copy under the current repository (plugins/, workspace root, or a new folder). Pass --output-dir only when the user asks for a different path.
  • Do not put companion files (*.test.js, README, extra modules) in the live directory. Wox loads every .js and .py there as a plugin.
  • Single-file SDK plugins must set header MinWoxVersion to "2.4.2". The scaffold applies this default when --min-wox-version is omitted. Do not lower it; Wox 2.4.2 is the first release that can load this plugin type, and store/CI reject older floors.
  • For single-file SDK plugins, the scaffold copies templates from ~/.wox/ai/skills/wox-plugin-creator/assets/single_file_plugin_templates/ (or the repo .agents/skills/wox-plugin-creator/assets/single_file_plugin_templates/ fallback).
  • Prefer standard library features; avoid third-party dependencies unless absolutely necessary. Single-file SDK plugins cannot use pip/npm packages.
  • For SDK usage and API details, read references/sdk_nodejs.md or references/sdk_python.md.
  • For plugins declaring querySelection, return results only for selection types and content the plugin can process. Return an empty results list for unsupported, missing, or empty selection data instead of showing usage or help rows for unrelated selections.
  • Keep a result on the row. Title is the name to scan. SubTitle is one short identity line, such as a code, place, or source. Tails are the few facts that must stay visible, such as a price and its change. Use at most three tail tags on one result. A fourth tag can be clipped, so part of a tag is not shown. Put any further fact in the subtitle, the copied text, or a preview. Do not add Preview for a quote, status, short record, or anything that fits on that row.
  • A durable result must set IdentityKey (Python identity_key, script JSON identity_key). Wox uses it for usage history, query pins, and MRU. The value must identify that one result and no other result from the plugin, and it must stay the same when the title, subtitle, translation, score, or query text changes. Use the item's own id, such as a path, URL, note id, command id, or record id. Do not use the visible title, a translated string, the current query, a random id, or one shared key for a whole list. The same item returned from search and from MRU restore must use the same key. score_key / ScoreKey is only the older name. Omit IdentityKey on a temporary result: a prompt, an empty or error state, a one-time status, or a row that exists only for the current selection or query and will not be pinned or restored.
  • Give every result action a unique Id (id in Python) across results and query invocations, including execute and form actions. Older plugin hosts cache callbacks by action ID alone, so reusing an ID such as open can execute another result's callback. For new SDK result actions, prefer omitting the ID and letting the host generate it; create a fresh action object for each result and query. When an explicit ID is needed, use a UUID or combine a unique query ID, result identity, and action kind. Keep the ID for the lifetime of the displayed action when using UpdateResult / update_result, especially when preserving an existing callback; use action context data for stable business identity instead. This rule concerns action IDs, not result IDs or the stable IdentityKey above. If a fixed ID is essential, verify the supported host versions and ensure callbacks cannot collide.
  • A text tail already has a theme-aware rounded container. Use an SVG image tail only when that tag must also contain an icon. Match the launcher metrics below, and see Simulated tail tags.
  • Refresh a visible row in place with UpdateResult / update_result. Remember the results returned by the latest query(). Replace that list on the next query. When a background refresh or an action changes a row that is still on screen, call UpdateResult with the same result Id and only the fields that changed (Title, SubTitle, Icon, Tails, Actions). The query text stays put and the list does not

Content truncated.

When not to use it

  • →When the user wants to submit a plugin to the official store
  • →When the user is editing an existing plugin without scaffolding

Prerequisites

python3

Limitations

  • →Requires --name and --trigger-keywords for all runtimes
  • →Script plugins are limited to single-file implementations

How it compares

It automates the creation of standard plugin structures and metadata, ensuring consistency compared to manual file creation.

Compared to similar skills

wox-plugin-creator side by side with the closest alternatives in the catalog.

SkillInstallsUpdatedSafetyDifficulty
wox-plugin-creator (this skill)15moReviewIntermediate
telegram-bot-builder10610moReviewIntermediate
copilot-sdk77moReviewIntermediate
reddit-api37moReviewIntermediate

Try saying

Example prompts that trigger this skill in your AI assistant.

Search skills

Search the agent skills registry