@floomhq/floom 1.0.6 → 1.0.8

package/README.md

@@ -3,48 +3,52 @@
 Publish AI skills from your terminal. Share them with a link. Add other people's skills with one command.
 
 ```bash
-npm install -g @floomhq/floom
-floom init my-skill.md
-floom login
-floom publish my-skill.md
-floom share my-skill --add teammate@example.com
-floom search review
-floom add awesome-skill
-floom setup --target claude --dry-run
-floom list
-floom library list
+npx -y @floomhq/floom init my-skill.md
+npx -y @floomhq/floom init brand-voice.md --template brand-voice
+npx -y @floomhq/floom login
+npx -y @floomhq/floom publish my-skill.md --share teammate@example.com
+npx -y @floomhq/floom share my-skill --add teammate@example.com
+npx -y @floomhq/floom search review
+npx -y @floomhq/floom add awesome-skill --setup
+npx -y @floomhq/floom agent-prompt
+npx -y @floomhq/floom setup --target claude --dry-run
+npx -y @floomhq/floom list
+npx -y @floomhq/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.
 
+The package is designed for `npx -y @floomhq/floom ...`. Global installs expose `floom-skills` to avoid colliding with any older local Floom runtime CLI.
+
 ## Commands
 
-- `floom login` — sign in with Google. New accounts are created on first login. Token stored at `~/.floom/config.json`.
-- `floom init [file.md]` — create a starter skill file.
-- `floom publish <file.md>` — upload a Markdown file. Optional `--public` / `--private` / `--unlisted`, `--type knowledge|instruction|workflow|skill`, `--installs-as <target>`, and `--version <label>`.
-- `floom share <slug>` — email-share one of your skills. Optional `--add <email>`, `--remove <email>`, and `--list`.
-- `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 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.
+- `npx -y @floomhq/floom login` — sign in with Google. New accounts are created on first login. Token stored at `~/.floom/config.json`.
+- `npx -y @floomhq/floom init [file.md]` — create a starter skill file. Optional `--template generic|brand-voice|pr-review|sales|support|onboarding`.
+- `npx -y @floomhq/floom publish <file.md>` — scan and upload a Markdown file. Optional `--public` / `--private` / `--unlisted`, `--type knowledge|instruction|workflow|skill`, `--installs-as <target>`, `--skill-version <label>`, and `--share <email>`. `--share` sends the normal link by email; no account is needed to add unlisted or public links.
+- `npx -y @floomhq/floom share <slug>` — email-share one of your skills. Optional `--add <email>`, `--remove <email>`, and `--list`.
+- `npx -y @floomhq/floom list` — show your published skills. Optional `--json`.
+- `npx -y @floomhq/floom add <url-or-slug>` — fetch a skill into `~/.claude/skills/<slug>.md`. Optional `--setup` connects Claude Code and `--force` replaces an existing local copy.
+- `npx -y @floomhq/floom info <url-or-slug>` — show skill metadata. Optional `--json`.
+- `npx -y @floomhq/floom search <query>` — search public skills and starter libraries. Optional `--library <slug>`, `--type knowledge|instruction|workflow|skill`, and `--json`.
+- `npx -y @floomhq/floom agent-prompt` — print the sentence to paste into Claude Code or Codex.
+- `npx -y @floomhq/floom setup` — add Floom usage guidance to `CLAUDE.md` or `AGENTS.md`. Optional `--target claude|codex`, `--dry-run`, `--yes`.
+- `npx -y @floomhq/floom connect` — alias for setup.
+- `npx -y @floomhq/floom mcp` — print MCP setup commands for supported agent CLIs.
+- `npx -y @floomhq/floom sync` — preview: pull your published, saved, and subscribed library skills into `~/.claude/skills/`.
+- `npx -y @floomhq/floom watch` — preview: run sync repeatedly. Optional `--interval <seconds>`; minimum `10`.
+- `npx -y @floomhq/floom library list` — list public starter libraries. Optional `--json`.
+- `npx -y @floomhq/floom library create <slug> --name <name>` — create a personal or starter library. Optional `--public` / `--private` / `--unlisted`.
+- `npx -y @floomhq/floom library add <library> <skill> [--folder <path>] [--tags a,b]` — add a skill to a library.
+- `npx -y @floomhq/floom library subscribe <slug>` — subscribe to a public or unlisted library so sync can pull it locally.
+- `npx -y @floomhq/floom move <slug> --folder <path>` — set your local folder override for a saved or library skill.
+- `npx -y @floomhq/floom delete <url-or-slug>` — delete one of your published skills. Optional `--yes`.
+- `npx -y @floomhq/floom doctor` — diagnose your Floom setup.
 - `floom whoami` — show the signed-in account.
 - `floom logout` — delete local credentials.
 
 ## Skill format
 
