@floomhq/floom 1.0.7 → 1.0.8

package/README.md

@@ -4,11 +4,13 @@ Publish AI skills from your terminal. Share them with a link. Add other people's
 
 ```bash
 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
+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
@@ -21,31 +23,32 @@ The package is designed for `npx -y @floomhq/floom ...`. Global installs expose
 ## Commands
 
 - `npx -y @floomhq/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.
-- `npx -y @floomhq/floom publish <file.md>` — upload a Markdown file. Optional `--public` / `--private` / `--unlisted`, `--type knowledge|instruction|workflow|skill`, `--installs-as <target>`, and `--skill-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`.
+- `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.
-- `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`.
+- `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
 ---

package/dist/cli.js

@@ -76,10 +76,12 @@ function commandUsage() {
 
    ${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")}
 
@@ -95,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")}
@@ -108,6 +112,7 @@ function commandUsage() {
  ${c.bold("Examples")}
    ${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")}
@@ -120,6 +125,7 @@ function commandUsage() {
     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",
@@ -140,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] ?? "";
@@ -151,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");
@@ -191,8 +200,31 @@ function parseFlags(argv) {
         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++) {
@@ -232,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 };
@@ -566,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();
@@ -655,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": {
@@ -674,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;
             }
@@ -740,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);

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/publish.js

@@ -192,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 {
@@ -206,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} --setup`)}\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} --setup`)}\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/package.json

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