magic-quill

从主题（游戏/电影/系列/等）或 URL 生成 OpenClaw Spellbook YAML 主题映射。当您需要在 /spells 下创建或刷新包含广泛流行技能（默认前 50 名）的主题法术映射文件时使用。生成器现在首先执行动态拼写列表引用发现（搜索拼写列表/API 并解析发现的 JSON/HTML 源），然后使用背景知识/上下文作为辅助样式输入，并在引用失败时回退到启发式拼写名称。注意：此技能会生成 YAML 映射文件 - 要在代理会话中使用咒语，您需要安装 openclaw-spellbook 挂钩（请参阅 wynnsu/openclaw-spellbook）。

# 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).
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)

```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/The_Lord_of_the_Rings" --limit 50 --author "@you"
npm run generate:spellbook-theme -- --topic "DnD 5e" --limit 20 --author "@you"
```

## Commands (Agents)

```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
```

## Install From This Repo (Subpath)

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

```bash
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:

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

Or install just the hook directly from the repo:
```bash
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):

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

---

## 中文说明

# Magic Quill

一支魔法羽毛笔，为 OpenClaw Spellbook 题写主题法术映射，对热门技能具有高覆盖率。

## 输入

- `--topic <name>` 或 `--url <https://...>`（主要输入；拼写列表查找首先按主题/主题搜索，提供时 `--url` 被视为高优先级的参考候选）
- 可选 `--theme <name>`，用于覆盖最终的主题名称（或仅用 `--theme` 运行纯启发式模式）
- 可选 `--out <path>`（别名：`--output`）（默认：`spells/<theme-slug>.yaml`）
- 可选 `--limit <n>`（别名：`--top`），用于前 N 名覆盖（默认：`50`）
- 可选 `--author <name>`（默认：`@magic-quill`）

## 操作步骤

1. 尽可能从两个来源收集热门技能：
   - `skills.sh` 趋势安装
   - ClawHub 下载量 API 端点
2. 将结果合并并去重为一个目标集合（如果获取失败，则用内置回退技能填补空缺）。
3. 首先收集拼写列表引用（主要拼写来源）：
   - 从主题/主题构建动态网络搜索查询（例如 `<topic> spell list` 和 `<topic> spells api`）
   - 将靠前的搜索结果链接（DuckDuckGo HTML 结果）解析为候选参考 URL
   - 当存在 `--url` 时将其作为高优先级候选纳入
   - 获取发现的 JSON/HTML 引用（例如如果发现了 `dnd5eapi.co`），提取拼写名称，并对来自成功引用的名称进行合并/去重
4. 收集背景设定/上下文（仅作为辅助样式关键词）：
   - 如果提供了 `--url`，获取并提取页面文本
   - 否则如果提供了 `--topic`，尝试 Wikipedia 摘要 API
   - 如果获取失败，使用内置的主题词库/启发式方法
5. 如果拼写列表引用失败或未产生足够的名称，则使用内置的启发式拼写名称生成器生成法术映射。
6. 将 YAML 写入请求的输出路径（通常在 `spells/` 下），并在可用时包含 `# spell-list-references:` 注释链接，指向成功动态发现的拼写列表来源/端点。
7. 如果输出文件位于 `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/The_Lord_of_the_Rings" --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 挂钩**。安装完整的 spellbook 包：

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

或者直接从仓库只安装挂钩：
```bash
npx skills add wynnsu/openclaw-spellbook/hooks/spellbook
```

该挂钩在运行时处理魔法法术名称与实际技能 ID 之间的转换。

安装后的用法（示例提示）：

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