-Optional YAML-ish frontmatter (`title`, `description`, `version`), then freeform Markdown.
+Optional YAML frontmatter (`title`, `description`, `version`, `type`, `installs_as`), then freeform Markdown.
 
 ```markdown
 ---
@@ -64,5 +68,5 @@ Override the API host with `FLOOM_API_URL` (defaults to `https://floom.dev`).
 `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
-and run `floom sync` again.
+conflicts. Symlinks are never followed. To replace a local skill manually, run
+`npx -y @floomhq/floom add <url-or-slug> --force`.

package/dist/cli.js

@@ -4,7 +4,7 @@ import { login } from "./login.js";
 import { publish } from "./publish.js";
 import { whoami } from "./whoami.js";
 import { init } from "./init.js";
-import { deleteConfig } from "./config.js";
+import { deleteConfig, readConfig } from "./config.js";
 import { list } from "./list.js";
 import { install } from "./install.js";
 import { info } from "./info.js";
@@ -63,22 +63,25 @@ function usage() {
 }
 function commandUsage() {
     const out = `
- ${c.bold("Usage:")} ${c.cyan("floom")} ${c.dim("<command> [flags]")}
+ ${c.bold("Usage:")} ${c.cyan("npx -y @floomhq/floom")} ${c.dim("<command> [flags]")}
+ ${c.dim("Global install binary:")} ${c.cyan("floom-skills")} ${c.dim("<command> [flags]")}
 
  ${c.bold("Commands")}
    ${c.dim("Skills")}
      ${c.cyan("add")} ${c.dim("<url>")}          Install a skill into the local agent skills folder
                        ${c.dim("Alias: install")}
-                       ${c.dim("Flags: --target claude|codex (default: claude), --setup")}
+                       ${c.dim("Flags: --target claude|codex (default: claude), --setup, --force")}
      ${c.cyan("search")} ${c.dim("<query>")}     Find public skills and libraries
      ${c.cyan("info")} ${c.dim("<url>")}         Show skill metadata
 
    ${c.dim("Publishing")}
      ${c.cyan("init")} ${c.dim("[path]")}        Create a skill scaffold
+                       ${c.dim("Flags: --template generic|brand-voice|pr-review|sales|support|onboarding")}
      ${c.cyan("scan")} ${c.dim("<path>")}        Check for secrets, injection, exfiltration
      ${c.cyan("publish")} ${c.dim("<path>")}     Scan, publish, and print a share link
                        ${c.dim("Flags: --public, --private, --type knowledge|instruction|workflow|skill")}
-                       ${c.dim("       --skill-version <label>")}
+                       ${c.dim("       --skill-version <label>, --share <email>")}
+                       ${c.dim("       --share emails the normal link; no account is needed to add it")}
      ${c.cyan("share")} ${c.dim("<slug>")}       Email-share one of your skills
                        ${c.dim("Flags: --add <email>, --remove <email>, --list")}
 
