superx-cli 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.6.0 (2026-09-18)
+
+- Skills layout: the skill now lives at `skills/superx/`, one folder per SuperX skill under `skills/superx/references/skills/<id>/` (`recipe.md` for the agent, `card.json` for the app). `SKILL.md` is route-first and under 500 lines: the command list moved verbatim to `references/commands.md`, the growth strategy guide to `references/growth-strategy.md`, and the skills index is generated. The root `SKILL.md`, `PLAYBOOK.md` and `PLAYBOOKS.md` are gone, and "playbook" is now only the name of the SuperX blog freebie
+- Skills install: `superx skills:list` prints every bundled skill (id, name, category) as JSON, and `superx skills:install` puts the skill where your agent looks for it (`~/.claude/skills` and `~/.agents/skills` by default, `--target claude|agents|openclaw|all`, `--project` for the current directory, `--copy` instead of a symlink). Re-running is safe and nothing ever runs on `npm install`
+- Skills set: 30 skills, up from 29 recipes and 29 app cards that were not the same 29. Worker Output Review gained its app card and Find Your Story gained its recipe, so every skill now ships both
+- New skill Viral Score Loop (viral-score-iterate): score a draft, rewrite keyed on what hurt, rescore, stop on warnings. Skills are now 31.
+- Renamed skill ids: `reply-like-a-pro` is now `reply-to-any-post` and `launch-announcement-campaign` is now `reply-to-dm-campaign`, matching the names they have had for a while
+- Skills content fixes: Instant Lead Hunt carries `signals:search --offer` and `--max-age-days` and prices the hunt honestly (it was "No extra cost"), Viral Format Remix says 3 AI credits per draft instead of "No extra cost", and Lead Review says the fit or not-fit verdicts are recorded
+- `npm run skills:build` regenerates the `SKILL.md` index, the server catalog and the docs page from the folders; `npm run skills:check` fails when any of the three is stale and runs on `prepublishOnly`
+- Viral Score: `posts:viral-score --text "..."` scores ONE draft from 0 to 100 against the account's OWN recent posts, with what helped and what hurt in plain English and an expected multiple on likes, replies, reposts+quotes and views versus that account's own median post. `--image`, `--video`, `--quote` and `--post-at` describe how the post would go out, and `--population` scores against the average training post instead (an account with fewer than 10 recent originals falls back to that on its own). Reposts+quotes and views carry `confidence: "low"`. It compares a draft with the account's normal post: it is not a reach prediction and it knows nothing about follower count. `warnings` name what the score never rewards (asking for replies, inviting people to connect, a borrowed template, sending readers off the platform), so a warning means rewrite rather than work around it. Cheap on purpose so drafts can be iterated: most calls charge no credits, one in ten charges 1, and the first call for an account charges 1 more while its baseline is built. `SKILL.md` carries the iterate-until-it-stops-rising recipe
+- Removed: `tools:predict`. It compared two drafts on a model's opinion and was never measured against real posts; `posts:viral-score` replaces it with a score fit on real same-author outcomes
+
 ## 0.5.2 (2026-09-16)
 
 - Lead search offer: `signals:search --offer "<one sentence on what you sell>"` (3-300 chars) tells the search what is being sold, and it plans up to 10 buyer-side query angles from that (workflows, pain, competitors, brand, adjacent) instead of running your keywords verbatim. `--keywords` are now 2-5 short seed angles of how the BUYER talks (a symptom, a tool they already pay for, their jargon), not the product's name and no search operators. Adding `--offer` is the single biggest lever on lead quality; `SKILL.md` carries the updated recipe

package/README.md

