@floomhq/floom 1.0.14 → 1.0.17

package/README.md

@@ -1,55 +1,64 @@
 # @floomhq/floom
 
-Publish AI skills from your terminal. Share them with a link. Add other people's skills with one command.
+Sync AI skills across agents and machines. Publish from your terminal, then add or sync skills with one command.
 
 ```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 --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
+npm install -g @floomhq/floom
+floom init my-skill.md
+floom init my-skill
+floom login
+floom publish my-skill
+floom share my-skill --add teammate@example.com
+floom search review
+floom add awesome-skill --setup
+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.
 
-The package is designed for `npx -y @floomhq/floom ...`. Global installs expose `floom-skills` to avoid colliding with any older local Floom runtime CLI.
+The package is designed for `npx -y @floomhq/floom ...`. Global installs expose `floom`; `floom doctor` reports older local Floom runtime CLIs if they shadow the new command.
 
 ## Commands
 
 - `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 init [path]` — create a starter skill folder at `<path>/SKILL.md`. Passing an existing-style `file.md` path still creates that Markdown file.
+- `npx -y @floomhq/floom publish <path>` — upload a skill folder or Markdown file. Folder packages use `<slug>/SKILL.md` plus optional `references/`, `examples/`, `scripts/`, and `assets/`. Optional `--public` / `--private` / `--unlisted`, `--type knowledge|instruction|workflow|skill`, `--installs-as <target>`, and `--skill-version <label>`.
 - `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 the local agent skills folder. Optional `--target claude|codex`, `--setup`, `--force` / `--update`, and `--json`.
-- `npx -y @floomhq/floom update <url-or-slug>` — install the latest remote skill content, replacing the local copy.
+- `npx -y @floomhq/floom add <url-or-slug>` — fetch a skill into `~/.claude/skills/<slug>/SKILL.md` with supporting package files. Optional `--target claude|codex`, `--setup` to connect the agent, and `--force` to replace 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`, `--file <path>`.
+- `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 the local agent skills folder. Optional `--target claude|codex`.
-- `npx -y @floomhq/floom watch` — preview: run sync repeatedly. Optional `--target claude|codex`, `--interval <seconds>`; minimum `10`.
+- `npx -y @floomhq/floom sync` — preview: pull your published, saved, and subscribed library skills into Claude or Codex. Optional `--target claude|codex`.
+- `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. Optional `--target claude|codex`, `--json`.
+- `npx -y @floomhq/floom doctor` — diagnose your Floom setup.
 - `npx -y @floomhq/floom whoami` — show the signed-in account.
 - `npx -y @floomhq/floom logout` — delete local credentials.
 
 ## Skill format
 
-Optional YAML frontmatter (`title`, `description`, `version`, `type`, `installs_as`), then freeform Markdown.
+A skill package is a folder:
+
+```text
+my-skill/
+  SKILL.md
+  references/
+  examples/
+  scripts/
+  assets/
+```
+
+`SKILL.md` contains optional YAML frontmatter (`title`, `description`, `type`, `version`), then freeform Markdown. Supporting files are packaged only from `references/`, `examples/`, `scripts/`, and `assets/`.
 
 ```markdown
 ---
@@ -62,14 +71,11 @@ version: 0.1.0
 - ...
 ```
 
-Authoring guide: https://floom.dev/docs/build-skills
-
 ## Configuration
 
 Override the API host with `FLOOM_API_URL` (defaults to `https://floom.dev`).
 
-`npx -y @floomhq/floom sync` and `npx -y @floomhq/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 replace a local skill manually, run
-`npx -y @floomhq/floom add <url-or-slug> --force`.
+`floom sync` and `floom watch` are v1 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. Sync writes missing files only.
+Remote updates, existing untracked files, and locally edited tracked files are skipped as conflicts.
+Symlinks are never followed. To replace a local skill manually, run `floom add <url-or-slug> --force`.