Skip to content
ZincGitHubDownload

Agent skills for plugin authors

View as Markdown

Zinc ships two skills for AI coding agents that write Zinc plugins. A skill is a folder with instructions (SKILL.md), reference pages and small scripts. The agent reads it when a task matches, so it follows the steps that work in this repository instead of guessing. The skills are written for Claude Code, and they work with any agent that reads SKILL.md folders.

Skill Use it to Download
zinc-plugin-create Make a new plugin: scaffold, build, test, package zinc-plugin-create.zip
zinc-plugin-port Check whether a Zotero plugin can run on Zinc, then port it zinc-plugin-port.zip

The zips are built from .claude/skills/ every time the website is built, so they match main.

zinc-plugin-create

Makes a plugin from nothing. The agent:

  1. Picks JavaScript or Rust, the smallest world, and the fewest permissions for what you asked for. JavaScript runs interpreted (QuickJS), so it suits glue code and small views; Rust suits plugins that compute.
  2. Scaffolds the plugin with scripts/scaffold.ts. The --with option picks the parts: menu, column, section, prefs, dialog, notifier, library, reader, net, toast and mcp (a tool for AI agents). The script writes manifest.json, the Fluent strings and the entry file, and prints the world and permissions it chose.
  3. Writes the logic from tested recipes (menus, columns, item pane sections, dialogs, preference panes, the notifier, library reads and writes, reader hooks, network, tools for AI agents).
  4. Builds it (plugin-api/sdk/js/scripts/build.ts or plugin-host/scripts/build-plugin.ts).
  5. Tests it with scripts/smoke.ts, which loads the plugin in the real runner with stub imports and calls its callbacks. No library and no running app are needed.
  6. Packages it with scripts/pack.ts: a .zplugin, or with --wasm a single .wasm file. Users install either from Settings > Plugins > Install from file… (Zinc 0.2.3 and later).

For tools for AI agents, the skill uses the plugin-mcp world (or plugin when the plugin also adds menus or views), the mcp.expose permission, and defineTool (JavaScript) or mcp::Tool (Rust). It reminds you that the tools stay hidden until you turn on the plugin’s switch in Settings > Plugins. See Exposing tools to AI agents.

zinc-plugin-port

Ports a Zotero 7 to 10 plugin (bootstrap.js and Firefox internals) to Zinc. The agent:

  1. Gets the source (an .xpi, a repository or a release) into a scratch folder and runs scripts/scan.ts. The scan lists every Zotero, Firefox and DOM API the plugin uses, maps each to the Zinc call and the row of the parity tables, and marks it covered, partial or not planned.
  2. Writes a go/no-go report per feature: what ports cleanly, what changes, what cannot be ported, the language, the permissions, and the licence. It stops here until you have read the report.
  3. Rewrites the plugin by pattern (lifecycle, prefs, Fluent strings, menus, columns, item pane sections, the notifier, library and database access, HTTP, dialogs, the reader, files, timers, monkey-patching). A plugin that serves an HTTP route to other programs is offered MCP tools instead, where that fits.
  4. Verifies the port on a throwaway core and a temporary library with scripts/verify-port.ts, and compares it feature by feature with the original.

A port is a derivative work: the skill keeps the original licence and notices, and refuses to copy code that has no licence.

Install a skill

Unzip it into one of these folders. Each zip holds one folder named after the skill.

  • ~/.claude/skills/ (on Windows %USERPROFILE%\.claude\skills\): the skill is available in every project.
  • .claude/skills/ inside a project: only in that project. A checkout of the Zinc repository already has both skills there.
Terminal window
Expand-Archive zinc-plugin-create.zip -DestinationPath "$HOME\.claude\skills"
Terminal window
unzip zinc-plugin-create.zip -d ~/.claude/skills

Start a new Claude Code session so it picks up the skill. Then ask for what you want, for example “make a Zinc plugin that adds a column with the number of PDF pages” or “port the Zotero plugin at to Zinc”. The agent loads the matching skill by itself; you can also name it.

What the skills need

  • A checkout of the Zinc repository. The scripts look for it (the folder that holds plugin-api/) from the current folder, from ZINC_ROOT, or from --zinc <path>. They use its SDKs, its WIT files and its build scripts.
  • Bun. For Rust plugins, a Rust toolchain with the wasm32-wasip2 target.
  • For testing: the plugin runner zhw (cd plugin-host-wasmtime && cargo build --release) and plugin-host/node_modules.

The skills never touch your real library, your Zotero data folder or the ports of a running Zinc (23119, 23120). See Writing a Zinc plugin for the same steps done by hand.