rayfin-getting-started
Use when starting or creating a NEW Rayfin app, or when a Rayfin task comes up and you are not yet inside a Rayfin project. Gets you into a project with the Rayfin CLI, then hands off to the authoritative, version-locked in-project rayfin skill/docs that own all in-project work. Triggers: build a Rayfin app, start a Rayfin project, create a new Rayfin app, create-rayfin, npm create @microsoft/rayfin, rayfin init, scaffold rayfin, rayfin CLI, rayfin template, universal app, awesome-rayfin gallery, get started with Rayfin
- License 许可
- MIT
- 所属仓库
- microsoft/rayfin
- 最近更新
- 2026-11-12
- Stars
- ★ 662
- Forks
- 77
01 前言 Front Matter
- name
- rayfin-getting-started
- metadata
- { "author": "microsoft", "version": "0.4.0" }
- description
- Use when starting or creating a NEW Rayfin app, or when a Rayfin task comes up and you are not yet inside a Rayfin project. Gets you into a project with the Rayfin CLI, then hands off to the authoritative, version-locked in-project rayfin skill/docs that own all in-project work. Triggers: build a Rayfin app, start a Rayfin project, create a new Rayfin app, create-rayfin, npm create @microsoft/rayfin, rayfin init, scaffold rayfin, rayfin CLI, rayfin template, universal app, awesome-rayfin gallery, get started with Rayfin
03 SKILL.md 正文
Rayfin (Getting Started)
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. The rayfin MCP server is an optional extra that most
projects do not install; if it happens to be available it is a convenience, never a
prerequisite. Lean on the in-project skill file plus rayfin docs.
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). The rayfin MCP server not being installed
or loaded is not a blocker. 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(or therayfinMCP, if already installed). Stop using this skill. - Existing non-Rayfin app here → add Rayfin in place with
npx rayfin init(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.
# Create non-interactively. --project-name is required; the template is pinned.
npx -y @microsoft/create-rayfin@latest --project-name <app-name> --template universal-app
# Or add Rayfin into an existing/empty directory
npx rayfin init [directory]
Always scaffold universal-app. Don't browse the gallery and don't pick a domain-specific
template. The Universal App is a deliberately small React + Vite base with a built-in
capability router that pulls in the right Rayfin services, npm modules, and skills on demand,
so the domain shape (analytics, CRUD, storage, functions) gets decided inside the project
rather than at scaffold time. The project's own .agents/skills/ own that decision, and they
are version-matched in a way a scaffold-time template choice is not.
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, load its .agents/skills/rayfin/SKILL.md and let its capability router take over.
04 同仓库更多 Skills
rayfin-getting-started
Use when starting or creating a NEW Rayfin app, or when a Rayfin task comes up and you are not yet inside a Rayfin project. Gets you into a project with the Rayfin CLI, then hands off to the authoritative, version-locked in-project rayfin skill/docs that own all in-project work. Triggers: build a Rayfin app, start a Rayfin project, create a new Rayfin app, create-rayfin, npm create @microsoft/rayfin, rayfin init, scaffold rayfin, rayfin CLI, rayfin template, universal app, awesome-rayfin gallery, get started with Rayfin
visuals
Use when user wants to incorporate charts, graphs, data grid, or other visual representations of data into their project. Use VegaVisual and DataGrid components to create these visuals, utilizing the shared DataTable input, formatting, theme, and interactivity. Covers the onInteraction selection/click events host apps consume, named multi-table data input for layered overlays and reference lines, and Vega-Lite native selections. Triggers: chart, graph, plot, dashboard, KPI, metric, trend, scorecard, data grid, visualize.
schema-discovery
Explore Power BI semantic model schemas using DAX INFO functions. Progressive metadata discovery strategy, scope estimation, and narrowing techniques for tables, columns, measures, and relationships.
query-design
Separates DAX data-fetching from TypeScript presentation. Guides when to use DAX vs. TypeScript vs. Vega-Lite for aggregation, total rows, FORMAT(), SELECTCOLUMNS, BLANK handling, filtering, multi-grain queries, cross-filtering and cross-highlight subset/overlay queries, and format strings.
functions-capability
Apply and build the Universal App functions capability. Use for trusted server-side logic, secrets, external APIs, custom model endpoints, published Fabric data agents, webhooks, or privileged operations.
fabric-sdk
How to query Fabric data from a running app through the Rayfin connectors client. Use getRayfinClient().connectors.<name>.executeQuery to run DAX against a semantic model, and toQueryResult to normalize the response.