@@ -4,6 +4,10 @@
 npx skills add superx-so/superx-agent
 ```
 
+Already have the CLI? `superx skills:install` puts the same skill in
+`~/.claude/skills/superx` and `~/.agents/skills/superx` (`--target openclaw`,
+`--project`, `--copy`).
+
 # SuperX CLI
 
 **Twitter/X growth CLI for developers and AI agents.** Read your posts and their metrics, pull account analytics, find the people who engage with you most, create draft or scheduled posts and threads (with image attachments), write, schedule, and publish long-form X Articles (with AI cover generation), and read or update the Context settings that steer SuperX's AI writing through the [SuperX API](https://docs.superx.so).
@@ -11,7 +15,7 @@ npx skills add superx-so/superx-agent
 Two things ship in this repo:
 
 - `superx-cli`, an npm package installing the `superx` binary (a thin client for `api.superx.so/v1`)
-- An agent skill (`SKILL.md`) plus a growth strategy guide (`PLAYBOOK.md`) and 29 goal-shaped recipes (`PLAYBOOKS.md`) so agents do not just schedule posts, they follow a strategy that works
+- An agent skill (`skills/superx/SKILL.md`) plus a growth strategy guide (`references/growth-strategy.md`) and a goal-shaped skill for every SuperX workflow (`references/skills/`) so agents do not just schedule posts, they follow a strategy that works
 
 ---
 
@@ -342,9 +346,9 @@ superx docs   # Prints the API quickstart as markdown; works without auth
 
 ## Features for AI agents
 
-- **Skill included**: `npx skills add superx-so/superx-agent` installs [SKILL.md](./SKILL.md), a complete agent reference with hard rules, workflows, and gotchas.
-- **Strategy included**: [PLAYBOOK.md](./PLAYBOOK.md) distills the SuperX growth methodology (action hierarchy, out-of-network discovery, the 3-3-3 engagement loop, weekly operating system) into directives an agent can execute with this CLI. The skill instructs agents to read it before creating content.
-- **Playbooks included**: [PLAYBOOKS.md](./PLAYBOOKS.md) holds 29 goal-shaped recipes, one per SuperX skill, each with its CLI chain, the matching MCP tool chain, and the point where the agent hands the result back to a person.
+- **Skill included**: `npx skills add superx-so/superx-agent`, or `superx skills:install` once the CLI is on the machine, installs [skills/superx](./skills/superx/SKILL.md), a route-first agent reference with the hard rules, the workflow, the gotchas and a [full command reference](./skills/superx/references/commands.md).
+- **Strategy included**: [references/growth-strategy.md](./skills/superx/references/growth-strategy.md) distills the SuperX growth methodology (action hierarchy, out-of-network discovery, the 3-3-3 engagement loop, weekly operating system) into directives an agent can execute with this CLI. The skill instructs agents to read it before creating content.
+- **Skills included**: [references/skills/](./skills/superx/references/skills) holds one folder per SuperX skill, each with its CLI chain, the matching MCP tool chain, and the point where the agent hands the result back to a person.
 - **Clean JSON stdout**: no decoration to strip; every data command is `jq`-safe.
 - **Idempotent writes**: agents can retry `scheduled:create` safely with `--idempotency-key`.
 - **Self-describing**: `superx docs` fetches the current API quickstart at runtime.
@@ -357,7 +361,7 @@ superx accounts
 superx posts:list --sort likes --limit 10          # study what works
 superx posts:analytics                             # check the trend
 superx contacts:list --sort engagement --limit 10  # who to engage today
-# ... read PLAYBOOK.md, draft content ...
+# ... read references/growth-strategy.md, draft content ...
 superx scheduled:create --text "Draft for review"  # draft first
 superx scheduled:list --status draft
 ```

package/dist/index.js

