@dragonbot-skills/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ballistic Brands
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# @dragonbot-skills/cli
+
+Install [Claude skills](https://docs.anthropic.com/) from the DragonBot
+catalog into your local Claude environment.
+
+```bash
+npx @dragonbot-skills/cli install amazon-kw-research
+```
+
+That single command drops `amazon-kw-research/SKILL.md` (plus any
+references and scripts) into `~/.claude/skills/amazon-kw-research/`,
+where Claude Code (and other Claude clients that follow the same
+convention) will pick it up automatically.
+
+## Commands
+
+```bash
+# What's in the catalog?
+dragonbot-skills list
+
+# Install a skill (user-scope: ~/.claude/skills/<slug>/)
+dragonbot-skills install amazon-kw-research
+
+# Install for one repo only (./.claude/skills/<slug>/)
+dragonbot-skills install amazon-kw-research --project
+
+# Install somewhere custom
+dragonbot-skills install amazon-kw-research --target ~/my-claude-skills
+
+# Reinstall over an existing copy
+dragonbot-skills install amazon-kw-research --force
+
+# Remove
+dragonbot-skills uninstall amazon-kw-research
+```
+
+`-h` / `--help` prints the full usage.
+
+## Skills
+
+| Slug | What it does |
+|---|---|
+| `amazon-kw-research` | Amazon keyword research → workbook + PPC setup (uses Keepa + Jungle Scout via the DragonBot MCP). |
+
+More skills will be added here — file a PR or run `dragonbot-skills list`
+after upgrading.
+
+## Where it installs
+
+| Scope | Path | When to use |
+|---|---|---|
+| `user` *(default)* | `~/.claude/skills/<slug>/` | one install, every project on this machine sees it |
+| `--project` | `<cwd>/.claude/skills/<slug>/` | this repo only |
+| `--target <dir>` | `<dir>/<slug>/` | custom — for clients that use a different skills directory |
+
+Skills installed here are picked up by Claude Code automatically. Other
+Claude clients (Desktop, Cowork, etc.) that follow the `.claude/skills/`
+convention work the same way; if yours reads from a different path, use
+`--target`.
+
+## Updating
+
+Skills are bundled with this package, so updating is just `npx`-ing the
+latest version:
+
+```bash
+npx @dragonbot-skills/cli@latest install amazon-kw-research --force
+```
+
+`--force` is needed because we won't silently overwrite an existing
+install. (No, we don't auto-update — installs are explicit.)
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build        # → dist/cli.js (chmod +x)
+node dist/cli.js list
+```
+
+Skills live in `skills/<slug>/SKILL.md` at the package root. Adding a
+new skill = adding a new folder there with a `SKILL.md` containing
+frontmatter (`name:`, `description:`) and a markdown body. The
+`bundledRoot` test override pattern in `src/install.test.ts` lets you
+unit-test against synthetic skills without touching the real catalog.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/cli.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+// @dragonbot-skills/cli — installer for DragonBot's Claude skills.
+//
+// Usage:
+//   npx @dragonbot-skills/cli list
+//   npx @dragonbot-skills/cli install <slug> [--project] [--target <dir>] [--force]
+//   npx @dragonbot-skills/cli uninstall <slug> [--project] [--target <dir>]
+//
+// Keep the dispatch dumb on purpose — three commands, flat flag
+// parsing, no commander/yargs dep. If we ever grow past ~5 commands,
+// reach for one.
+import { listBundledSkills } from "./skills.js";
+import { install, uninstall } from "./install.js";
+const USAGE = `dragonbot-skills — install Claude skills from the DragonBot catalog
+
+Usage:
+  dragonbot-skills list
+  dragonbot-skills install <slug> [--project] [--target <dir>] [--force]
+  dragonbot-skills uninstall <slug> [--project] [--target <dir>]
+
+Scope:
+  (default)         install to ~/.claude/skills/<slug>/  (user-scope)
+  --project         install to ./.claude/skills/<slug>/  (current repo only)
+  --target <dir>    install to <dir>/<slug>/             (any custom path)
+
+Flags:
+  --force           overwrite an existing install
+  -h, --help        show this help
+
+Examples:
+  dragonbot-skills install amazon-kw-research
+  dragonbot-skills install amazon-kw-research --project --force
+  dragonbot-skills list
+`;
+function main(argv) {
+    const args = argv.slice(2);
+    if (args.length === 0 || args[0] === "-h" || args[0] === "--help") {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    const command = args[0];
+    const rest = args.slice(1);
+    switch (command) {
+        case "list":
+            return runList();
+        case "install":
+            return runInstall(rest);
+        case "uninstall":
+            return runUninstall(rest);
+        default:
+            process.stderr.write(`Unknown command: ${command}\n\n${USAGE}`);
+            return 2;
+    }
+}
+function runList() {
+    const skills = listBundledSkills();
+    if (skills.length === 0) {
+        process.stdout.write("No skills bundled in this version of the package.\n");
+        return 0;
+    }
+    process.stdout.write(`Available skills (${skills.length}):\n\n`);
+    const slugWidth = Math.max(...skills.map((s) => s.slug.length));
+    for (const s of skills) {
+        const padded = s.slug.padEnd(slugWidth, " ");
+        process.stdout.write(`  ${padded}  ${s.description}\n`);
+    }
+    process.stdout.write("\nInstall one with: dragonbot-skills install <slug>\n");
+    return 0;
+}
+function runInstall(rest) {
+    const { positionals, flags } = parseFlags(rest);
+    const slug = positionals[0];
+    if (!slug) {
+        process.stderr.write("install: missing <slug>\n\n" + USAGE);
+        return 2;
+    }
+    const scope = flags.project ? "project" : "user";
+    try {
+        const result = install({
+            slug,
+            scope,
+            targetDir: flags.target,
+            force: flags.force,
+        });
+        process.stdout.write(`✓ Installed ${slug} → ${result.installedTo} (${result.scope}-scope)\n`);
+        return 0;
+    }
+    catch (err) {
+        process.stderr.write(`${err.message}\n`);
+        return 1;
+    }
+}
+function runUninstall(rest) {
+    const { positionals, flags } = parseFlags(rest);
+    const slug = positionals[0];
+    if (!slug) {
+        process.stderr.write("uninstall: missing <slug>\n\n" + USAGE);
+        return 2;
+    }
+    const scope = flags.project ? "project" : "user";
+    try {
+        const result = uninstall({
+            slug,
+            scope,
+            targetDir: flags.target,
+        });
+        if (result.removed) {
+            process.stdout.write(`✓ Removed ${slug} from ${result.path}\n`);
+        }
+        else {
+            process.stdout.write(`(no-op) ${result.path} was not installed\n`);
+        }
+        return 0;
+    }
+    catch (err) {
+        process.stderr.write(`${err.message}\n`);
+        return 1;
+    }
+}
+function parseFlags(args) {
+    const positionals = [];
+    const flags = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg.startsWith("--")) {
+            positionals.push(arg);
+            continue;
+        }
+        const eq = arg.indexOf("=");
+        const key = eq < 0 ? arg.slice(2) : arg.slice(2, eq);
+        const inlineValue = eq < 0 ? undefined : arg.slice(eq + 1);
+        switch (key) {
+            case "project":
+                flags.project = true;
+                break;
+            case "force":
+                flags.force = true;
+                break;
+            case "target":
+                flags.target = inlineValue ?? args[++i];
+                if (!flags.target) {
+                    throw new Error("--target needs a directory path");
+                }
+                break;
+            default:
+                throw new Error(`Unknown flag: --${key}`);
+        }
+    }
+    return { positionals, flags };
+}
+process.exit(main(process.argv));
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/install.js

@@ -0,0 +1,111 @@
+// Install / uninstall skills into the user's local Claude skills
+// directory.
+//
+// Claude Code reads skills from two locations:
+//   user-scope    ~/.claude/skills/<slug>/SKILL.md
+//   project-scope <cwd>/.claude/skills/<slug>/SKILL.md
+//
+// We default to user-scope (one install, every project sees it) and
+// expose `--project` for the per-repo variant. `--target <dir>`
+// overrides both — useful for other Claude clients (Cowork, Desktop)
+// that put their skills directory somewhere else.
+//
+// Install is atomic-ish: copy to a temp directory next to the
+// destination, then rename into place. If the destination already
+// exists we refuse without `--force` — a real reinstall should be
+// explicit, not silent.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { findBundledSkill } from "./skills.js";
+/**
+ * Resolve the skills directory the CLI should write into for a
+ * given scope. Doesn't create the directory — install() does that.
+ */
+export function resolveSkillsRoot(opts) {
+    if (opts.targetDir) {
+        return { root: path.resolve(opts.targetDir), scope: "custom" };
+    }
+    const scope = opts.scope ?? "user";
+    if (scope === "project") {
+        const cwd = opts.cwd ?? process.cwd();
+        return { root: path.join(cwd, ".claude", "skills"), scope: "project" };
+    }
+    const home = opts.home ?? os.homedir();
+    return { root: path.join(home, ".claude", "skills"), scope: "user" };
+}
+/**
+ * Copy the bundled skill folder for `slug` into the chosen skills
+ * directory. Throws when:
+ *   - the slug isn't bundled in this package
+ *   - the destination exists and `force` is false
+ */
+export function install(opts) {
+    const src = findBundledSkill(opts.slug, opts.bundledRoot);
+    if (!src) {
+        throw new Error(`Skill not found in this package: ${opts.slug}\n` +
+            `Run \`dragonbot-skills list\` to see what's available.`);
+    }
+    const { root, scope } = resolveSkillsRoot({
+        scope: opts.scope,
+        targetDir: opts.targetDir,
+        cwd: opts.cwd,
+        home: opts.home,
+    });
+    const dest = path.join(root, opts.slug);
+    if (fs.existsSync(dest)) {
+        if (!opts.force) {
+            throw new Error(`${dest} already exists. Pass --force to overwrite.`);
+        }
+        fs.rmSync(dest, { recursive: true, force: true });
+    }
+    fs.mkdirSync(root, { recursive: true });
+    // Stage in a sibling tmp dir, then rename. Avoids leaving a half-
+    // copied skill folder behind if the copy is interrupted.
+    const staging = fs.mkdtempSync(path.join(root, `.${opts.slug}-staging-`));
+    try {
+        copyDirRecursive(src, staging);
+        fs.renameSync(staging, dest);
+    }
+    catch (err) {
+        fs.rmSync(staging, { recursive: true, force: true });
+        throw err;
+    }
+    return { installedTo: dest, scope };
+}
+/**
+ * Remove the installed skill folder. Idempotent: returns
+ * `removed: false` (no error) when the folder isn't present.
+ */
+export function uninstall(opts) {
+    const { root, scope } = resolveSkillsRoot({
+        scope: opts.scope,
+        targetDir: opts.targetDir,
+        cwd: opts.cwd,
+        home: opts.home,
+    });
+    const dest = path.join(root, opts.slug);
+    if (!fs.existsSync(dest)) {
+        return { removed: false, path: dest, scope };
+    }
+    fs.rmSync(dest, { recursive: true, force: true });
+    return { removed: true, path: dest, scope };
+}
+// Minimal recursive copy — no externals, follows directories and
+// regular files only. Symlinks aren't expected in skills today; if
+// we ever ship one, switch to fs.cp({ recursive: true, verbatimSymlinks: true }).
+function copyDirRecursive(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        const s = path.join(src, entry.name);
+        const d = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            copyDirRecursive(s, d);
+        }
+        else if (entry.isFile()) {
+            fs.copyFileSync(s, d);
+        }
+        // Symlinks + special files: skip silently.
+    }
+}
+//# sourceMappingURL=install.js.map

