Magic Quill

Generate YAML spell mapping files for OpenClaw Spellbook themed by a topic or URL, using dynamic spell-list discovery and heuristic fallback.

Security Scan

The skill's stated goal (generate themed YAML spell mappings) matches most of its instructions and code, but there are several concerning elements — dynamic fetching of arbitrary URLs, a pre-scan prompt-injection signal in SKILL.md, and inclusion of many powerful/dangerous fallback skill IDs — that warrant caution before installing or running it.

Purpose & Capability

The name/description (generate themed OpenClaw Spellbook YAML mappings) matches the included SKILL.md and the script file: the skill discovers spell lists, fetches pages, synthesizes names, and writes YAML. Including a built-in list of popular skills (used as fallbacks) is consistent with its goal to provide broad coverage. That fallback list however includes high-privilege/dangerous skill IDs (e.g., delete-file, kill-process, kubectl-apply, terraform-apply), which is coherent for a 'popular-skills' fallback but may be surprising to non-technical users and expands the potential impact of generated mappings.

Instruction Scope

Runtime instructions ask the agent to perform web searches (parse DuckDuckGo HTML), fetch arbitrary discovered URLs and a user-supplied --url, follow links up to depth, extract JSON/HTML content, merge names, and then write YAML under spells/. This gives the skill broad discretion to contact many external hosts (including ones discovered dynamically) and to read/parse arbitrary pages. The SKILL.md also triggered a pre-scan 'unicode-control-chars' prompt-injection pattern — that could be used to hide content or manipulate parsers. Additionally, because the fallback skill list contains destructive operations, the generated YAML may map benign-sounding spell names to actions that can perform destructive changes if later used by an agent.

Install Mechanism

There is no install spec (instruction-only), which is lower-risk in that nothing is automatically downloaded at install time. However, the repo includes an executable Node script (scripts/generate-spell-mapping.mjs) which will be executed by the agent when invoked; that script does filesystem writes and network fetches. Because execution is manual/agent-driven rather than an automatic remote download, the install risk is moderate but requires reviewing the script before running.

Credentials

The skill asks for no environment variables or credentials, which is proportionate. That said, it references external resources (skills.sh trending installs, ClawHub downloads API, DuckDuckGo, Wikipedia) without declaring required credentials — likely they are public endpoints, but the SKILL.md doesn't document expected endpoints or failure modes. The script will read/write files (spells/), and may fetch arbitrary hosts, so network access is the main capability requested; no hidden credential requests were declared, which is appropriate but leaves some uncertainty about how external APIs are used.

Persistence & Privilege

always is false and the skill is user-invocable — no elevated persistence requested. The script writes files to the project's spells/ directory (expected behavior). Be aware: writing new spell mapping YAML that maps to powerful skill IDs can effectively enable those operations when the openclaw-spellbook hook is installed, so the write operation has security implications even though the skill itself doesn't request persistent platform privileges.

Scan Findings in Context

[unicode-control-chars] unexpected: SKILL.md contained unicode control characters pattern. This is not expected for a generator README and can be used to obfuscate content or try to manipulate prompts/parsers. It should be inspected and removed or explained before trusting the skill.

What to consider before installing

What to consider before installing/running Magic Quill: - Inspect the generator script (scripts/generate-spell-mapping.mjs) fully before running. The script will fetch web pages, parse JSON/HTML, follow links, and write YAML files; ensure there are no hidden outbound endpoints or obfuscated behavior. - The SKILL.md triggered a unicode-control-chars heuristic. That can hide text or behavior from casual reviewers — open the raw SKILL.md and the script in a plain text editor, search for control characters, and remove or understand them. - Network behavior: the tool performs dynamic web searches and will fetch arbitrary discovered URLs and any --url you provide. If you run it, consider doing so in an environment with controlled network access (or offline) until you trust it. - Review generated YAML before using it with the openclaw-spellbook hook. The fallback/popular-skills list includes powerful/destructive skill IDs (delete-file, kill-process, kubectl-apply, terraform-apply, etc.). If the generator maps those to easy-to-invoke spell names, an agent using that spellbook could execute destructive actions. Manually vet or sanitize the mapping (remove or rename high-risk mappings) before enabling them in an agent environment. - Validate locally: run the generation with --out pointing to a safe directory (not your live project), review the output, and run the npm validation step in a sandbox. Do not auto-install or auto-enable the spellbook hook until you have reviewed artifact contents. - If you need stronger assurance, request the full source of the external endpoints the script calls (skills.sh, ClawHub) or run the script with network monitoring to see what hosts are contacted. Given the prompt-injection signal and the potentially wide-reaching consequences of the generated mappings, proceed only after manual review and with network/file safeguards in place.

