@miraclesoft/spark

Install and manage Spark AI skills for Claude Code, Cursor, GitHub Copilot, and OpenCode — from one CLI, across every tool you use.

Install

npm install -g @miraclesoft/spark

Quick start

spark auth --url https://power.miraclesoft.ai   # browser login, once per portal
spark install angular-expert                        # prompts for tool/scope if not configured
spark list                                           # what's installed, and its status

Commands

spark auth

spark auth --url <portal-url>   # browser login (dev, QA, prod, or any Spark portal)
spark auth                      # re-auth against the last portal you used
spark auth --logout             # clear stored credentials

Opens your browser, you log in on the portal, and it hands a token back to the CLI automatically — nothing to copy/paste. Credentials are stored in ~/.spark/config.json.

spark config

Defaults so you don't have to repeat --tool/--scope/--path on every command.

spark config                    # show everything (defaults + auth info)
spark config tool               # read one value
spark config tool cursor        # set one value
spark config unset tool         # clear one value
spark config set scope local    # explicit form, same effect as `spark config scope local`

Valid keys: tool (claude | cursor | copilot | opencode), scope (global | local | custom), path (used when scope is custom).

spark install [slugs...]

spark install angular-expert
spark install angular-expert react-patterns --scope local
spark install [email protected] --tool claude       # pin a specific version
spark install --kit frontend-essentials --tool cursor

• --tool / --scope fall back to your configured defaults, then prompt interactively if neither is set.
• --scope custom requires --path (or a configured default path).
• If the target folder already has local edits, you'll be prompted to overwrite or skip (--force skips the prompt and always overwrites).
• Each skill installs as a folder — SKILL.md plus any attachments — never a single file.

spark update [slugs...]

spark update                              # update everything to latest
spark update angular-expert                # just one skill
spark update angular-expert --tool cursor  # only its cursor install, if it's under multiple tools
spark update [email protected]         # pin to a specific version
spark update --dry-run                     # preview without changing anything
spark update --force                       # skip the "has local modifications" prompt

Also resets a locally-modified skill back to its published content even when there's no newer version available — that's what --force is for if spark list shows something as modified and there's nothing to bump to.

spark uninstall [slugs...]

spark uninstall angular-expert
spark uninstall angular-expert --tool cursor   # only that install, if it exists under multiple tools
spark uninstall --all                          # remove everything Spark manages (asks to confirm)

If a skill is installed under more than one tool or scope and you don't pass --tool/--scope, you'll get a checklist to pick which install(s) to remove.

spark list

spark list                    # everything
spark list --tool claude
spark list --scope local
spark list --status modified
spark list --here             # only skills installed under the current directory

spark status

Auth state (who you're logged in as) and a summary of manifest health (clean/modified/missing counts).

Install locations

Every install is a folder — SKILL.md plus any attachments — at the canonical path for its tool and scope:

| Tool | Local (--scope local) | Global (--scope global) | |----------|----------------------------|-------------------------------------| | claude | .claude/skills/<slug>/ | ~/.claude/skills/<slug>/ | | cursor | .cursor/skills/<slug>/ | ~/.cursor/skills/<slug>/ | | copilot | .github/skills/<slug>/ | ~/.copilot/skills/<slug>/ | | opencode | .opencode/skills/<slug>/ | ~/.config/opencode/skills/<slug>/ |

--scope custom --path <dir> installs to <dir>/<slug>/ for any tool.

Development

npm ci
npm run dev -- <command>    # run against source via ts-node
npm run build                # compile to dist/
npm run lint                 # tsc --noEmit