package/dist/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"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"}

package/dist/skills.js

@@ -0,0 +1,101 @@
+// Discovery of skills bundled inside this package.
+//
+// The CLI doesn't fetch from a registry yet — every skill we
+// distribute lives under `skills/<slug>/` inside the package itself.
+// `npm install`-ing @dragonbot-skills/cli (or running it via npx)
+// gives the user the full catalog locally; the install command just
+// copies the requested folder out to the user's Claude skills dir.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Absolute path to the bundled `skills/` directory.
+ *
+ * Resolves relative to THIS source file, not to process.cwd() —
+ * users run `npx @dragonbot-skills/cli` from wherever they happen
+ * to be, so cwd is irrelevant. We walk up from `dist/skills.js`
+ * (compiled) to the package root and then into `skills/`.
+ */
+export function bundledSkillsDir() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(here, "..", "skills");
+}
+/**
+ * Return every skill bundled in this package: the directory name
+ * (slug) plus the `name:` and `description:` fields parsed from its
+ * SKILL.md frontmatter. Sorted by slug for stable output.
+ *
+ * Skips any subdirectory that doesn't contain a SKILL.md (it's not
+ * a skill).
+ */
+export function listBundledSkills(rootOverride) {
+    const dir = rootOverride ?? bundledSkillsDir();
+    if (!fs.existsSync(dir))
+        return [];
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    const skills = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const slug = entry.name;
+        const skillFile = path.join(dir, slug, "SKILL.md");
+        if (!fs.existsSync(skillFile))
+            continue;
+        const body = fs.readFileSync(skillFile, "utf8");
+        const meta = parseFrontmatter(body);
+        skills.push({
+            slug,
+            name: meta.name ?? slug,
+            description: meta.description ?? "",
+        });
+    }
+    skills.sort((a, b) => a.slug.localeCompare(b.slug));
+    return skills;
+}
+/**
+ * Resolve the on-disk path of a single bundled skill folder.
+ * Returns null when the slug isn't present (or the folder lacks a
+ * SKILL.md, in which case it isn't really a skill).
+ */
+export function findBundledSkill(slug, rootOverride) {
+    const root = rootOverride ?? bundledSkillsDir();
+    const dir = path.join(root, slug);
+    const skillFile = path.join(dir, "SKILL.md");
+    if (!fs.existsSync(skillFile))
+        return null;
+    const stat = fs.statSync(dir);
+    if (!stat.isDirectory())
+        return null;
+    return dir;
+}
+function parseFrontmatter(source) {
+    if (!source.startsWith("---"))
+        return {};
+    const end = source.indexOf("\n---", 3);
+    if (end < 0)
+        return {};
+    const header = source.slice(3, end).trim();
+    const out = {};
+    for (const rawLine of header.split("\n")) {
+        if (rawLine.startsWith(" ") || rawLine.startsWith("\t"))
+            continue;
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const colon = line.indexOf(":");
+        if (colon < 0)
+            continue;
+        const key = line.slice(0, colon).trim();
+        let value = line.slice(colon + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        if (key === "name")
+            out.name = value;
+        if (key === "description")
+            out.description = value;
+    }
+    return out;
+}
+//# sourceMappingURL=skills.js.map

package/dist/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@dragonbot-skills/cli",
+  "version": "0.1.0",
+  "description": "Install DragonBot skills (Amazon keyword research, etc.) into your local Claude environment.",
+  "type": "module",
+  "bin": {
+    "dragonbot-skills": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x dist/cli.js",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test --import tsx 'src/**/*.test.ts'",
+    "dev": "tsx src/cli.ts"
+  },
+  "keywords": [
+    "claude",
+    "claude-skills",
+    "anthropic",
+    "amazon",
+    "keyword-research",
+    "dragonbot"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}

package/skills/amazon-kw-research/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: amazon-keyword-research
+description: Amazon keyword research for product listings and PPC. Use when asked to do keyword research, find keywords for a product, build keyword lists, or analyze search terms for Amazon products.
+requires:
+  connections:
+    - keepa
+    - jungle_scout
+    - google_drive
+    - google_sheets
+---
+
+# Amazon Keyword Research Skill
+
+## Overview
+Conduct keyword research for Amazon products using Keepa (for ASIN/competitor data) and Jungle Scout (for keyword metrics). Output a structured Google Sheet workbook with raw data, filtered keywords, root keyword analysis, and PPC keyword lists.
+
+> **Before any API call here, read the per-service skills first** — they contain the canonical endpoint specs and curl examples you need:
+> - **Keepa:** see `skills/keepa/SKILL.md` (vended key via gateway, `?key=`-based auth).
+> - **Jungle Scout:** see `skills/jungle_scout/SKILL.md` (transparent reverse proxy, `Authorization` header + extra headers).
+>
+> Each skill has a `toolspec` YAML block listing every endpoint, method, params, and the exact auth flow — parse those for ground truth instead of guessing endpoint paths.
+
+## Process
+
+### 1. Identify Competitor ASINs
+- Use Keepa (see `skills/keepa/SKILL.md`) to find top competitors for the product category — start with `/search` by keyword, or `/bestsellers` for a category, then `/product` for details.
+- Select 5-10 ASINs that are direct competitors (same product type, similar price range)
+- Include a mix: top sellers + rising products
+
+### 2. Pull Keyword Data
+- Use Jungle Scout's `keywords_by_asin` endpoint (see `skills/jungle_scout/SKILL.md`) for each competitor ASIN
+- For exploration around a known phrase, use `keywords_by_keyword` instead
+- Export: keyword phrase, search volume, SV trend, PPC bids, competing products, sponsored ASINs, ranking competitors
+
+### 3. Build the Workbook
+
+#### Sheet: Raw Data
+- All keywords from Cerebro, unfiltered
+- Include all columns from the source
+
+#### Sheet: Filtered Keywords
+- Only includes **relevant** keywords — filtered by the Ranking Competitors relevancy test
+- **Relevancy test:** A keyword is relevant if ≥30% of the competitor ASINs rank for it. With 10 competitors that's ≥3; with 7-8 competitors that's ≥2. Adjust threshold based on competitor count.
+- "Raw Data" = full Cerebro dump (all columns, untouched). "Filtered Keywords" = relevant keywords only, simplified columns + root keyword classification + color coding.
+- Add a "Root Keyword" column that classifies each keyword by its root keyword group
+- Color-code rows by root keyword (matching the Root Keywords sheet colors)
+- Unclassified keywords stay white — this shows RKW coverage gaps
+
+**Why filter by Ranking Competitors:**
+- Cerebro pulls keywords from competitor ASINs, but competitors sell multiple product types
+- A competitor might rank for "card sleeves" but that doesn't make it relevant for deck boxes
+- Ranking Competitors count tells you how many of YOUR selected competitors actually rank for that keyword
+- If only 1 out of 7 competitors ranks for it, it's probably not relevant to the product category
+
+#### Sheet: Root Keywords
+- Group keywords into root keyword categories
+- Each root keyword gets a distinct pastel background color
+- Columns: Root Keyword, Total Search Volume, # Variants, Top 5 Variants, Avg PPC Bid, Notes
+
+**Root Keyword Rules:**
+- Root keywords must be **specific to the product type** — not generic category terms
+- ❌ BAD: "mtg accessories", "magic the gathering accessories", "card protector" (too generic, captures unrelated products)
+- ❌ BAD: "card sleeves", "booster box" (adjacent product categories, not the product being sold)
+- ✅ GOOD: "deck box", "mtg deck box", "commander deck box", "card storage box", "magnetic box"
+- Root keywords should describe **the product you're selling**, not adjacent products that share competitors
+- **NO catch-all "other" bucket.** Leave unmatched keywords with an empty Root Keyword field (uncolored). This makes gaps immediately visible — if too many rows are uncolored, you know you're missing root keywords.
+- Check the "Top 5 Variants" — if they include unrelated products (e.g., mahjong when researching MTG), the root keyword is too broad
+- When a keyword matches multiple root keywords, assign it to the **most specific** (longest match)
+- Unclassified keywords stay white/uncolored in Raw Keywords — this is a feature, not a bug. It shows coverage gaps at a glance.
+
+#### Sheet: Never Keywords (NKWs)
+- **Single words** (not phrases) that should be negated in BROAD PPC campaigns
+- A word is an NKW if we're SURE that a search term containing it does NOT describe our product — meaning the searcher would not buy our product
+- NKWs are about **product fit**, not niche. Example for a deck box:
+  - ✅ NKW: "dual" (our deck box holds one deck, not two)
+  - ✅ NKW: "binder" (completely different product format)
+  - ❌ NOT NKW: "pokemon" (someone could use our deck box for pokemon cards)
+  - ❌ NOT NKW: "yugioh" (same logic — different game, but same product use case)
+- Columns: Word, Reason, Source Keywords (examples of keywords containing this word)
+- **Competitor brand names** are NKWs — if someone searches "gamegenic deck box" they want that specific brand, not ours
+- Be conservative — when in doubt, do NOT add as NKW. False negatives (missing an NKW) waste some ad spend; false positives (wrongly blocking a word) lose sales.
+
+**How NKWs are used in PPC:**
+- EXACT campaign: targets each Filtered Keyword as exact match
+- BROAD campaign: targets each Filtered Keyword as broad match, negating:
+  1. All Filtered Keywords (already in EXACT)
+  2. All Never Keywords (would produce irrelevant search terms)
+- Goal of BROAD: discover new long-tail keywords based on Master List words
+
+#### Sheet: Master List
+- The final curated keyword list that feeds directly into PPC campaigns
+- Formula: `master_list = filtered_keywords × root_keywords / never_keywords`
+  - `×` (multiply/overlap): only Filtered Keywords that ARE classified under a Root Keyword
+  - `/` (divide/remove): exclude any keyword containing a word from the Never Keywords list
+- Contains the same data columns as Filtered Keywords (minus the Root Keyword column)
+- This is the sheet that gets used for EXACT and BROAD PPC campaigns
+
+#### Sheet: Single Words
+- Individual word frequency analysis from the **Master List** (not raw data)
+- Columns: Word, Count (how many Master List keywords contain this word)
+- Sorted by count descending
+- Helps identify core vocabulary for listings and potential missing NKWs
+
+#### Sheet: Amazon Listing
+- Suggested Amazon product title and 5 bullet points, optimized for keyword coverage
+- **Goal:** Include as many Single Words as possible while keeping the text readable, relevant, and compliant with Amazon guidelines
+
+**Title:**
+- Amazon max ~200 characters — aim for 190-200
+- Must contain all high-count words from Single Words (the most important keywords)
+- Higher-count words should appear earlier in the title
+- Format: `Brand - Product Type - Key Features - Use Case/Compatibility`
+- Must be readable and make sense — not keyword-stuffed
+
+**Bullet Points (5):**
+- Each bullet covers a different angle: specs, protection, compatibility, design, portability/gifting
+- Work in remaining Single Words that didn't fit in the title
+- Still must be readable and relevant to actual product features
+- Each bullet: ~200-350 chars
+
+**Counters & Tracking (built into the sheet):**
+- Title character count (vs Amazon max)
+- Title word count
+- Each bullet's character count
+- Total bullet characters
+- **Keyword Coverage section:** Total Single Words, Used in Title, Used in Bullets Only, Used Anywhere, NOT Used (with percentages)
+- **Top Unused Words:** Quick-reference list of highest-count unused words
+- **Full Word Usage Detail table:** Every Single Word with columns: Word, Count, In Title? (Yes/No), In Bullets? (Yes/No)
+  - Green row = used in title
+  - Yellow row = used in bullets only
+  - Red row = unused
+  - Yes/No cells: green background for Yes, red for No
+- **Notes column for unused words** explaining why each is unused:
+  - "Variant X already in listing" — e.g. "boxes" when "box" is present, "sleeves" when "sleeved" is used
+  - "Franchise/set name" — lorwyn, avatar, spiderman, etc.
+  - "Competitor brand" — shouldn't be in our listing
+  - "Color" — listing covers multiple variants
+  - "Material not applicable" — doesn't describe our product
+  - "Low priority / niche term" — catch-all for rare terms
+  - Feature-specific flags — "check if product has this feature" (e.g. dice tray, window)
+
+**Formatting:**
+- Dark blue section headers with white bold text
+- Light blue for title, light green for bullets, light yellow for stats
+- Orange for top unused quick-reference
+- Dark red separator for unused words section
+- Column B wide (800px) with text wrap for bullet readability
+- Column E (Notes) at 400px
+
+#### Sheet: PPC Setup
+- Complete PPC campaign setup ready for implementation
+- **Sections:**
+  1. **Campaign Structure** — overview table showing both campaigns, their match types, targeting, negatives, and goals
+  2. **EXACT Campaign Keywords** — all Master List keywords sorted by search volume, with suggested PPC bids (min/max/suggested)
+  3. **BROAD Campaign Keywords** — same keywords as EXACT (reference note)
+  4. **BROAD Campaign — Exact Negative Keywords** — all Master List keywords as exact negatives (to avoid overlap with EXACT campaign)
+  5. **BROAD Campaign — Phrase Negative Keywords** — all Never Keywords as phrase negatives (to block irrelevant search terms)
+  6. **Summary** — total counts for each section + bid statistics (avg/min/max)
+- **Formatting:**
+  - Dark blue section headers
+  - Green alternating rows for EXACT keywords
+  - Purple for BROAD campaign references
+  - Orange alternating rows for exact negatives
+  - Red alternating rows for phrase negatives
+  - Yellow for summary stats
+
+### 4. Color Coding
+- Assign each root keyword a distinct **pastel** color (HSV: saturation ~0.25, value 1.0)
+- Apply the color to the root keyword's row in the Root Keywords sheet
+- Apply the same color to all rows in Filtered Keywords that belong to that root keyword
+- If a keyword belongs to multiple root keywords, assign it to one (most specific) and color accordingly
+
+### 5. Upload to Google Drive
+- Create as a Google Sheet (not xlsx) directly via API
+- Place in the appropriate product folder (e.g., `Brands / [Brand] / Product line - [Product] /`)
+- Name format: "Keyword research - [Product name]"
+- Match parent folder permissions when sharing
+
+### 6. Sheet Formatting
+- **Freeze row 1 and column A** on all sheets (for easy scrolling)
+- **Add filters** on all columns of every sheet
+- **Numbers must be numbers** — use `valueInputOption='USER_ENTERED'` when writing to Google Sheets so numeric values are treated as numbers, not text. Never write numbers as strings (no leading apostrophe). This enables proper sorting/filtering.
+- These are standard — apply to every workbook, every time
+
+## Quality Checks
+- [ ] Filtered Keywords only contains relevant keywords (≥30% of competitors ranking)
+- [ ] Raw Data contains the full unfiltered Cerebro dump
+- [ ] Root keywords are specific to the product, not generic category terms
+- [ ] Top 5 Variants for each root keyword are all relevant to the actual product
+- [ ] No "other" catch-all bucket — unclassified keywords stay blank/uncolored
+- [ ] Colors are applied consistently between Root Keywords and Filtered Keywords
+- [ ] Sheet is in the correct Drive folder with proper permissions
+
+---
+> **Core skill** (read-only, updated by the platform).
+> If you need to add customer-specific knowledge, IDs, preferences, or learnings for this skill,
+> create an extension at `workspace/skills/amazon-kw-research/SKILL.md` — do not modify this file.