Skill authoring

Build skills agents actually use.

A Floom skill is reusable behavior for an agent: knowledge, instructions, workflows, or a more complete capability. Good skills tell the agent when to use them, what to do, and what to output.

Start from a template

Templates remove the blank page and teach the structure by example.

$ npx -y @floomhq/floom init support-tone.md --template support

brand-voicecompany voice and approved language

pr-reviewrisk-first code review behavior

salesaccount research and outreach prep

supportclear support replies and escalation rules

onboardingteam context and first-week guidance

Pick the right type

knowledge — Facts the agent needs: brand voice, company context, onboarding notes, customer facts.

instruction — Rules for behavior: tone, review style, coding standards, escalation rules.

workflow — A repeatable process with inputs, steps, and a defined output.

skill — A fuller agent capability with examples, resources, or tool usage.

Use this shape

---
title: Short human title
description: One sentence saying what job this helps the agent do.
type: knowledge | instruction | workflow | skill
installs_as: claude_skill | memory | rule | codex_instruction
version: 1.0
---

# Title

## Use when
- The exact situations where the agent applies this.

## Inputs
- What the user or environment must provide.

## Instructions
- Ordered behavior.
- Constraints and safety limits.

## Output
- The shape of the answer or artifact.

## Examples
- One short before/after or input/output example.

Make discovery easy

Agents see the title and description first. Put the trigger in the description, then repeat it as a Use when section near the top.

Use concrete jobs: Review a PR for launch risk beats Improve code.
State the expected input and output.
Keep rare background in links or references.
Include examples when tone, format, or judgment matters.

Complex and code-based skills

Floom Version 1 publishes one Markdown entrypoint. For complex skills, make that file the entrypoint and link to the supporting repo, scripts, config, or examples.

## Resources
- Repo template: https://github.com/acme/audit-skill-template
- Script path after clone: scripts/audit.ts
- Config example: examples/audit.config.json

## Setup
1. Clone the template repo if files are not present.
2. Run npm install.
3. Run npm test before using generated findings.

## Instructions
1. Inspect changed files first.
2. Run the audit script.
3. Verify every finding against source code.
4. Return only confirmed issues with file paths.

Scan before publish

Floom scans for high-confidence secrets, prompt injection, and data exfiltration patterns before upload.

$ npx -y @floomhq/floom scan support-tone.md

Publish, share, organize

$ npx -y @floomhq/floom publish support-tone.md --type instruction --public
$ npx -y @floomhq/floom publish support-tone.md --share teammate@example.com
$ npx -y @floomhq/floom library create support-pack --name "Support pack" --unlisted
$ npx -y @floomhq/floom library add support-pack support-tone --folder support/tone

Libraries group related skills. Folders control where synced skills land locally. Version 1 keeps teams simple with links and libraries; private workspaces and roles come later.