@floomhq/floom 1.0.0 → 1.0.2

package/README.md

@@ -4,10 +4,14 @@ Publish AI skills from your terminal. Share them with a link. Add other people's
 
 ```bash
 npm install -g @floomhq/floom
+floom init my-skill.md
 floom login
 floom publish my-skill.md
+floom search review
 floom add awesome-skill
+floom setup --target claude --dry-run
 floom list
+floom library list
 ```
 
 Returns a shareable link like `https://floom.dev/s/ffas93ud`. Anyone with the URL can read the raw Markdown — drop it into any AI tool that accepts skills.
@@ -20,8 +24,17 @@ Returns a shareable link like `https://floom.dev/s/ffas93ud`. Anyone with the UR
 - `floom list` — show your published skills. Optional `--json`.
 - `floom add <url-or-slug>` — fetch a skill into `~/.claude/skills/<slug>.md`.
 - `floom info <url-or-slug>` — show skill metadata. Optional `--json`.
-- `floom sync` — preview: pull your own Floom-published skills into `~/.claude/skills/`.
+- `floom search <query>` — search public skills and starter libraries. Optional `--library <slug>`, `--type knowledge|instruction|workflow|skill`, and `--json`.
+- `floom setup` — add Floom usage guidance to `CLAUDE.md` or `AGENTS.md`. Optional `--target claude|codex`, `--dry-run`, `--yes`.
+- `floom connect` — alias for `floom setup`.
+- `floom mcp` — print MCP setup commands for supported agent CLIs.
+- `floom sync` — preview: pull your published, saved, and subscribed library skills into `~/.claude/skills/`.
 - `floom watch` — preview: run `floom sync` repeatedly. Optional `--interval <seconds>`; minimum `10`.
+- `floom library list` — list public starter libraries. Optional `--json`.
+- `floom library create <slug> --name <name>` — create a personal or starter library. Optional `--public` / `--private` / `--unlisted`.
+- `floom library add <library> <skill> [--folder <path>] [--tags a,b]` — add a skill to a library.
+- `floom library subscribe <slug>` — subscribe to a public or unlisted library so sync can pull it locally.
+- `floom move <slug> --folder <path>` — set your local folder override for a saved or library skill.
 - `floom delete <url-or-slug>` — delete one of your published skills. Optional `--yes`.
 - `floom doctor` — diagnose your Floom setup.
 - `floom whoami` — show the signed-in account.
@@ -46,7 +59,7 @@ version: 0.1.0
 
 Override the API host with `FLOOM_API_URL` (defaults to `https://floom.dev`).
 
-`floom sync` and `floom watch` are Version 1 preview commands for your own published skills. They store a machine-local manifest at `~/.floom/sync-manifest.json`.
+`floom sync` and `floom watch` are Version 1 preview commands for published, saved, and subscribed library skills. They store a machine-local manifest at `~/.floom/sync-manifest.json`.
 The manifest records hashes for files Floom previously wrote. Version 1 sync writes missing files
 only. Remote updates, existing untracked files, and locally edited tracked files are skipped as
 conflicts. Symlinks are never followed. To accept the Floom version, move or delete the local file

package/dist/cli.js

@@ -11,19 +11,21 @@ import { info } from "./info.js";
 import { deleteSkill } from "./delete.js";
 import { doctor } from "./doctor.js";
 import { sync } from "./sync.js";
+import { printMcpSetup } from "./mcp.js";
+import { setupAgent } from "./setup.js";
+import { search } from "./search.js";
+import { libraryAddSkill, libraryCreate, libraryList, libraryRemoveSkill, librarySubscribe, libraryUnsubscribe, moveSkill, } from "./library.js";
 import { c, symbols } from "./ui.js";
 import { printError, FloomError } from "./errors.js";