@@ -197,8 +197,9 @@ var SuperXAPI = class {
   async factCheck(body) {
     return (await this.request("/tools/factcheck", { method: "POST", body })).json;
   }
-  async predictAlgorithm(body) {
-    return (await this.request("/tools/algorithm-predict", { method: "POST", body })).json;
+  /** Score ONE draft against the account's own normal post. */
+  async viralScore(body) {
+    return (await this.request("/posts/viral-score", { method: "POST", body })).json;
   }
   /** Draft ONE reply to a post. Text only: a person posts it. */
   async draftReply(body) {
@@ -654,7 +655,7 @@ function getConfig() {
 
 // src/commands/auth.ts
 function promptForKey() {
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     const rl = readline.createInterface({
       input: process.stdin,
       output: process.stderr
@@ -662,7 +663,7 @@ function promptForKey() {
     });
     rl.question("Paste your API key (sxk_...): ", (answer) => {
       rl.close();
-      resolve(answer.trim());
+      resolve2(answer.trim());
     });
   });
 }
@@ -799,6 +800,17 @@ async function postsRemix(argv) {
   const api = new SuperXAPI(getConfig());
   printJson(await api.remixPost(body));
 }
+async function postsViralScore(argv) {
+  const body = { text: argv.text };
+  if (argv.image) body.has_image = true;
+  if (argv.video) body.has_video = true;
+  if (argv.quote) body.is_quote = true;
+  if (argv.postAt) body.post_at = argv.postAt;
+  if (argv.population) body.baseline = "population";
+  if (argv.account) body.account_id = argv.account;
+  const api = new SuperXAPI(getConfig());
+  printJson(await api.viralScore(body));
+}
 
 // src/commands/tools.ts
 async function toolsInlineEdit(argv) {
@@ -826,12 +838,6 @@ async function toolsFactcheck(argv) {
   const api = new SuperXAPI(getConfig());
   printJson(await api.factCheck(body));
 }
-async function toolsPredict(argv) {
-  const body = { version_a: argv.a, version_b: argv.b };
-  if (argv.account) body.account_id = argv.account;
-  const api = new SuperXAPI(getConfig());
-  printJson(await api.predictAlgorithm(body));
-}
 
 // src/commands/inspiration.ts
 async function inspirationSearch(argv) {
@@ -1093,7 +1099,7 @@ async function waitForDataset(api, started) {
   const deadline = Date.now() + WAIT_TIMEOUT_MS;
   let latest = started;
   while (Date.now() < deadline) {
-    await new Promise((resolve) => setTimeout(resolve, WAIT_POLL_MS));
+    await new Promise((resolve2) => setTimeout(resolve2, WAIT_POLL_MS));
     latest = await api.getDataset(datasetId);
     if (latest?.data?.status !== "collecting") {
       printJson(latest);
@@ -2316,6 +2322,206 @@ async function queueSet(argv) {
   printJson(await api.updateQueueSettings(body));
 }
 
+// src/commands/skills.ts
+var fs4 = __toESM(require("fs"));
+var os2 = __toESM(require("os"));
+var path4 = __toESM(require("path"));
+var SKILL_NAME = "superx";
+function packageSkillDir() {
+  return path4.join(__dirname, "..", "skills", SKILL_NAME);
+}
+function skillsRefDir() {
+  return path4.join(packageSkillDir(), "references", "skills");
+}
+function readJson(file) {
+  return JSON.parse(fs4.readFileSync(file, "utf8"));
+}
+async function skillsList() {
+  const dir = skillsRefDir();
+  const meta = readJson(path4.join(dir, "categories.json"));
+  const categoryOrder = meta.categories.map((c) => c.id);
+  const rows = fs4.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => {
+    const card = readJson(path4.join(dir, e.name, "card.json"));
+    return {
+      id: e.name,
+      name: card.name,
+      category: card.category,
+      order: card.order
+    };
+  }).sort((a, b) => {
+    const ca = categoryOrder.indexOf(a.category);
+    const cb = categoryOrder.indexOf(b.category);
+    if (ca !== cb) return ca - cb;
+    return a.order - b.order;
+  }).map(({ id, name, category }) => ({ id, name, category }));
+  printJson({
+    data: rows,
+    meta: { count: rows.length, skills_dir: dir, categories: meta.categories }
+  });
+}
+function homeTargets(target) {
+  const home = os2.homedir();
+  const claude = {
+    label: "claude",
+    dest: path4.join(home, ".claude", "skills", SKILL_NAME)
+  };
+  const agents = {
+    label: "agents",
+    dest: path4.join(home, ".agents", "skills", SKILL_NAME)
+  };
+  const openclaw = {
+    label: "openclaw",
+    dest: path4.join(home, ".openclaw", "skills", SKILL_NAME)
+  };
+  if (target === "claude") return [claude];
+  if (target === "agents") return [agents];
+  if (target === "openclaw") return [openclaw];
+  if (target === "all") return [claude, agents, openclaw];
+  const targets = [claude, agents];
+  if (fs4.existsSync(path4.join(home, ".openclaw"))) targets.push(openclaw);
+  return targets;
+}
+function projectTargets(target) {
+  const cwd = process.cwd();
+  const claude = {
+    label: "claude",
+    dest: path4.join(cwd, ".claude", "skills", SKILL_NAME)
+  };
+  const agents = {
+    label: "agents",
+    dest: path4.join(cwd, ".agents", "skills", SKILL_NAME)
+  };
+  const workspace = {
+    label: "workspace",
+    dest: path4.join(cwd, "skills", SKILL_NAME)
+  };
+  if (target === "claude") return [claude];
+  if (target === "agents") return [agents];
+  if (target === "openclaw") return [workspace];
+  return [claude, agents, workspace];
+}
+function copyTree(src, dest) {
+  fs4.mkdirSync(dest, { recursive: true });
+  for (const entry of fs4.readdirSync(src, { withFileTypes: true })) {
+    const from = path4.join(src, entry.name);
+    const to = path4.join(dest, entry.name);
+    if (entry.isDirectory()) copyTree(from, to);
+    else if (entry.isFile()) fs4.copyFileSync(from, to);
+  }
+}
+function copySkillTree(src, dest) {
+  if (!fs4.existsSync(path4.join(src, "SKILL.md"))) {
+    throw new Error(`refusing to copy: ${src} has no SKILL.md`);
+  }
+  try {
+    copyTree(src, dest);
+  } catch (err) {
+    fs4.rmSync(dest, { recursive: true, force: true });
+    throw err;
+  }
+}
+function isSameDirectory(dest, source) {
+  try {
+    if (fs4.lstatSync(dest).isSymbolicLink()) return false;
+  } catch {
+    return false;
+  }
+  if (path4.resolve(dest) === path4.resolve(source)) return true;
+  try {
+    return fs4.realpathSync(dest) === fs4.realpathSync(source);
+  } catch {
+    return false;
+  }
+}
+function isManagedInstall(dest) {
+  let stat;
+  try {
+    stat = fs4.lstatSync(dest);
+  } catch {
+    return false;
+  }
+  if (stat.isSymbolicLink()) return true;
+  if (!stat.isDirectory()) return false;
+  if (!fs4.existsSync(path4.join(dest, "references", "skills", "categories.json"))) {
+    return false;
+  }
+  let head;
+  try {
+    head = fs4.readFileSync(path4.join(dest, "SKILL.md"), "utf8").slice(0, 4096);
+  } catch {
+    return false;
+  }
+  const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(head);
+  if (!frontmatter) return false;
+  return new RegExp(`^name:\\s*${SKILL_NAME}\\s*$`, "m").test(frontmatter[1]);
+}
+function install(source, t, copy) {
+  let exists = true;
+  try {
+    fs4.lstatSync(t.dest);
+  } catch {
+    exists = false;
+  }
+  if (exists && isSameDirectory(t.dest, source)) return { action: "unchanged" };
+  if (exists) {
+    if (!isManagedInstall(t.dest)) {
+      return {
+        action: "skipped",
+        error: `${t.dest} already exists and is not a copy of this skill; move or remove it first, then run skills:install again`
+      };
+    }
+    if (!copy) {
+      try {
+        if (fs4.realpathSync(t.dest) === fs4.realpathSync(source)) return { action: "unchanged" };
+      } catch {
+      }
+    }
+    fs4.rmSync(t.dest, { recursive: true, force: true });
+  }
+  fs4.mkdirSync(path4.dirname(t.dest), { recursive: true });
+  if (!copy) {
+    try {
+      fs4.symlinkSync(source, t.dest, "dir");
+      return { action: exists ? "relinked" : "linked" };
+    } catch (err) {
+      note(`Symlink failed for ${t.dest} (${err?.code || err?.message}); copying instead.`);
+    }
+  }
+  copySkillTree(source, t.dest);
+  return { action: "copied" };
+}
+async function skillsInstall(argv) {
+  const source = packageSkillDir();
+  if (!fs4.existsSync(path4.join(source, "SKILL.md"))) {
+    note(`Error: no skill found at ${source}. Reinstall superx-cli.`);
+    process.exit(1);
+  }
+  const targets = argv.project ? projectTargets(argv.target) : homeTargets(argv.target);
+  const results = targets.map((t) => {
+    let outcome;
+    try {
+      outcome = install(source, t, Boolean(argv.copy));
+    } catch (err) {
+      outcome = { action: "failed", error: err?.message || String(err) };
+    }
+    if (outcome.error) note(`${t.label}: ${outcome.error}`);
+    else note(`${t.label}: ${outcome.action} ${t.dest}`);
+    return { target: t.label, path: t.dest, ...outcome };
+  });
+  const failed = results.filter((r) => r.error).length;
+  printJson({
+    data: {
+      skill: SKILL_NAME,
+      source,
+      mode: argv.copy ? "copy" : "symlink",
+      scope: argv.project ? "project" : "home",
+      targets: results
+    },
+    meta: { installed: results.length - failed, failed }
+  });
+  if (failed) process.exit(1);
+}
+
 // src/commands/docs.ts
 async function docs() {
   const apiUrl = resolveApiUrl(loadCredentials()?.apiUrl || DEFAULT_API_URL);
@@ -2513,12 +2719,15 @@ var advancedSettingsOptions = (y) => y.option("auto-retweet", {
   ),
   run(toolsFactcheck)
 ).command(
-  "tools:predict",
-  "Score two versions of a post against what the timeline rewards (costs AI credits)",
-  (y) => accountOption(y).option("a", { describe: "The first version (required)", type: "string", demandOption: true }).option("b", { describe: "The second version (required)", type: "string", demandOption: true }).example('$0 tools:predict --a "$(cat v1.txt)" --b "$(cat v2.txt)"', "Compare two drafts").epilogue(
-    "The scores are a model's opinion, useful for comparing two drafts against each other, not a prediction of real reach."
+  "posts:viral-score",
+  "Score one draft against this account's own normal post, with what helped and what hurt",
+  (y) => accountOption(y).option("text", { describe: "The draft to score (required, max 4000 chars)", type: "string", demandOption: true }).option("image", { describe: "An image would be attached", type: "boolean" }).option("video", { describe: "A video would be attached", type: "boolean" }).option("quote", { describe: "The post quotes another post", type: "boolean" }).option("post-at", { describe: "When it would go out (UTC ISO-8601)", type: "string" }).option("population", {
+    describe: "Score against the average training post instead of this account's own posts",
+    type: "boolean"
+  }).example('$0 posts:viral-score --text "$(cat draft.txt)"', "Score a draft before you send it").example('$0 posts:viral-score --text "..." --image', "Score it as a post with an image").epilogue(
+    "The score compares this draft with the account's OWN recent posts. It is not a reach prediction and it knows nothing about follower count. Rewrite and score again until the score stops rising, and read any warnings as a stop sign: asking for replies or sending readers off the platform can never raise it."
   ),
-  run(toolsPredict)
+  run(postsViralScore)
 ).command(
   "replies:list",
   "List replies the account has sent (newest first)",
@@ -3495,6 +3704,30 @@ var advancedSettingsOptions = (y) => y.option("auto-retweet", {
   "Show the account's DM allowances and how much of each is used (free)",
   (y) => accountOption(y),
   run(dmLimits)
+).command(
+  "skills:list",
+  "List the SuperX skills bundled with this package (no auth needed)",
+  (y) => y.example("$0 skills:list", "Every skill's id, name and category as JSON").epilogue(
+    "Each skill's recipe is at <skills_dir>/<id>/recipe.md and its app card at card.json. Install the skill for your agent with skills:install."
+  ),
+  run(skillsList)
+).command(
+  "skills:install",
+  "Install the bundled SuperX skill where your agent looks for skills",
+  (y) => y.option("target", {
+    describe: "Where to install: claude (~/.claude/skills), agents (~/.agents/skills), openclaw (~/.openclaw/skills), all. Default: claude + agents, plus openclaw when ~/.openclaw exists",
+    type: "string",
+    choices: ["claude", "agents", "openclaw", "all"]
+  }).option("project", {
+    describe: "Install into the current directory (.claude/skills, .agents/skills, skills) instead of your home directory",
+    type: "boolean"
+  }).option("copy", {
+    describe: "Copy the files instead of symlinking them (also the automatic fallback when a symlink is refused)",
+    type: "boolean"
+  }).example("$0 skills:install", "Symlink the skill into ~/.claude/skills and ~/.agents/skills").example("$0 skills:install --project --copy", "Copy it into this repo for everyone working in it").epilogue(
+    "Re-running is safe: an install that already points at this package is left alone. Nothing runs on npm install; this command is the only thing that writes outside the package."
+  ),
+  run(skillsInstall)
 ).command("docs", "Print the SuperX API quickstart (markdown, no auth needed)", {}, run(docs)).demandCommand(1, "Specify a command. Run: superx --help").strict().help().alias("h", "help").version().wrap(Math.min(100, process.stdout.columns || 100)).fail((msg, err) => {
   if (err) throw err;
   note(msg || "Invalid usage. Run: superx --help");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superx-cli",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "SuperX CLI - command line interface to the SuperX API for Twitter/X growth: read posts and analytics, find engaged contacts, and schedule posts and threads",
   "main": "dist/index.js",
   "bin": {
@@ -10,14 +10,14 @@
     "dev": "tsup --watch",
     "build": "tsup",
     "start": "node ./dist/index.js",
-    "prepublishOnly": "npm run build"
+    "skills:build": "node scripts/skills.mjs build --server ../superx-server --docs ../superx-docs",
+    "skills:check": "node scripts/skills.mjs check --server ../superx-server --docs ../superx-docs",
+    "prepublishOnly": "npm run skills:check && npm run build"
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
-    "SKILL.md",
-    "PLAYBOOK.md",
-    "PLAYBOOKS.md",
     "CHANGELOG.md",
     "LICENSE"
   ],