AI helpers#

The AI-facing half of napkin-sketch, in three plugins. Each one owns a folder here, and a folder is the whole plugin: the manifest, the commands, any subagents, the skills, and the contract the tool reads before it edits anything. The marketplace that lists them is .claude-plugin/marketplace.json at the repository root.

Experimental. The AI helpers run an agentic AI command-line tool that napkin-sketch does not ship, on your account and at its cost. They are new, and their commands, forms and files may change in a minor release.

ai-helper/
├── vectors/            Animation Mode: pose one SVG frame into the next
├── graphic-designer/   Design language: read an asset, then draw more like it
└── scripting/          Napkin scripts: write one from a request

Installing#

All three plugins are tracked source, so a clone already has them. What installing does is put them where an AI tool looks.

npm run ai-helper -- --list                     # targets and helpers
npm run ai-helper                               # every helper -> .claude
npm run ai-helper -- --to github                # -> .github
npm run ai-helper -- --helper graphic-designer  # narrow to one helper
npm run ai-helper -- --to plugin                # check the plugins, print /plugin

A dot-folder target copies each helper's skills and instructions into it. The plugin target copies nothing, because the folder already is the plugin; it checks the tree, syncs the manifest version to package.json, and prints the commands that load it:

/plugin marketplace add .
/plugin install vectors@napkin-sketch
/plugin install graphic-designer@napkin-sketch
/plugin install scripting@napkin-sketch

Without a clone, /plugin marketplace add isocialPractice/napkin-sketch reaches the same three.

Animation Mode is a feature switch, not a file copy#

Animation Mode is the one part of the app gated on an install record. Turning it on and off is its own script, which only ever touches the vectors helper:

npm run animation-mode -- --status
npm run animation-mode -- --install --to plugin
npm run animation-mode -- --uninstall

It writes ai-helper/installed.json (gitignored), and the app reads that one file to decide whether the mode exists. graphic-designer and scripting have no such switch: nothing in the GUI runs them, so there is nothing to gate. scripting is run by the command line's draw --prompt, which needs only the AI tool on the PATH.

The reference files, by URI#

The vectors helper's skills read reference sheets and the data measured from them, about 6 MB in their assets/ folders. The npm package leaves them out and carries assets/uri.md in each such folder instead: every file's name and its address in this repository at the release's tag, which the skills tell a tool how to download. A clone and the GitHub plugin have the files themselves. npm run ai-helper -- --to plugin writes the lists, and a test fails when one falls behind its folder or the version.

Adding a helper#

1. Make ai-helper/<name>/ with a .claude-plugin/plugin.json, and whichever of commands/, agents/, instructions/ and skills/ it needs.
2. Add an entry to HELPERS in scripts/install-ai-helper.mjs - the installer derives everything else from it.
3. Add the matching constant in src/core/ai-tool.ts. A test fails if the two registries disagree, because the script cannot import the TypeScript.
4. Add a plugin entry to the root marketplace manifest.

Skill names are global once a tool loads them, so every SKILL.md in the tracked tree must declare a name no other one does. test/ai-helper.test.ts enforces that across all the helpers at once.