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.zipInstalls 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.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
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
- Auto-detect this machine:
Toolbar status and Toast notifications
Choose the API by lifetime and scope:
ShowToolbarMsg/show_toolbar_msgdisplays 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, useOnEnterPluginQuery/on_enter_plugin_queryand its callback context to publish the status once a result is selected; the initial globalqueryruns 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=Trueand explicitly callClearToolbarMsg(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_msgdisplays an independent global notification and does not require an active plugin context. Use it for one-off events and optional notification actions. The legacyNotify/notifyAPI is deprecated and also displays a Toast.
Choose a plugin type
- Single-file SDK plugin: one
.pyor CommonJS.jsfile 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+; headerMinWoxVersionmust be"2.4.2". - SDK plugin (
.wox): multi-file package with dependencies, resources, TypeScript, andplugin.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.
- Run
python3 scripts/detect_local_runtime.py(usepythonifpython3is missing). It printsnodejs,python, ornone. - If that script cannot run, check the floors yourself:
node --versionfor Node.js 20+, andpython3 --versionfor Python 3.10+. On Windows also trypy -3 --versionandpython --version. - 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
- Map the choice to
--type:singlefile-nodejs/singlefile-python, ornodejs/python.--type singlefileapplies the same detection inside the scaffold.
Workflow
1) Scaffold plugin files
- Use
scripts/scaffold_wox_plugin.pyfornodejs,python,singlefile,singlefile-python, orsinglefile-nodejs. - Pass
--nameand--trigger-keywordsfor every runtime. The scaffold exits without them.--output-diris 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 initin 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>.jsorWox.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-dirwhen using the scaffold, or write the file there directly fromassets/single_file_plugin_templates/. Do not also create a copy under the current repository (plugins/, workspace root, or a new folder). Pass--output-dironly 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.jsand.pythere as a plugin. - Single-file SDK plugins must set header
MinWoxVersionto"2.4.2". The scaffold applies this default when--min-wox-versionis 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.mdorreferences/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.
Titleis the name to scan.SubTitleis one short identity line, such as a code, place, or source.Tailsare 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 addPreviewfor a quote, status, short record, or anything that fits on that row. - A durable result must set
IdentityKey(Pythonidentity_key, script JSONidentity_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/ScoreKeyis only the older name. OmitIdentityKeyon 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(idin 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 asopencan 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 usingUpdateResult/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 stableIdentityKeyabove. 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 latestquery(). Replace that list on the next query. When a background refresh or an action changes a row that is still on screen, callUpdateResultwith the same resultIdand 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
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.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| wox-plugin-creator (this skill) | 1 | 5mo | Review | Intermediate |
| telegram-bot-builder | 106 | 10mo | Review | Intermediate |
| copilot-sdk | 7 | 7mo | Review | Intermediate |
| reddit-api | 3 | 7mo | Review | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
telegram-bot-builder
davila7
Expert in building Telegram bots that solve real problems - from simple automation to complex AI-powered bots. Covers bot architecture, the Telegram Bot API, user experience, monetization strategies, and scaling bots to thousands of users. Use when: telegram bot, bot api, telegram automation, chat bot telegram, tg bot.
copilot-sdk
github
Build agentic applications with GitHub Copilot SDK. Use when embedding AI agents in apps, creating custom tools, implementing streaming responses, managing sessions, connecting to MCP servers, or creating custom agents. Triggers on Copilot SDK, GitHub SDK, agentic app, embed Copilot, programmable agent, MCP server, custom agent.
reddit-api
alinaqi
Reddit API with PRAW (Python) and Snoowrap (Node.js)
adk-engineer
jeremylongshore
Execute software engineer specializing in creating production-ready ADK agents with best practices, code structure, testing, and deployment automation. Use when asked to "build ADK agent", "create agent code", or "engineer ADK application". Trigger with relevant phrases based on skill purpose.
agent-v3-performance-engineer
ruvnet
Agent skill for v3-performance-engineer - invoke with $agent-v3-performance-engineer
llm-application-dev
skillcreatorai
Building applications with Large Language Models - prompt engineering, RAG patterns, and LLM integration. Use for AI-powered features, chatbots, or LLM-based automation.