A magical quill that inscribes themed spell mappings for OpenClaw Spellbook with high coverage for popular skills.

Inputs

• --topic <name> or --url <https://...> (primary inputs; spell-list lookup searches by topic/theme first, and --url is treated as a high-priority reference candidate when provided)
• Optional --theme <name> to override the final theme name (or run heuristic-only mode with just --theme)
• Optional --out <path> (alias: --output) (default: spells/<theme-slug>.yaml)
• Optional --limit <n> (alias: --top) for top-N coverage (default: 50)
• Optional --author <name> (default: @magic-quill)

What To Do

1. Gather popular skills from both sources when possible:
   • skills.sh trending installs
   • ClawHub downloads API endpoint
2. Merge and de-duplicate the results into a target set (fill gaps from built-in fallback skills if fetch fails).
3. Gather spell-list references first (primary spell source):
   • Build dynamic web search queries from topic/theme (for example <topic> spell list and <topic> spells api)
   • Parse top search result links (DuckDuckGo HTML results) into candidate reference URLs
   • Include --url as a high-priority candidate when present
   • Fetch discovered JSON/HTML references (for example dnd5eapi.co if discovered), extract spell names, and merge/de-duplicate names from successful references
4. Gather lore/context (secondary style keywords only):
   • If --url is provided, fetch and extract page text
   • Else if --topic is provided, try Wikipedia summary API
   • If fetch fails, use built-in theme lexicon/heuristics
5. If spell-list references fail or do not produce enough names, generate spell mappings with the built-in heuristic spell-name generator.
6. Write YAML to the requested output path (usually under spells/), including # spell-list-references: comment links for successful dynamically discovered spell-list sources/endpoints when available.
7. Validate with npm run validate:spells if the output file is under spells/.

Commands (Users)

npm run generate:spellbook-theme -- --theme "Studio Ghibli" --limit 50 --author "@you"
npm run generate:spellbook-theme -- --topic "Cyberpunk 2077" --limit 75 --out spells/cyberpunk-2077.yaml --author "@you"
npm run generate:spellbook-theme -- --url "https://en.wikipedia.org/wiki/The_Lord_of_the_Rings" --limit 50 --author "@you"
npm run generate:spellbook-theme -- --topic "DnD 5e" --limit 20 --author "@you"

Commands (Agents)

node magic-quill/scripts/generate-spell-mapping.mjs --theme "The Legend of Zelda" --topic "The Legend of Zelda" --limit 50 --out spells/zelda.yaml --author "@example"
node scripts/validate-spells.mjs

Install From This Repo (Subpath)

Use a repo subpath source with npx skills add, for example:

npx skills add wynnsu/openclaw-spellbook/magic-quill

⚠️ Requires Hook for Use

This skill generates spell YAML mapping files — to actually use the themed spells in agent sessions, you need the openclaw-spellbook hook installed. Install the full spellbook package:

# Install the spellbook hook (includes magic-quill skill)
npx skills add wynnsu/openclaw-spellbook

Or install just the hook directly from the repo:

npx skills add wynnsu/openclaw-spellbook/hooks/spellbook

The hook handles the translation between magical spell names and actual skill IDs at runtime.

Usage after install (example prompt):

Use magic-quill to create a Star Wars spell mapping with top 50 coverage and write it to spells/star-wars.yaml.