@@ -94,6 +97,8 @@ function commandUsage() {
      ${c.cyan("setup")}              Configure Claude Code or Codex instructions
                        ${c.dim("Alias: connect")}
                        ${c.dim("Flags: --target claude|codex, --yes, --dry-run")}
+     ${c.cyan("agent-prompt")}       Print the sentence to paste into your agent
+                       ${c.dim("Alias: paste")}
      ${c.cyan("doctor")}             Troubleshoot auth, API, and local folders
 
    ${c.dim("Advanced")}
@@ -105,20 +110,22 @@ function commandUsage() {
      ${c.cyan("watch")}              Preview polling sync loop
 
  ${c.bold("Examples")}
-   ${c.cyan("floom add")} ${c.dim("https://floom.dev/s/ffas93ud")}
-   ${c.cyan("floom publish")} ${c.dim("support-tone.md --type instruction --public")}
-   ${c.cyan("floom setup")} ${c.dim("--target claude --yes")}
+   ${c.cyan("npx -y @floomhq/floom add")} ${c.dim("https://floom.dev/s/ffas93ud --setup")}
+   ${c.cyan("npx -y @floomhq/floom publish")} ${c.dim("support-tone.md --type instruction --public")}
+   ${c.cyan("npx -y @floomhq/floom publish")} ${c.dim("support-tone.md --share teammate@example.com")}
+   ${c.cyan("npx -y @floomhq/floom setup")} ${c.dim("--target claude --yes")}
 
  ${c.bold("Help")}
-   ${c.cyan("floom commands")}       Show this reference
+   ${c.cyan("npx -y @floomhq/floom commands")}  Show this reference
    ${c.cyan("--help")}               Show this reference
    ${c.cyan("--version")}            Show CLI version
 
- ${c.dim("Run")} ${c.cyan("floom")} ${c.dim("with no command for the guided start screen.")}
+ ${c.dim("Run")} ${c.cyan("npx -y @floomhq/floom")} ${c.dim("with no command for the guided start screen.")}
 `;
     process.stdout.write(out);
 }
 const ASSET_TYPES = new Set(["knowledge", "instruction", "workflow", "skill"]);
+const INIT_TEMPLATES = new Set(["generic", "brand-voice", "pr-review", "sales", "support", "onboarding"]);
 const INSTALL_TARGETS = new Set([
     "claude_skill",
     "memory",
@@ -139,7 +146,7 @@ function readFlagValue(argv, index, flag) {
     return { value, nextIndex: index + 1 };
 }
 function parseFlags(argv) {
-    const out = { visibility: "unlisted", update: false, rest: [] };
+    const out = { visibility: "unlisted", update: false, shareEmails: [], explicitVisibility: false, rest: [] };
     let visibilityFlag = null;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i] ?? "";
@@ -150,12 +157,15 @@ function parseFlags(argv) {
             }
             visibilityFlag = nextVisibility;
             out.visibility = nextVisibility;
+            out.explicitVisibility = true;
         }
         else if (a === "--update") {
             throw new FloomError(V1_NOT_AVAILABLE, "`floom publish --update` is planned for a later Floom release.");
         }
         else if (a === "--share" || a.startsWith("--share=")) {
-            throw new FloomError(V1_NOT_AVAILABLE, "`floom publish --share` is planned for a later Floom release.");
+            const { value, nextIndex } = readFlagValue(argv, i, "--share");
+            out.shareEmails.push(...parseEmailList(value, "--share"));
+            i = nextIndex;
         }
         else if (a === "--type" || a.startsWith("--type=")) {
             const { value, nextIndex } = readFlagValue(argv, i, "--type");
@@ -173,23 +183,48 @@ function parseFlags(argv) {
             out.installsAs = value;
             i = nextIndex;
         }
-        else if (a === "--skill-version" || a.startsWith("--skill-version=") || a === "--version" || a.startsWith("--version=")) {
-            const flagName = a.startsWith("--skill-version") ? "--skill-version" : "--version";
-            const { value, nextIndex } = readFlagValue(argv, i, flagName);
+        else if (a === "--skill-version" || a.startsWith("--skill-version=")) {
+            const { value, nextIndex } = readFlagValue(argv, i, "--skill-version");
             if (!VERSION_RE.test(value)) {
-                throw new FloomError(`Invalid ${flagName}: ${value}`, "Use 1-64 characters: letters, numbers, dots, underscores, plus, or hyphen.");
+                throw new FloomError(`Invalid --skill-version: ${value}`, "Use 1-64 characters: letters, numbers, dots, underscores, plus, or hyphen.");
             }
             out.version = value;
             i = nextIndex;
         }
+        else if (a === "--version" || a.startsWith("--version=")) {
+            throw new FloomError("`--version` prints the Floom CLI version at the top level.", "For skill version labels, use `--skill-version <label>`.");
+        }
         else if (a.startsWith("--")) {
             throw new FloomError(`Unknown flag: ${a}`, "Try `floom publish skill.md --type instruction --public`.");
         }
         else
             out.rest.push(a);
     }
+    if (out.shareEmails.length > 0) {
+        out.shareEmails = dedupeEmails(out.shareEmails);
+        if (out.shareEmails.length > 200) {
+            throw new FloomError("Too many --share recipients.", "Use 200 email addresses or fewer.");
+        }
+        if (out.visibility === "private") {
+            throw new FloomError("`--private --share` would email a link recipients cannot open.", "Use `--unlisted --share` for invite emails, or `floom share <slug> --add <email>` for email-gated access after publishing.");
+        }
+    }
     return out;
 }
+function parseEmailList(value, source) {
+    const emails = value.split(",").map((email) => email.trim().toLowerCase()).filter(Boolean);
+    if (emails.length === 0)
+        throw new FloomError(`Missing value for ${source}.`, `Try \`${source} teammate@example.com\`.`);
+    for (const email of emails) {
+        if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+            throw new FloomError(`Invalid email for ${source}: ${email}`, "Use an address like teammate@example.com.");
+        }
+    }
+    return emails;
+}
+function dedupeEmails(emails) {
+    return [...new Set(emails)];
+}
 function parseShareFlags(argv) {
     const out = { list: false, add: [], remove: [] };
     for (let i = 0; i < argv.length; i++) {
@@ -229,16 +264,27 @@ function parseShareFlags(argv) {
 }
 function parseInitArgs(argv) {
     let file;
-    for (const a of argv) {
+    let template = "generic";
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] ?? "";
+        if (a === "--template" || a.startsWith("--template=")) {
+            const { value, nextIndex } = readFlagValue(argv, i, "--template");
+            if (!INIT_TEMPLATES.has(value)) {
+                throw new FloomError(`Invalid --template: ${value}`, "Use one of: generic, brand-voice, pr-review, sales, support, onboarding.");
+            }
+            template = value;
+            i = nextIndex;
+            continue;
+        }
         if (a.startsWith("--")) {
-            throw new FloomError(`Unknown flag: ${a}`, "Try `floom init skill.md`.");
+            throw new FloomError(`Unknown flag: ${a}`, "Try `floom init skill.md --template brand-voice`.");
         }
         if (file) {
             throw new FloomError(`Unexpected argument: ${a}`, "Try `floom init skill.md`.");
         }
         file = a;
     }
-    return file ? { file } : {};
+    return file ? { file, template } : { template };
 }
 function parseListFlags(argv) {
     const out = { json: false };
@@ -272,6 +318,7 @@ function parseAddArgs(argv) {
     let slug;
     let target;
     let setup = false;
+    let force = false;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i] ?? "";
         if (a === "--target" || a.startsWith("--target=")) {
@@ -285,6 +332,9 @@ function parseAddArgs(argv) {
         else if (a === "--setup") {
             setup = true;
         }
+        else if (a === "--force") {
+            force = true;
+        }
         else if (a.startsWith("--")) {
             throw new FloomError(`Unknown flag: ${a}`, "Try `floom add <url-or-slug> --setup`.");
         }
@@ -297,7 +347,7 @@ function parseAddArgs(argv) {
     if (!slug) {
         throw new FloomError("Missing skill slug.", "Try: `floom add <url-or-slug> --setup`");
     }
-    return target ? { slug, target, setup } : { slug, setup };
+    return target ? { slug, target, setup, force } : { slug, setup, force };
 }
 function parseSearchFlags(argv) {
     const out = { json: false };
@@ -559,6 +609,9 @@ function parseSingleFileArg(argv, usageHint) {
         throw new FloomError("Missing file argument.", usageHint);
     return file;
 }
+function agentPrompt() {
+    process.stdout.write("Use my installed Floom skills when they fit the task. Search ~/.claude/skills first.\n");
+}
 function sleep(ms, signal) {
     if (signal.aborted)
         return Promise.resolve();
@@ -571,6 +624,10 @@ function sleep(ms, signal) {
     });
 }
 async function watch(intervalSeconds) {
+    const cfg = await readConfig();
+    if (!cfg) {
+        throw new FloomError("Not signed in.", "Run `npx -y @floomhq/floom login` before watch, or use `npx -y @floomhq/floom add <link>` without an account.");
+    }
     const controller = new AbortController();
     let stopping = false;
     const stop = () => {
@@ -644,7 +701,7 @@ async function main() {
                 return;
             case "init": {
                 const flags = parseInitArgs(rest);
-                await init(flags.file);
+                await init(flags.file, flags.template);
                 return;
             }
             case "publish": {
@@ -663,6 +720,7 @@ async function main() {
                     ...(flags.assetType ? { assetType: flags.assetType } : {}),
                     ...(flags.installsAs ? { installsAs: flags.installsAs } : {}),
                     ...(flags.version ? { version: flags.version } : {}),
+                    ...(flags.shareEmails.length > 0 ? { sharedWithEmails: flags.shareEmails } : {}),
                 });
                 return;
             }
@@ -712,6 +770,7 @@ async function main() {
                 await install(flags.slug, {
                     ...(flags.target ? { target: flags.target } : {}),
                     setup: flags.setup,
+                    force: flags.force,
                 });
                 if (flags.setup) {
                     await setupAgent({ target: flags.target ?? "claude", dryRun: false, yes: true });
@@ -728,6 +787,11 @@ async function main() {
                 await setupAgent(flags);
                 return;
             }
+            case "agent-prompt":
+            case "paste":
+                rejectArgs(rest, "Try `floom agent-prompt`.");
+                agentPrompt();
+                return;
             case "watch": {
                 const flags = parseWatchFlags(rest);
                 await watch(flags.intervalSeconds);
@@ -771,7 +835,7 @@ async function main() {
         }
     }
     catch (e) {
-        printError(e);
+        printError(e, { json: rest.includes("--json") });
         process.exit(1);
     }
 }

package/dist/errors.js

@@ -20,6 +20,9 @@ export function friendlyHttp(status, action) {
         return new FloomError(`You don't have permission to ${action}.`);
     }
     if (status === 404) {
+        if (/fetch|inspect|add|install|show|get|search|list|info/i.test(action)) {
+            return new FloomError("Skill not found.", "Check the link or slug, then try again.");
+        }
         return new FloomError("Skill not found.", "Run `floom publish` without `--update` to create a new one.");
     }
     if (status === 413) {
@@ -37,7 +40,14 @@ export function friendlyNetwork(err) {
     }
     return new FloomError(msg);
 }
-export function printError(err) {
+export function printError(err, opts = {}) {
+    if (opts.json) {
+        const error = err instanceof FloomError
+            ? { error: err.message, hint: err.hint ?? null }
+            : { error: err instanceof Error ? err.message : String(err), hint: null };
+        process.stderr.write(`${JSON.stringify(error)}\n`);
+        return;
+    }
     if (err instanceof FloomError) {
         process.stderr.write(`\n${symbols.fail}  ${err.message}\n`);
         if (err.hint) {

package/dist/init.js

@@ -4,7 +4,8 @@ import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { c, symbols } from "./ui.js";
 import { FloomError } from "./errors.js";
-const TEMPLATE = `---
+const TEMPLATES = {
+    generic: `---
 title:
 description:
 version: 1.0
@@ -26,10 +27,156 @@ version: 1.0
 
 
 # Examples
-`;
-export async function init(filename) {
+`,
+    "brand-voice": `---
+title: Brand voice
+description: Help an agent write in our company voice.
+type: knowledge
+installs_as: memory
+version: 1.0
+---
+
+# Brand Voice
+
+## Use when
+- Writing customer-facing copy
+- Rewriting drafts to match our tone
+- Reviewing messaging before it ships
+
+## Voice rules
+- Sound clear, direct, and useful.
+- Prefer concrete nouns and short sentences.
+- Avoid hype, filler, and generic AI language.
+
+## Words we use
+- Replace this list with approved terms.
+
+## Words we avoid
+- Replace this list with banned or overused terms.
+
+## Examples
+- Before:
+- After:
+`,
+    "pr-review": `---
+title: PR review
+description: Review code changes with risk-first feedback.
+type: workflow
+installs_as: claude_skill
+version: 1.0
+---
+
+# PR Review
+
+## Use when
+- Reviewing a pull request or diff
+- Checking a change before merge
+
+## Review order
+1. Correctness and regressions
+2. Security and data safety
+3. Tests and missing edge cases
+4. Maintainability
+
+## Output
+- Lead with findings.
+- Include file paths and line references.
+- Keep style comments out unless they affect behavior.
+- If no issues are found, say that clearly and name any test gaps.
+`,
+    sales: `---
+title: Sales research
+description: Prepare concise account research and outreach context.
+type: workflow
+installs_as: memory
+version: 1.0
+---
+
+# Sales Research
+
+## Use when
+- Preparing for a prospect call
+- Writing a relevant outbound message
+- Summarizing account context for the team
+
+## Gather
+- Company
+- Buyer persona
+- Recent trigger
+- Likely pain
+- Existing tools or workflow
+
+## Output
+- 5 bullet account summary
+- 3 likely pain points
+- 2 tailored opener angles
+- 1 clear next action
+`,
+    support: `---
+title: Support tone
+description: Answer support tickets with a clear and calm company voice.
+type: instruction
+installs_as: memory
+version: 1.0
+---
+
+# Support Tone
+
+## Use when
+- Replying to customer support messages
+- Summarizing customer issues
+- Drafting escalation notes
+
+## Rules
+- Acknowledge the issue in plain language.
+- Give the next concrete step.
+- Do not over-apologize.
+- Do not invent product behavior.
+- Escalate when data, billing, or account access is involved.
+
+## Reply shape
+1. Short acknowledgement
+2. Direct answer or next step
+3. What happens next
+`,
+    onboarding: `---
+title: Team onboarding
+description: Help a new teammate understand how this team works.
+type: knowledge
+installs_as: memory
+version: 1.0
+---
+
+# Team Onboarding
+
+## Use when
+- A new teammate asks how work gets done
+- An agent needs company or team context
+- Creating first-week task plans
+
+## Team context
+- Mission:
+- Customers:
+- Current priorities:
+- Tools:
+
+## How we work
+- Decision rules:
+- Review process:
+- Communication norms:
+- Definition of done:
+
+## First-week checklist
+- Read:
+- Set up:
+- Ask:
+- Ship:
+`,
+};
+export async function init(filename, template = "generic") {
     const target = filename ?? "skill.md";
     const filePath = resolve(process.cwd(), target);
+    const body = TEMPLATES[template];
     const exists = await fileExists(filePath);
     if (exists) {
         if (!process.stdin.isTTY) {
@@ -44,7 +191,7 @@ export async function init(filename) {
         }
     }
     try {
-        await writeFile(filePath, TEMPLATE, "utf8");
+        await writeFile(filePath, body, "utf8");
     }
     catch (err) {
         const code = err.code;
@@ -57,10 +204,11 @@ export async function init(filename) {
         throw new FloomError(`Couldn't create ${target}: ${err.message}`);
     }
     process.stdout.write(`\n${symbols.ok}  Created ${c.bold(basename(filePath))}\n`);
+    process.stdout.write(`   ${c.dim(`Template: ${template}`)}\n`);
     process.stdout.write(`\n   ${c.bold("Next")}\n`);
     process.stdout.write(`   ${c.dim("1.")} Fill in the title, description, and instructions.\n`);
-    process.stdout.write(`   ${c.dim("2.")} Check it: ${c.cyan(`floom scan ${shellQuote(target)}`)}\n`);
-    process.stdout.write(`   ${c.dim("3.")} Publish:  ${c.cyan(`floom publish ${shellQuote(target)} --type instruction --public`)}\n\n`);
+    process.stdout.write(`   ${c.dim("2.")} Check it: ${c.cyan(`npx -y @floomhq/floom scan ${shellQuote(target)}`)}\n`);
+    process.stdout.write(`   ${c.dim("3.")} Publish:  ${c.cyan(`npx -y @floomhq/floom publish ${shellQuote(target)} --public`)}\n\n`);
 }
 function shellQuote(value) {
     if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value))

package/dist/install.js

@@ -77,6 +77,18 @@ async function writeInstallFile(root, target, body) {
         await parent.close();
     }
 }
+async function overwriteInstallFile(target, body) {
+    const handle = await open(target, constants.O_WRONLY | constants.O_TRUNC | constants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile())
+            throw new FloomError("Local path is blocked by an existing file or directory.");
+        await writeAll(handle, body);
+    }
+    finally {
+        await handle.close();
+    }
+}
 async function openSafeParentDirectory(root, target) {
     await ensureSafeParentDirectory(root, target);
     return open(dirname(target), constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
@@ -175,8 +187,20 @@ export async function install(slugInput, opts = {}) {
     if (existing === remoteHash) {
         action = "unchanged";
     }
+    else if (existing !== null && opts.force) {
+        try {
+            await overwriteInstallFile(target, detail.body_md);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === "ELOOP")
+                throw new FloomError("Local path is a symbolic link.", "Move or delete the local path, then run `floom add` again.");
+            throw err;
+        }
+        action = "updated";
+    }
     else if (existing !== null) {
-        throw new FloomError("Local skill already exists with different content.", "Move or delete the local file, then run `floom add` again.");
+        throw new FloomError("Local skill already exists with different content.", "Run `npx -y @floomhq/floom add <link> --force` to replace it, or move the local file first.");
     }
     else {
         try {
@@ -185,7 +209,7 @@ export async function install(slugInput, opts = {}) {
         catch (err) {
             const code = err.code;
             if (code === "EEXIST") {
-                throw new FloomError("Local skill already exists with different content.", "Move or delete the local file, then run `floom add` again.");
+                throw new FloomError("Local skill already exists with different content.", "Run `npx -y @floomhq/floom add <link> --force` to replace it, or move the local file first.");
             }
             if (code === "ELOOP") {
                 throw new FloomError("Local path is a symbolic link.", "Move or delete the local path, then run `floom add` again.");

package/dist/login.js

@@ -8,7 +8,6 @@ const DEFAULT_PORT = 7456;
 const TIMEOUT_MS = 5 * 60 * 1000;
 export async function login() {
     const apiUrl = getApiUrl();
-    const port = await pickPort();
     process.stdout.write(header());
     process.stdout.write(`${symbols.arrow}  Opening browser to sign in with Google...\n\n`);
     const spinner = ora({
@@ -17,7 +16,7 @@ export async function login() {
     }).start();
     let tokens;
     try {
-        tokens = await waitForCallback(port);
+        tokens = await waitForCallback();
     }
     catch (err) {
         spinner.stop();
@@ -57,16 +56,11 @@ export async function login() {
     process.stdout.write(`${symbols.ok}  Signed in as ${c.bold(me.email ?? me.id)}\n`);
     process.stdout.write(`   ${c.dim("Your token is saved at ~/.floom/config.json")}\n\n`);
 }
-/** Reserve a free port. Defaults to 7456 (must be in Supabase uri_allow_list). */
-async function pickPort() {
-    // Supabase uri_allow_list whitelists 7456 explicitly. If it's busy, we fail
-    // loudly rather than silently using a port that won't be allowed.
-    return DEFAULT_PORT;
-}
-function waitForCallback(port) {
+function waitForCallback() {
     return new Promise((resolve, reject) => {
         const apiUrl = getApiUrl();
         let settled = false;
+        let retriedEphemeralPort = false;
         const server = createServer((req, res) => {
             // CORS preflight from the browser bridge page.
             const origin = req.headers.origin ?? "*";
@@ -128,13 +122,27 @@ function waitForCallback(port) {
             server.close();
         }
         server.on("error", (err) => {
+            const code = err.code;
+            if (!settled && !retriedEphemeralPort && code === "EADDRINUSE") {
+                retriedEphemeralPort = true;
+                server.listen(0, "127.0.0.1");
+                return;
+            }
             if (settled)
                 return;
             settled = true;
             clearTimeout(timer);
-            reject(new FloomError(`Local auth server failed on port ${port}.`, `Is port ${port} already in use? (${err.message})`));
+            reject(new FloomError("Local auth server failed.", err.message));
         });
-        server.listen(port, "127.0.0.1", () => {
+        server.listen(DEFAULT_PORT, "127.0.0.1", () => {
+            const address = server.address();
+            if (!address || typeof address === "string") {
+                settled = true;
+                cleanup();
+                reject(new FloomError("Could not reserve a local sign-in port."));
+                return;
+            }
+            const port = address.port;
             const target = `${apiUrl}/auth/cli?port=${port}`;
             open(target).catch((e) => {
                 const msg = e instanceof Error ? e.message : String(e);

package/dist/publish.js

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import { basename, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
 import ora from "ora";
 import clipboard from "clipboardy";
 import { getWebUrl, readConfig, resolveApiUrl } from "./config.js";
@@ -34,21 +35,27 @@ function parseFrontmatter(input) {
     const headerBlock = trimmed.slice(3, end).trim();
     const rest = trimmed.slice(end + 4).replace(/^\r?\n/, "");
     const meta = {};
-    const lines = headerBlock.split(/\r?\n/);
-    for (let i = 0; i < lines.length; i++) {
-        const rawLine = lines[i] ?? "";
-        const line = rawLine.trim();
-        if (!line || line.startsWith("#"))
+    let parsed;
+    try {
+        parsed = headerBlock ? parseYaml(headerBlock) : {};
+    }
+    catch (err) {
+        return {
+            meta,
+            body: rest,
+            error: {
+                message: err instanceof Error ? err.message.replace(/\n.*/s, "") : "Invalid YAML.",
+                line: yamlErrorLine(err),
+            },
+        };
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return { meta, body: rest };
+    for (const [rawKey, rawValue] of Object.entries(parsed)) {
+        const key = rawKey.trim().toLowerCase();
+        const value = frontmatterScalar(rawValue);
+        if (value === undefined)
             continue;
-        const colon = line.indexOf(":");
-        if (colon === -1) {
-            return { meta, body: rest, error: { message: `Couldn't parse line: \`${rawLine}\``, line: i + 2 } };
-        }
-        const key = line.slice(0, colon).trim().toLowerCase();
-        let value = line.slice(colon + 1).trim();
-        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
-            value = value.slice(1, -1);
-        }
         if (key === "title"
             || key === "description"
             || key === "version"
@@ -67,6 +74,18 @@ function parseFrontmatter(input) {
     }
     return { meta, body: rest };
 }
+function yamlErrorLine(err) {
+    const linePos = err.linePos;
+    const line = linePos?.[0]?.line;
+    return typeof line === "number" && Number.isFinite(line) ? line + 1 : 2;
+}
+function frontmatterScalar(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return undefined;
+}
 function parseAssetType(value, source) {
     if (!value)
         return undefined;
@@ -173,10 +192,15 @@ export async function publish(opts) {
     spinner.stop();
     const versionTag = version ? c.dim(` (${formatVersionLabel(version)})`) : "";
     const titleLabel = data.title ? `"${data.title}"` : opts.file;
+    const invitedEmails = opts.sharedWithEmails ?? [];
     process.stdout.write(`\n${symbols.ok}  Published ${c.bold(titleLabel)}${versionTag}\n\n`);
+    process.stdout.write(`   ${c.bold("Send this to someone:")}\n`);
     process.stdout.write(`   ${c.cyan(humanUrl)}\n\n`);
-    if (data.visibility === "shared" && data.shared_with_emails?.length) {
-        process.stdout.write(`   ${c.dim(`Shared with ${data.shared_with_emails.join(", ")}`)}\n\n`);
+    process.stdout.write(`   ${c.bold("They run:")}\n`);
+    process.stdout.write(`   ${c.cyan(`npx -y @floomhq/floom add ${humanUrl} --setup`)}\n\n`);
+    if (invitedEmails.length) {
+        process.stdout.write(`   ${c.bold("Email invite:")}\n`);
+        process.stdout.write(`   ${c.dim(invitedEmails.join(", "))}\n\n`);
     }
     let copied = false;
     try {
@@ -187,14 +211,11 @@ export async function publish(opts) {
         copied = false;
     }
     if (copied) {
-        process.stdout.write(`   ${c.dim("Copied to clipboard. Share it anywhere.")}\n\n`);
+        process.stdout.write(`   ${c.dim("Copied link to clipboard.")}\n\n`);
     }
     else {
         process.stdout.write(`   ${c.dim("Share it anywhere.")}\n\n`);
     }
-    process.stdout.write(`   ${c.bold("Next")}\n`);
-    process.stdout.write(`   ${c.dim("1.")} Test locally: ${c.cyan(`npx -y @floomhq/floom add ${humanUrl} --target claude`)}\n`);
-    process.stdout.write(`   ${c.dim("2.")} Send the link.\n`);
-    process.stdout.write(`   ${c.dim("3.")} Receiver runs ${c.cyan(`npx -y @floomhq/floom add ${humanUrl} --target claude`)}\n`);
-    process.stdout.write(`   ${c.dim("4.")} Agent reads the installed Markdown from the local skills folder.\n\n`);
+    process.stdout.write(`   ${c.bold("Agent prompt:")}\n`);
+    process.stdout.write(`   ${c.cyan("npx -y @floomhq/floom agent-prompt")}\n\n`);
 }

package/dist/scan.js

@@ -17,6 +17,9 @@ export async function scanSkill(file) {
             throw new FloomError(`That's a directory, not a file: ${file}`);
         throw new FloomError(`Couldn't read ${file}: ${err.message}`);
     }
+    if (!raw.trim()) {
+        throw new FloomError(`File is empty: ${file}`, "Add skill instructions before scanning or publishing.");
+    }
     const findings = detectSkillSecurityFindings(raw);
     if (findings.length > 0) {
         throw new FloomError("Security scan failed.", `${formatSecurityFindings(findings)}\nRemove secrets, prompt-injection text, or data-exfiltration instructions before publishing.`);

package/dist/secrets.js

@@ -12,7 +12,8 @@ const SECRET_PATTERNS = [
     { label: "Private key", regex: /-----BEGIN (?:RSA |EC |OPENSSH |)PRIVATE KEY-----/g },
 ];
 const GENERIC_ASSIGNMENT_RE = /\b(?:api[_-]?key|secret|access[_-]?token|auth[_-]?token|bearer[_-]?token)\b\s*[:=]\s*["']?([A-Za-z0-9_./+=-]{24,})["']?/gi;
-const PLACEHOLDER_RE = /^(?:your|example|placeholder|replace|changeme|todo|xxx|test|demo|dummy|redacted)/i;
+const PROVIDER_LIKE_ASSIGNMENT_RE = /\b(?:api[_-]?key|secret|access[_-]?token|auth[_-]?token|bearer[_-]?token)\b\s*[:=]\s*["']?((?:sk|pk|rk)-[A-Za-z0-9_-]{8,}|sbp_[A-Za-z0-9]{12,}|xox[baprs]-[A-Za-z0-9-]{12,})["']?/gi;
+const PLACEHOLDER_RE = /(?:^|[_./+=-])(?:your|example|placeholder|replace|changeme|todo|xxx|test|demo|dummy|fake|redacted)(?:$|[_./+=-])/i;
 const PROMPT_INJECTION_PATTERNS = [
     { label: "Prompt injection instruction", regex: /\bignore (?:all )?(?:previous|prior|above|earlier) instructions\b/gi },
     { label: "Prompt injection instruction", regex: /\bdisregard (?:all )?(?:previous|prior|above|earlier) instructions\b/gi },
@@ -62,6 +63,13 @@ export function detectSecrets(input) {
             continue;
         pushFinding(findings, seen, "Possible secret assignment", lineNumberAt(input, match.index ?? 0), value);
     }
+    PROVIDER_LIKE_ASSIGNMENT_RE.lastIndex = 0;
+    for (const match of input.matchAll(PROVIDER_LIKE_ASSIGNMENT_RE)) {
+        const value = match[1] ?? "";
+        if (!value)
+            continue;
+        pushFinding(findings, seen, "Provider-like secret assignment", lineNumberAt(input, match.index ?? 0), value);
+    }
     return findings.sort((a, b) => a.line - b.line || a.label.localeCompare(b.label));
 }
 function detectPatternFindings(input, patterns, category) {

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@floomhq/floom",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Publish AI skills from your terminal. Share with a link.",
   "license": "MIT",
   "type": "module",
   "bin": {
-    "floom": "bin/floom.js"
+    "floom-skills": "bin/floom.js"
   },
   "files": [
     "bin",
@@ -30,7 +30,8 @@
     "open": "10.1.0",
     "ora": "8.1.1",
     "picocolors": "1.1.1",
-    "update-notifier": "7.3.1"
+    "update-notifier": "7.3.1",
+    "yaml": "2.8.4"
   },
   "devDependencies": {
     "@types/node": "22.10.5",