Floom

One skill library, synced across every agent and machine.

Floom is an open-source skill distribution layer for AI agents. Publish a Markdown skill from your terminal, share it with a link, then install or sync it into the agents you use on each machine.

A Floom skill can be knowledge, instructions, a workflow, or an agent-native skill package. Use it for brand voice, company facts, coding standards, PR review loops, support playbooks, onboarding packs, sales workflows, and other reusable agent behavior.

Quickstart

Create a skill package:

npx -y @floomhq/floom init support-tone

Edit support-tone/SKILL.md, then publish it:

npx -y @floomhq/floom login
npx -y @floomhq/floom publish support-tone --public

Install a shared skill into a local agent:

npx -y @floomhq/floom add https://floom.dev/s/ffas93ud --setup

Pull your own published, saved, and subscribed library skills onto this machine:

npx -y @floomhq/floom sync
npx -y @floomhq/floom watch --interval 60

Print MCP setup commands:

npx -y @floomhq/floom mcp

Claude Code and Codex can also run the lightweight MCP server:

claude mcp add floom -- npx -y @floomhq/floom-mcp-sync
codex mcp add floom -- npx -y @floomhq/floom-mcp-sync

Agent Support

Agent	Version 1 support
Claude Code	First-class CLI setup with --target claude; MCP sync via @floomhq/floom-mcp-sync.
Codex	First-class CLI setup with --target codex; MCP sync via @floomhq/floom-mcp-sync.
Cursor	Manual support: add the Markdown skill locally and reference it from Cursor rules or project instructions.
Kimi	Manual support: paste or save the Markdown skill into the Kimi workflow you use.
OpenCode	Manual support: use shared Markdown skills directly.

Floom keeps Markdown as the source format so unsupported agents can still use the skill content without waiting for an integration.

Starter Examples

• examples/brand-voice-starter - a brand voice knowledge pack.
• examples/pr-review-workflow - a reusable code review workflow.
• examples/team-onboarding-pack - a starter onboarding pack for new agents.
• examples/hello-world.md - a minimal single-file skill.

Browse awesome-floom-skills for curated Claude skills, Codex skills, agent skills, reusable agent workflows, Claude Code skills, and AI agent workflows.

Skill Package Format

A native Floom skill package is a folder with SKILL.md at the root:

my-skill/
  SKILL.md
  references/
  examples/
  scripts/
  assets/

references/, examples/, scripts/, and assets/ are optional. Floom only packages those supporting directories, which keeps the share boundary explicit.

---
title: PR review workflow
description: Review code changes for launch-risk issues
type: workflow
version: 0.1.0
---

# PR Review Workflow

Use this skill when reviewing a pull request before release.

CLI Commands

• npx -y @floomhq/floom login - sign in with Google. Use --provider github for GitHub.
• npx -y @floomhq/floom init [path] - create a starter skill folder at <path>/SKILL.md; file.md paths create single-file skills.
• npx -y @floomhq/floom publish <path> - upload a skill folder or Markdown file. Add --update [slug-or-url] to update an existing skill you own.
• npx -y @floomhq/floom share <slug> - email-share one of your skills.
• npx -y @floomhq/floom list - show your published skills.
• npx -y @floomhq/floom add <url-or-slug> --setup - fetch a shared skill and connect supported agents.
• npx -y @floomhq/floom info <url-or-slug> - show skill metadata.
• npx -y @floomhq/floom search <query> - search public skills and starter libraries.
• npx -y @floomhq/floom setup --target claude|codex - add Floom guidance to CLAUDE.md or AGENTS.md.
• npx -y @floomhq/floom connect - alias for setup.
• npx -y @floomhq/floom mcp - print MCP setup commands.
• npx -y @floomhq/floom sync - pull published, saved, and subscribed library skills locally.
• npx -y @floomhq/floom watch - run sync repeatedly.
• npx -y @floomhq/floom library list - list public starter libraries.
• npx -y @floomhq/floom library subscribe <slug> - subscribe to a public or unlisted library.
• npx -y @floomhq/floom doctor - diagnose local Floom setup.

See cli/README.md for the complete CLI reference.

Version 1 Scope

In scope:

• Terminal-first publish, share, add, search, and setup.
• Public and unlisted skill links.
• Native folder skill packages.
• Public starter libraries.
• Manual sync and watch polling.
• MCP startup and polling sync for Claude Code and Codex.
• Missing-file-only local writes with conflict protection.

Out of scope:

• Hosted skill execution.
• Marketplace workflows.
• Team dashboards and approvals.
• Production-grade hot reload.
• Automatic deletion of local Markdown files.
• Automated setup for Cursor, Kimi, and OpenCode.

Repository Structure

• cli/ - Node 22 TypeScript CLI, published as @floomhq/floom.
• mcp-sync/ - MCP server, published as @floomhq/floom-mcp-sync.
• web/ - Next.js app for the public site, auth, API routes, and share pages.
• examples/ - starter skill packages and single-file examples.
• awesome-floom-skills/ - curated skill library index for agent workflows.
• supabase/ - SQL migrations for the Floom skill schema.

Development

Install and check the package you are changing:

cd cli
npm ci
npm run typecheck
npm run build
npm test

cd ../mcp-sync
npm ci
npx tsc --noEmit
npm run build
npm test

Web builds require Supabase environment variables. Use non-secret placeholders for build-only checks:

cd web
NEXT_PUBLIC_SUPABASE_URL=https://example.supabase.co \
NEXT_PUBLIC_SUPABASE_ANON_KEY=ci-placeholder-anon-key \
SUPABASE_SERVICE_ROLE_KEY=ci-placeholder-service-role-key \
npm run build

License

MIT. See LICENSE.