Magic Quill
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).
- 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.
- 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. - Validate with
npm run validate:spells if the output file is under spells/.
Commands (Users)
CODEBLOCK0
Commands (Agents)
CODEBLOCK1
Install From This Repo (Subpath)
Use a repo subpath source with npx skills add, for example:
CODEBLOCK2
⚠️ 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:
CODEBLOCK3
Or install just the hook directly from the repo:
CODEBLOCK4
The hook handles the translation between magical spell names and actual skill IDs at runtime.
Usage after install (example prompt):
CODEBLOCK5
Magic Quill
一支神奇的羽毛笔，可为 OpenClaw Spellbook 铭刻主题法术映射，对热门技能具有高覆盖率。
输入参数
- - --topic <名称> 或 --url （主要输入；法术列表查找优先按主题/话题搜索，提供 --url 时将其视为高优先级参考候选项）
- 可选 --theme <名称> 用于覆盖最终主题名称（或仅使用 --theme 运行启发式模式）
- 可选 --out <路径>（别名：--output）（默认值：spells/<主题别名>.yaml）
- 可选 --limit <数量>（别名：--top）用于前 N 项覆盖（默认值：50）
- 可选 --author <名称>（默认值：@magic-quill）
执行步骤
- 1. 尽可能从两个来源收集热门技能：
- skills.sh 热门安装数据
- ClawHub 下载 API 端点
- 2. 合并并去重结果，形成目标集合（若获取失败，则从内置备用技能中填补空缺）。
- 首先收集法术列表参考（主要法术来源）：
- 根据话题/主题构建动态网络搜索查询（例如 <话题> spell list 和 <话题> spells api）
- 将顶部搜索结果链接（DuckDuckGo HTML 结果）解析为候选参考 URL
- 当存在 --url 时，将其作为高优先级候选
- 获取发现的 JSON/HTML 参考（例如若发现 dnd5eapi.co），提取法术名称，并从成功的参考中合并/去重名称
- 4. 收集背景/上下文（仅次要风格关键词）：
- 如果提供了 --url，则获取并提取页面文本
- 否则如果提供了 --topic，则尝试 Wikipedia 摘要 API
- 如果获取失败，则使用内置主题词典/启发式规则
- 5. 如果法术列表参考失败或未产生足够名称，则使用内置启发式法术名称生成器生成法术映射。
- 将 YAML 写入请求的输出路径（通常在 spells/ 下），包括 # spell-list-references: 注释链接，指向成功动态发现的法术列表来源/端点（如可用）。
- 如果输出文件位于 spells/ 下，则使用 npm run validate:spells 进行验证。
命令（用户）
bash
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/TheLordoftheRings --limit 50 --author @you
npm run generate:spellbook-theme -- --topic DnD 5e --limit 20 --author @you
命令（代理）
bash
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
从此仓库安装（子路径）
使用 npx skills add 配合仓库子路径源，例如：
bash
npx skills add wynnsu/openclaw-spellbook/magic-quill
⚠️ 需要 Hook 才能使用
此技能生成法术 YAML 映射文件——要在代理会话中实际使用主题法术，您需要安装 openclaw-spellbook hook。安装完整法术书包：
bash
安装法术书 hook（包含 magic-quill 技能）
npx skills add wynnsu/openclaw-spellbook
或直接从仓库仅安装 hook：
bash
npx skills add wynnsu/openclaw-spellbook/hooks/spellbook
该 hook 在运行时处理魔法法术名称与实际技能 ID 之间的转换。
安装后使用示例（提示词示例）：
text
使用 magic-quill 创建一个包含前 50 项覆盖的星球大战法术映射，并将其写入 spells/star-wars.yaml。