-const VERSION = "1.0.0";
+const VERSION = "1.0.2";
 const PKG = { name: "@floomhq/floom", version: VERSION };
 const V1_NOT_AVAILABLE = "Not available in Floom Version 1.";
 function usage() {
     const out = `
- ${c.coral("     ____       __")}
- ${c.coral("    / __ \\___  / /___ ___  __")}
- ${c.coral("   / /_/ / _ \\/ / __ `/ / / /")}
- ${c.coral("  / _, _/  __/ / /_/ / /_/ /")}
- ${c.coral(" /_/ |_|\\___/_/\\__,_/\\__, /")}   ${c.dim(`v${VERSION}`)}
- ${c.coral("                    /____/")}
+ ${c.coral("  __ _")}
+ ${c.coral(" / _| |___  ___ _ __")}   ${c.dim(`v${VERSION}`)}
+ ${c.coral("|  _| / _ \\/ _ \\ '  \\")}
+ ${c.coral("|_| |_\\___/\\___/_|_|_|")}
 
  ${c.bold("Share AI agent skills with a link.")}
  ${c.dim("Publish knowledge, instructions, and workflows from your terminal.")}
@@ -32,6 +34,9 @@ function usage() {
    ${c.cyan("floom")} ${c.dim("<command> [options]")}
 
  ${c.bold("Start Here")}
+   ${c.cyan("floom init")} ${c.dim("support-tone.md")}
+      ${c.dim("Create a starter Markdown skill.")}
+
    ${c.cyan("floom add")} ${c.dim("https://floom.dev/s/ffas93ud")}
       ${c.dim("Install a public skill. No account needed.")}
 
@@ -39,9 +44,10 @@ function usage() {
       ${c.dim("Publish Markdown and print a share link.")}
 
  ${c.bold("Commands")}
-   ${c.dim("Receive")}
+     ${c.dim("Receive")}
      ${c.cyan("add")} ${c.dim("<url-or-slug>")}             Install into ~/.claude/skills/
      ${c.cyan("info")} ${c.dim("<url-or-slug>")}            Show metadata ${c.dim("[--json]")}
+     ${c.cyan("search")} ${c.dim("<query>")}                Search public skills and libraries ${c.dim("[--json]")}
 
    ${c.dim("Create")}
      ${c.cyan("init")} ${c.dim("[file.md]")}                Create a starter skill file
@@ -57,13 +63,18 @@ function usage() {
    ${c.dim("Account")}
      ${c.cyan("login")}                         Sign in with Google
      ${c.cyan("list")}                          List your published skills ${c.dim("[--json]")}
+     ${c.cyan("library")}                       Create, browse, and subscribe to skill libraries
+     ${c.cyan("move")} ${c.dim("<slug> --folder <path>")}  Place a saved skill in a local folder
      ${c.cyan("delete")} ${c.dim("<url-or-slug>")}          Delete one of your skills ${c.dim("[--yes]")}
      ${c.cyan("whoami")}                        Show the signed-in account
      ${c.cyan("logout")}                        Delete local credentials
 
    ${c.dim("System")}
-     ${c.cyan("sync")}                          Preview: pull your own published skills
-     ${c.cyan("watch")}                         Preview: poll your own published skills ${c.dim("[--interval <seconds>, min 10]")}
+     ${c.cyan("setup")} ${c.dim("[--target claude|codex] [--file path]")}  Add Floom guidance to agent instructions
+     ${c.cyan("connect")} ${c.dim("[--target claude|codex]")}              Alias for setup
+     ${c.cyan("mcp")}                           Print MCP setup guidance
+     ${c.cyan("sync")}                          Preview: pull published, saved, and library skills
+     ${c.cyan("watch")}                         Preview: poll published, saved, and library skills ${c.dim("[--interval <seconds>, min 10]")}
      ${c.cyan("doctor")}                        Diagnose auth, API, and local setup
      ${c.cyan("--help")}                        Show this help
      ${c.cyan("--version")}                     Show version
@@ -165,6 +176,36 @@ function parseInfoFlags(argv) {
     }
     return out;
 }
+function parseSearchFlags(argv) {
+    const out = { json: false };
+    const terms = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] ?? "";
+        if (a === "--json")
+            out.json = true;
+        else if (a === "--library" || a.startsWith("--library=")) {
+            const { value, nextIndex } = readFlagValue(argv, i, "--library");
+            out.library = value;
+            i = nextIndex;
+        }
+        else if (a === "--type" || a.startsWith("--type=")) {
+            const { value, nextIndex } = readFlagValue(argv, i, "--type");
+            if (!ASSET_TYPES.has(value)) {
+                throw new FloomError(`Invalid --type: ${value}`, "Use one of: knowledge, instruction, workflow, skill.");
+            }
+            out.type = value;
+            i = nextIndex;
+        }
+        else if (a.startsWith("--")) {
+            throw new FloomError(`Unknown flag: ${a}`, "Try `floom search \"support tone\" --type instruction`.");
+        }
+        else {
+            terms.push(a);
+        }
+    }
+    out.query = terms.join(" ").trim();
+    return out;
+}
 function parseDeleteFlags(argv) {
     const out = { yes: false };
     for (const a of argv) {
@@ -177,6 +218,164 @@ function parseDeleteFlags(argv) {
     }
     return out;
 }
+function parseSetupFlags(argv) {
+    const out = { dryRun: false, yes: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] ?? "";
+        if (a === "--dry-run" || a === "--preview")
+            out.dryRun = true;
+        else if (a === "--yes" || a === "-y")
+            out.yes = true;
+        else if (a === "--target" || a.startsWith("--target=")) {
+            const { value, nextIndex } = readFlagValue(argv, i, "--target");
+            if (value !== "claude" && value !== "codex") {
+                throw new FloomError("Invalid --target.", "Use `claude` or `codex`.");
+            }
+            out.target = value;
+            i = nextIndex;
+        }
+        else if (a === "--file" || a.startsWith("--file=")) {
+            const { value, nextIndex } = readFlagValue(argv, i, "--file");
+            out.file = value;
+            i = nextIndex;
+        }
+        else if (a.startsWith("--")) {
+            throw new FloomError(`Unknown flag: ${a}`, "Try `floom setup --target codex --dry-run`.");
+        }
+        else if (!out.file)
+            out.file = a;
+        else
+            throw new FloomError(`Unexpected argument: ${a}`, "Try `floom setup --target claude --yes`.");
+    }
+    return out;
+}
+function normalizeFolder(value) {
+    return value === "root" || value === "/" || value === "." ? null : value;
+}
+function parseFolderTagFlags(argv) {
+    const out = { tags: [], rest: [] };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] ?? "";
+        if (a === "--folder" || a.startsWith("--folder=")) {
+            const { value, nextIndex } = readFlagValue(argv, i, "--folder");
+            out.folder = normalizeFolder(value);
+            i = nextIndex;
+        }
+        else if (a === "--root") {
+            out.folder = null;
+        }
+        else if (a === "--tag" || a.startsWith("--tag=")) {
+            const { value, nextIndex } = readFlagValue(argv, i, "--tag");
+            out.tags.push(value);
+            i = nextIndex;
+        }
+        else if (a === "--tags" || a.startsWith("--tags=")) {
+            const { value, nextIndex } = readFlagValue(argv, i, "--tags");
+            out.tags.push(...value.split(",").map((tag) => tag.trim()).filter(Boolean));
+            i = nextIndex;
+        }
+        else if (a.startsWith("--")) {
+            throw new FloomError(`Unknown flag: ${a}`, "Use --folder <path>, --root, --tag <tag>, or --tags a,b.");
+        }
+        else {
+            out.rest.push(a);
+        }
+    }
+    return out;
+}
+function parseLibraryCreateFlags(argv) {
+    const out = { visibility: "unlisted" };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] ?? "";
+        if (a === "--name" || a.startsWith("--name=")) {
+            const { value, nextIndex } = readFlagValue(argv, i, "--name");
+            out.name = value;
+            i = nextIndex;
+        }
+        else if (a === "--description" || a.startsWith("--description=")) {
+            const { value, nextIndex } = readFlagValue(argv, i, "--description");
+            out.description = value;
+            i = nextIndex;
+        }
+        else if (a === "--public")
+            out.visibility = "public";
+        else if (a === "--private")
+            out.visibility = "private";
+        else if (a === "--unlisted")
+            out.visibility = "unlisted";
+        else if (a.startsWith("--")) {
+            throw new FloomError(`Unknown flag: ${a}`, "Try `floom library create team-onboarding --name \"Team onboarding\"`.");
+        }
+        else if (!out.slug)
+            out.slug = a;
+        else
+            throw new FloomError(`Unexpected argument: ${a}`, "Try `floom library create <slug> --name <name>`.");
+    }
+    return out;
+}
+async function runLibrary(argv) {
+    const [subcommand, ...rest] = argv;
+    switch (subcommand ?? "list") {
+        case "list": {
+            const flags = parseListFlags(rest);
+            await libraryList(flags);
+            return;
+        }
+        case "create": {
+            const flags = parseLibraryCreateFlags(rest);
+            if (!flags.slug)
+                throw new FloomError("Missing library slug.", "Try `floom library create team-onboarding --name \"Team onboarding\"`.");
+            if (!flags.name)
+                throw new FloomError("Missing --name.", "Try `floom library create team-onboarding --name \"Team onboarding\"`.");
+            await libraryCreate({
+                slug: flags.slug,
+                name: flags.name,
+                ...(flags.description !== undefined ? { description: flags.description } : {}),
+                visibility: flags.visibility,
+            });
+            return;
+        }
+        case "add": {
+            const flags = parseFolderTagFlags(rest);
+            const [librarySlug, skillSlug] = flags.rest;
+            if (!librarySlug || !skillSlug) {
+                throw new FloomError("Missing library or skill slug.", "Try `floom library add team-onboarding support-tone --folder support`.");
+            }
+            await libraryAddSkill({
+                librarySlug,
+                skillSlug,
+                ...(flags.folder !== undefined ? { folder: flags.folder } : {}),
+                tags: flags.tags,
+            });
+            return;
+        }
+        case "remove":
+        case "rm": {
+            const [librarySlug, skillSlug] = rest;
+            if (!librarySlug || !skillSlug) {
+                throw new FloomError("Missing library or skill slug.", "Try `floom library remove team-onboarding support-tone`.");
+            }
+            await libraryRemoveSkill(librarySlug, skillSlug);
+            return;
+        }
+        case "subscribe": {
+            const slug = rest[0];
+            if (!slug)
+                throw new FloomError("Missing library slug.", "Try `floom library subscribe superpowers`.");
+            await librarySubscribe(slug);
+            return;
+        }
+        case "unsubscribe": {
+            const slug = rest[0];
+            if (!slug)
+                throw new FloomError("Missing library slug.", "Try `floom library unsubscribe superpowers`.");
+            await libraryUnsubscribe(slug);
+            return;
+        }
+        default:
+            throw new FloomError(`Unknown library command: ${subcommand}`, "Use: list, create, add, remove, subscribe, unsubscribe.");
+    }
+}
 function parseWatchFlags(argv) {
     const out = { intervalSeconds: 60 };
     for (let i = 0; i < argv.length; i++) {
@@ -310,6 +509,19 @@ async function main() {
                     await info({ slug: flags.slug ?? "", json: flags.json });
                 }
                 return;
+            case "search": {
+                const flags = parseSearchFlags(rest);
+                if (!flags.query) {
+                    throw new FloomError("Missing search query.", "Try: `floom search \"support tone\"`.");
+                }
+                await search({
+                    query: flags.query,
+                    ...(flags.library ? { library: flags.library } : {}),
+                    ...(flags.type ? { type: flags.type } : {}),
+                    json: flags.json,
+                });
+                return;
+            }
             case "add":
             case "install": {
                 const slug = rest.find((a) => !a.startsWith("--"));
@@ -322,6 +534,12 @@ async function main() {
             case "sync":
                 await sync();
                 return;
+            case "setup":
+            case "connect": {
+                const flags = parseSetupFlags(rest);
+                await setupAgent(flags);
+                return;
+            }
             case "watch": {
                 const flags = parseWatchFlags(rest);
                 await watch(flags.intervalSeconds);
@@ -335,11 +553,23 @@ async function main() {
             }
             case "library":
             case "lib":
-                notAvailable("`floom library`");
-            case "move":
-                notAvailable("`floom move`");
+                await runLibrary(rest);
+                return;
+            case "move": {
+                const flags = parseFolderTagFlags(rest);
+                const slug = flags.rest[0];
+                if (!slug) {
+                    throw new FloomError("Missing skill slug.", "Try `floom move support-tone --folder support/tone`.");
+                }
+                if (flags.folder === undefined) {
+                    throw new FloomError("Missing --folder.", "Use --folder <path> or --root. Add --tag or --tags when useful.");
+                }
+                await moveSkill({ slug, folder: flags.folder, tags: flags.tags });
+                return;
+            }
             case "mcp":
-                notAvailable("`floom mcp setup`");
+                printMcpSetup();
+                return;
             case "doctor":
                 await doctor();
                 return;

package/dist/doctor.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { stat, readFile, access, readdir, constants } from "node:fs/promises";
 import { getApiUrl, readConfig, CONFIG_PATH } from "./config.js";
 import { c, symbols } from "./ui.js";
-const CLI_VERSION = "1.0.0";
+const CLI_VERSION = "1.0.2";
 function statusBadge(s) {
     if (s === "ok")
         return c.green(symbols.ok);

package/dist/info.js

@@ -1,6 +1,7 @@
 import ora from "ora";
 import { getApiUrl, readConfig } from "./config.js";
 import { getJson } from "./lib/api.js";
+import { extractRequires, formatToolList, formatType } from "./lib/skill-labels.js";
 import { c, symbols } from "./ui.js";
 import { FloomError } from "./errors.js";
 function slugFromInput(input) {
@@ -29,9 +30,12 @@ export async function info(opts) {
         spinner?.stop();
     }
     if (opts.json) {
-        // Strip body_md from JSON output to keep it summary-shaped.
+        // Strip body_md from JSON output to keep it summary-shaped, but expose
+        // the parsed `requires` list so scripted consumers don't need to parse
+        // YAML themselves.
         const { body_md: _body, ...summary } = detail;
-        process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+        const requires = extractRequires(detail.body_md);
+        process.stdout.write(`${JSON.stringify({ ...summary, requires }, null, 2)}\n`);
         return;
     }
     const title = detail.title ?? c.dim("(untitled)");
@@ -41,7 +45,11 @@ export async function info(opts) {
         process.stdout.write(`   ${c.dim("About:      ")}${detail.description}\n`);
     }
     process.stdout.write(`   ${c.dim("Visibility: ")}${detail.visibility}\n`);
-    process.stdout.write(`   ${c.dim("Type:       ")}${detail.asset_type ?? "skill"}\n`);
+    process.stdout.write(`   ${c.dim("Type:       ")}${formatType(detail.asset_type)}\n`);
+    const requires = extractRequires(detail.body_md);
+    if (requires.length > 0) {
+        process.stdout.write(`   ${c.dim("Needs:      ")}${formatToolList(requires)}\n`);
+    }
     if (detail.version) {
         process.stdout.write(`   ${c.dim("Version:    ")}${detail.version}\n`);
     }

package/dist/lib/skill-labels.js

@@ -0,0 +1,140 @@
+/**
+ * CLI-side mirror of the web's skill-labels: type label + tool label + a tiny
+ * frontmatter parser for `requires:`. No React, no `gray-matter` — keep the
+ * CLI dep tree thin.
+ *
+ * The frontmatter parser intentionally only supports two `requires` shapes:
+ *   requires: [gmail, linear]
+ *   requires:
+ *     - gmail
+ *     - linear
+ *
+ * That covers >99% of real skills. If a skill uses a more exotic YAML shape
+ * we silently get an empty list — not a crash.
+ */
+const SKILL_TYPE_LABELS = {
+    knowledge: "Knowledge",
+    instruction: "Instruction",
+    workflow: "Workflow",
+    skill: "Skill",
+};
+const TOOL_LABELS = {
+    gmail: "Gmail",
+    "google-mail": "Gmail",
+    calendar: "Google Calendar",
+    "google-calendar": "Google Calendar",
+    drive: "Google Drive",
+    "google-drive": "Google Drive",
+    docs: "Google Docs",
+    "google-docs": "Google Docs",
+    sheets: "Google Sheets",
+    "google-sheets": "Google Sheets",
+    github: "GitHub",
+    gitlab: "GitLab",
+    linear: "Linear",
+    notion: "Notion",
+    slack: "Slack",
+    intercom: "Intercom",
+    zendesk: "Zendesk",
+    hubspot: "HubSpot",
+    salesforce: "Salesforce",
+    stripe: "Stripe",
+    airtable: "Airtable",
+    jira: "Jira",
+    asana: "Asana",
+    trello: "Trello",
+    zapier: "Zapier",
+    composio: "Composio",
+    whatsapp: "WhatsApp",
+    telegram: "Telegram",
+    discord: "Discord",
+    twitter: "Twitter",
+    x: "X",
+    linkedin: "LinkedIn",
+    openai: "OpenAI",
+    anthropic: "Anthropic",
+    gemini: "Gemini",
+    claude: "Claude",
+    perplexity: "Perplexity",
+    supabase: "Supabase",
+    vercel: "Vercel",
+    resend: "Resend",
+    twilio: "Twilio",
+    webhook: "Webhook",
+    http: "HTTP",
+};
+export function formatType(value) {
+    if (!value)
+        return "Skill";
+    const normalized = value.toLowerCase();
+    return SKILL_TYPE_LABELS[normalized] ?? "Skill";
+}
+export function formatTool(slug) {
+    const normalized = slug.trim().toLowerCase();
+    if (!normalized)
+        return slug;
+    if (TOOL_LABELS[normalized])
+        return TOOL_LABELS[normalized];
+    return normalized
+        .split(/[-_\s]+/)
+        .filter(Boolean)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(" ");
+}
+export function formatToolList(tools) {
+    return tools.map(formatTool).join(", ");
+}
+/**
+ * Pull `requires:` out of YAML frontmatter. Returns a deduped lowercase list
+ * or [] if absent / malformed.
+ */
+export function extractRequires(body) {
+    if (!body)
+        return [];
+    const trimmed = body.replace(/^/, "");
+    if (!trimmed.startsWith("---"))
+        return [];
+    const end = trimmed.indexOf("\n---", 3);
+    if (end === -1)
+        return [];
+    const headerBlock = trimmed.slice(3, end);
+    const lines = headerBlock.split(/\r?\n/);
+    const seen = new Set();
+    const out = [];
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i] ?? "";
+        const line = raw.trim();
+        const inlineMatch = /^requires\s*:\s*\[(.*?)\]\s*$/i.exec(line);
+        if (inlineMatch) {
+            const inner = inlineMatch[1] ?? "";
+            for (const part of inner.split(",")) {
+                const value = part.trim().replace(/^['"]|['"]$/g, "").toLowerCase();
+                if (value && !seen.has(value)) {
+                    seen.add(value);
+                    out.push(value);
+                }
+            }
+            return out;
+        }
+        if (/^requires\s*:\s*$/i.test(line)) {
+            // Block form. Scan subsequent indented `- foo` lines until indent breaks.
+            for (let j = i + 1; j < lines.length; j++) {
+                const next = lines[j] ?? "";
+                const itemMatch = /^\s+-\s+(.+?)\s*$/.exec(next);
+                if (!itemMatch) {
+                    // First non-list line ends the block.
+                    if (next.trim() === "")
+                        continue;
+                    break;
+                }
+                const value = (itemMatch[1] ?? "").replace(/^['"]|['"]$/g, "").trim().toLowerCase();
+                if (value && !seen.has(value)) {
+                    seen.add(value);
+                    out.push(value);
+                }
+            }
+            return out;
+        }
+    }
+    return out;
+}

package/dist/library.js

@@ -44,7 +44,32 @@ export async function libraryCreate(opts) {
         ...(opts.visibility ? { visibility: opts.visibility } : {}),
     });
     process.stdout.write(`\n${symbols.ok}  Library created: ${c.cyan(result.slug)}\n`);
-    process.stdout.write(`   ${c.dim("View:")} ${apiUrl}/library/${result.slug}\n\n`);
+    process.stdout.write(`   ${c.dim("API:")}  ${apiUrl}/api/v1/libraries/${result.slug}\n`);
+    process.stdout.write(`   ${c.dim("Sync:")} floom library subscribe ${result.slug}\n\n`);
+}
+export async function libraryAddSkill(opts) {
+    const cfg = await readConfig();
+    if (!cfg)
+        throw new FloomError("Not signed in.", "Run `floom login` first.");
+    const apiUrl = cfg.apiUrl ?? getApiUrl();
+    await postJson(`${apiUrl}/api/v1/libraries/${encodeURIComponent(opts.librarySlug)}/skills`, "add skill to library", cfg.accessToken, {
+        skill_slug: opts.skillSlug,
+        ...(opts.folder !== undefined ? { folder: opts.folder } : {}),
+        ...(opts.tags ? { tags: opts.tags } : {}),
+    });
+    const folderText = opts.folder ?? c.dim("(root)");
+    const tagsText = opts.tags?.length ? opts.tags.join(", ") : c.dim("(none)");
+    process.stdout.write(`\n${symbols.ok}  Added ${c.cyan(opts.skillSlug)} to ${c.cyan(opts.librarySlug)}\n`);
+    process.stdout.write(`   ${c.dim("folder:")} ${folderText}\n`);
+    process.stdout.write(`   ${c.dim("tags:")}   ${tagsText}\n\n`);
+}
+export async function libraryRemoveSkill(librarySlug, skillSlug) {
+    const cfg = await readConfig();
+    if (!cfg)
+        throw new FloomError("Not signed in.", "Run `floom login` first.");
+    const apiUrl = cfg.apiUrl ?? getApiUrl();
+    await deleteRequest(`${apiUrl}/api/v1/libraries/${encodeURIComponent(librarySlug)}/skills/${encodeURIComponent(skillSlug)}`, "remove skill from library", cfg.accessToken);
+    process.stdout.write(`\n${symbols.ok}  Removed ${c.cyan(skillSlug)} from ${c.cyan(librarySlug)}\n\n`);
 }
 export async function librarySubscribe(slug) {
     const cfg = await readConfig();

package/dist/list.js

@@ -1,15 +1,18 @@
 import ora from "ora";
 import { getApiUrl, readConfig } from "./config.js";
 import { getJson } from "./lib/api.js";
+import { extractRequires, formatToolList, formatType } from "./lib/skill-labels.js";
 import { c, symbols } from "./ui.js";
 import { FloomError } from "./errors.js";
 function formatRow(s) {
     const title = s.title ?? c.dim("(untitled)");
     const visibility = c.dim(`[${s.visibility}]`);
-    const type = c.dim(`[${s.asset_type ?? "skill"}]`);
+    const type = c.dim(`[${formatType(s.asset_type)}]`);
     const version = s.version ? c.dim(`v${s.version}`) : "";
     const updated = c.dim(formatRelative(s.updated_at));
-    return `   ${c.cyan(s.slug.padEnd(14))}  ${title}  ${type}  ${visibility}  ${version}  ${updated}`;
+    const requires = extractRequires(s.body_md);
+    const needs = requires.length > 0 ? c.dim(`needs ${formatToolList(requires)}`) : "";
+    return `   ${c.cyan(s.slug.padEnd(14))}  ${title}  ${type}  ${visibility}  ${version}  ${updated}${needs ? `  ${needs}` : ""}`;
 }
 function formatRelative(iso) {
     const diff = Date.now() - new Date(iso).getTime();
@@ -38,7 +41,7 @@ export async function list(opts) {
     const spinner = opts.json ? null : ora({ text: c.dim("Loading skills..."), color: "yellow" }).start();
     let published = [];
     try {
-        const mine = await getJson(`${apiUrl}/api/me/skills`, "load your skills", cfg.accessToken);
+        const mine = await getJson(`${apiUrl}/api/v1/me/skills`, "load your skills", cfg.accessToken);
         published = mine.skills ?? [];
     }
     finally {

package/dist/search.js

@@ -0,0 +1,54 @@
+import ora from "ora";
+import { getApiUrl, readConfig } from "./config.js";
+import { getJson } from "./lib/api.js";
+import { c, symbols } from "./ui.js";
+function formatSkillRow(skill) {
+    const title = skill.title ?? c.dim("(untitled)");
+    const type = c.dim(`[${skill.asset_type}]`);
+    const libs = skill.libraries.length
+        ? c.dim(` ${skill.libraries.map((lib) => `@${lib.slug}`).join(", ")}`)
+        : "";
+    return `   ${c.cyan(skill.slug.padEnd(22))}  ${title}  ${type}${libs}`;
+}
+function formatLibraryRow(library) {
+    const count = `${library.skill_count} ${library.skill_count === 1 ? "skill" : "skills"}`;
+    return `   ${c.cyan(`@${library.slug}`.padEnd(22))}  ${library.name}  ${c.dim(count)}`;
+}
+export async function search(opts) {
+    const cfg = await readConfig();
+    const apiUrl = cfg?.apiUrl ?? getApiUrl();
+    const params = new URLSearchParams({ q: opts.query });
+    if (opts.library)
+        params.set("library", opts.library);
+    if (opts.type)
+        params.set("type", opts.type);
+    const spinner = opts.json ? null : ora({ text: c.dim("Searching Floom..."), color: "yellow" }).start();
+    let result;
+    try {
+        result = await getJson(`${apiUrl}/api/v1/search?${params.toString()}`, "search skills");
+    }
+    finally {
+        spinner?.stop();
+    }
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return;
+    }
+    process.stdout.write(`\n${symbols.dot}  ${c.bold("Search results")} ${c.dim(`for "${result.query}"`)}\n\n`);
+    if (result.skills.length === 0 && result.libraries.length === 0) {
+        process.stdout.write(`   ${c.dim("No matching public skills or libraries.")}\n\n`);
+        return;
+    }
+    if (result.skills.length > 0) {
+        process.stdout.write(` ${c.dim("Skills")}\n`);
+        for (const skill of result.skills)
+            process.stdout.write(`${formatSkillRow(skill)}\n`);
+        process.stdout.write("\n");
+    }
+    if (result.libraries.length > 0) {
+        process.stdout.write(` ${c.dim("Libraries")}\n`);
+        for (const library of result.libraries)
+            process.stdout.write(`${formatLibraryRow(library)}\n`);
+        process.stdout.write("\n");
+    }
+}

package/dist/setup.js

@@ -0,0 +1,158 @@
+import { access, lstat, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { FloomError } from "./errors.js";
+import { c, symbols } from "./ui.js";
+const START_MARKER = "<!-- FLOOM SETUP START -->";
+const END_MARKER = "<!-- FLOOM SETUP END -->";
+const TARGETS = {
+    claude: { label: "Claude Code", filename: "CLAUDE.md" },
+    codex: { label: "Codex", filename: "AGENTS.md" },
+};
+export const FLOOM_AGENT_INSTRUCTIONS = `${START_MARKER}
+## Floom
+
+- Before reinventing agent workflows, use Floom to search, list, add, and sync skills.
+- Search or inspect skills with \`floom search <query>\`, \`floom info <slug-or-url>\`, and \`floom list\`.
+- Add reusable workflows with \`floom add <slug-or-url>\`.
+- Keep local skills current with \`floom sync\`.
+- For MCP tools, run \`floom mcp\` for setup guidance and add \`@floomhq/floom-mcp-sync\` only after reviewing your local agent config.
+${END_MARKER}`;
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readIfExists(path) {
+    if (!(await fileExists(path)))
+        return null;
+    const stat = await lstat(path);
+    if (stat.isSymbolicLink()) {
+        throw new FloomError("Refusing to update an instruction file that is a symbolic link.", `Inspect ${path}, then pass a regular file path.`);
+    }
+    if (!stat.isFile()) {
+        throw new FloomError("Instruction target is not a file.", path);
+    }
+    return readFile(path, "utf8");
+}
+function parseTargetFromFile(file) {
+    const upper = file.toUpperCase();
+    if (upper.endsWith("CLAUDE.MD"))
+        return "claude";
+    if (upper.endsWith("AGENTS.MD"))
+        return "codex";
+    return undefined;
+}
+async function findUp(filename) {
+    let dir = process.cwd();
+    const home = resolve(homedir());
+    while (true) {
+        const candidate = join(dir, filename);
+        if (await fileExists(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (dir === parent || dir === home)
+            return null;
+        dir = parent;
+    }
+}
+async function detectTarget(opts) {
+    const agent = opts.target ?? (opts.file ? parseTargetFromFile(opts.file) : undefined);
+    if (opts.file) {
+        const resolvedAgent = agent ?? "codex";
+        return {
+            agent: resolvedAgent,
+            label: TARGETS[resolvedAgent].label,
+            path: resolve(process.cwd(), opts.file),
+        };
+    }
+    if (agent) {
+        const existing = await findUp(TARGETS[agent].filename);
+        return {
+            agent,
+            label: TARGETS[agent].label,
+            path: existing ?? resolve(process.cwd(), TARGETS[agent].filename),
+        };
+    }
+    const claude = await findUp(TARGETS.claude.filename);
+    const codex = await findUp(TARGETS.codex.filename);
+    if (claude && codex) {
+        throw new FloomError("Found both Claude Code and Codex instruction files.", "Pass `--target claude` or `--target codex`.");
+    }
+    if (claude)
+        return { agent: "claude", label: TARGETS.claude.label, path: claude };
+    if (codex)
+        return { agent: "codex", label: TARGETS.codex.label, path: codex };
+    throw new FloomError("No agent instruction file found.", "Run `floom setup --target claude --yes` or `floom setup --target codex --yes` from the repo root.");
+}
+function renderPreview(target, existing) {
+    const action = existing === null ? "create" : "append";
+    return [
+        "",
+        `${symbols.bullet}  Floom setup preview for ${c.bold(target.label)}`,
+        `   ${c.dim("Target:")} ${target.path}`,
+        `   ${c.dim("Action:")} ${action}`,
+        "",
+        FLOOM_AGENT_INSTRUCTIONS,
+        "",
+        `${c.dim("MCP setup guidance:")} run ${c.cyan("floom mcp")} to print local agent commands.`,
+        "",
+    ].join("\n");
+}
+async function confirmWrite(target, existing) {
+    if (!process.stdin.isTTY) {
+        throw new FloomError("Refusing to update agent instructions without confirmation in non-interactive mode.", "Pass `--yes` to write, or `--dry-run` to preview.");
+    }
+    const action = existing === null ? "Create" : "Append to";
+    const rl = createInterface({ input, output });
+    try {
+        const answer = (await rl.question(`   ${action} ${target.path} for ${target.label}? ${c.dim("(y/N)")} `)).trim().toLowerCase();
+        return answer === "y" || answer === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function setupAgent(opts) {
+    const target = await detectTarget(opts);
+    const existing = await readIfExists(target.path);
+    if (existing?.includes(START_MARKER) && existing.includes(END_MARKER)) {
+        process.stdout.write(`\n${symbols.ok}  Floom instructions already present in ${c.bold(target.path)}\n\n`);
+        return;
+    }
+    if (opts.dryRun) {
+        process.stdout.write(renderPreview(target, existing));
+        return;
+    }
+    if (!opts.yes) {
+        process.stdout.write(renderPreview(target, existing));
+        const ok = await confirmWrite(target, existing);
+        if (!ok) {
+            process.stdout.write(`\n${c.dim("Cancelled. Nothing was written.")}\n\n`);
+            return;
+        }
+    }
+    await mkdir(dirname(target.path), { recursive: true });
+    const next = existing === null
+        ? `${FLOOM_AGENT_INSTRUCTIONS}\n`
+        : `${existing.replace(/\s*$/, "")}\n\n${FLOOM_AGENT_INSTRUCTIONS}\n`;
+    if (existing === null) {
+        await writeFile(target.path, next, { encoding: "utf8", flag: "wx" }).catch((err) => {
+            if (err instanceof Error && "code" in err && err.code === "EEXIST") {
+                throw new FloomError("Instruction file appeared while setup was running.", "Re-run `floom setup` so Floom can inspect the current file before writing.");
+            }
+            throw err;
+        });
+    }
+    else {
+        await writeFile(target.path, next, "utf8");
+    }
+    process.stdout.write(`\n${symbols.ok}  Added Floom instructions to ${c.bold(target.path)}\n`);
+    process.stdout.write(`   ${c.dim("MCP setup guidance:")} ${c.cyan("floom mcp")}\n\n`);
+}

package/dist/sync.js

@@ -211,7 +211,7 @@ export async function sync(opts = {}) {
     const spinner = opts.spinner === false ? null : ora({ text: c.dim("Syncing skills..."), color: "yellow" }).start();
     let payload;
     try {
-        payload = await getJson(`${apiUrl}/api/me/skills`, "load your skills", cfg.accessToken);
+        payload = await getJson(`${apiUrl}/api/v1/me/skills`, "load your skills", cfg.accessToken);
     }
     catch (err) {
         spinner?.stop();
@@ -223,7 +223,7 @@ export async function sync(opts = {}) {
     }
     for (const skill of payload.skills)
         validateSyncSkillShape(skill);
-    // Version 1 preview syncs owned published skills only.
+    // Version 1 preview syncs published, saved, and subscribed library skills.
     const all = payload.skills;
     const seen = new Set();
     let unchanged = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floomhq/floom",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Publish AI skills from your terminal. Share with a link.",
   "license": "MIT",
   "type": "module",