Rayfin is a Backend-as-a-Service: define your data model with TypeScript decorators and Rayfin provides auth, a typed data API, storage, and Fabric hosting.
This skill only handles getting started: getting you from zero into a working Rayfin
project, then handing off. The moment you're in a project, the authoritative, version-locked
skill at .agents/skills/rayfin/SKILL.md, alongside the package docs in node_modules and
the rayfin docs CLI, owns everything else: schema, auth, storage, querying, deployment.
Load it and stop using this one.
Route, don't improvise
Rayfin's specifics are version-locked per project — schema/decorator syntax, the typed data
API and client queries, auth, storage, and deployment all live in the project's own skill and
rayfin docs. Never answer them from memory; remembered Rayfin APIs are routinely
wrong against the installed version. Get into a project, read .agents/skills/rayfin/SKILL.md,
then follow it for version-matched signatures. The in-project skill file and the
rayfin docs CLI are available the moment a project exists — including right after you
scaffold one, in the same session.
Being blocked does not unlock memory. Only treat yourself as blocked if you can reach none
of the version-matched sources — you can't read .agents/skills/rayfin/SKILL.md and can't
run rayfin docs (e.g. tool permissions denied). When genuinely blocked, say you need those
sources to answer accurately and stop there. Don't offer a "general approach" or example code
"in the meantime"; that stopgap is exactly the fabrication this skill exists to prevent.
Already in a Rayfin project?
Check this first — before scaffolding anything, even when the user says "build" or "set up a
new app". A directory is a Rayfin project if it has rayfin/rayfin.yml or a package.json
depending on @microsoft/rayfin-*. Environment signals alone are enough: if the workspace
context shows either — even when you can't open the files yet — treat it as an existing
project and continue in place. Never stand up a nested or sibling project.
- Already in one → load
.agents/skills/rayfin/SKILL.mdand userayfin docs. Stop using this skill. - Existing non-Rayfin app here → add Rayfin in place with
npx -y -p @microsoft/rayfin-cli@latest rayfin init --project-name <app-name>(don't scaffold a separate project), then load the in-project skill. - Empty directory → scaffold (below), then load the in-project skill from the project root.
Scaffold a new project
npm create @microsoft/rayfin@latest is a thin wrapper around rayfin init. As an agent you
run non-interactively (stdin isn't a TTY), so use the npx -y form — npm create can
mishandle piped stdin and strip flags, and --project-name is required non-interactively.
# Use the CLI's bundled default app template. Keep this command on one line
# so it also works in PowerShell.
npx -y @microsoft/create-rayfin@latest --project-name <app-name> --template blankapp
# Or add Rayfin into an existing directory.
npx -y -p @microsoft/rayfin-cli@latest rayfin init --project-name <app-name> [directory]
Always use the bundled blankapp template. Don't browse the gallery or pick a
domain-specific template.
Mind the project root before loading the in-project skill: create-rayfin creates a child
project directory (named from --project-name, slugified), so cd into it; an in-place
rayfin init scaffolds in the current directory, so you're already there. Once at the project
root, read AGENTS.md first when the template ships a capability router, then load
.agents/skills/rayfin/SKILL.md for every version-locked Rayfin specific.