agentleFS
santoshkanthetysantoshkanthety/powerbi-agent/skills/powerbi-fabric-apps/SKILL.md

powerbi-fabric-apps

Skill3 starsChanged 7 months agoMITView on GitHub

Build, run and deploy Microsoft Fabric Apps with the Rayfin SDK and CLI — TypeScript decorator data models, Fabric SSO, GraphQL/DAB data API, storage, Functions, static hosting, and the fabric-semanticmodel connector that executes DAX against a Power BI semantic model from a custom app. Use when the user mentions: Fabric App, Fabric Apps, Rayfin, rayfin CLI, rayfin up, rayfin init, rayfin dev, rayfin connector, data app, backend as a service on Fabric, custom app on a semantic model, app on top of Power BI data, GraphQL on Fabric, Fabric SQL database app, appbackends, deploy an app to a Fabric workspace.

  • Reads credentials
  • Installs packages

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 4 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If you can reach none of those sources, say so and stop.

    line 38
  2. Distinctive:

    Check before scaffolding, even when the user says "new app".

    line 60
  3. Distinctive:

    Never create a nested or sibling project inside one that already exists.

    line 72
  4. Distinctive:

    Verify the decorator set against the in-project skill — this shape is the documented pattern, not a guarantee for your installed version:

    line 126
  5. Very specific:

    Keep the generated version value.

    line 197
  6. Very specific:

    Always branch on status before touching table.

    line 214
  7. Very specific:

    Query the model metadata before writing DAX: Never guess table, column or measure names.

    line 222

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Fabric Apps with the Rayfin SDK

Fabric Apps (preview) is a managed backend-as-a-service inside Microsoft Fabric. You declare the data model as TypeScript classes with decorators; Rayfin provisions the SQL database, Entra SSO, a GraphQL data API, file storage, Functions and static hosting, and deploys all of it as one Fabric item with npx rayfin up.

For powerbi-agent the headline use is the fabric-semanticmodel connector: an app that executes DAX against an existing Power BI semantic model with delegated user identity, so you can ship a bespoke analytical front end on a model you already govern — without embedding, without a service principal, and without the Execute Queries REST API in your own code.

Rule zero: route, don't improvise

Never write Rayfin API code from memory. The decorator set, the client generics, the connector packages and the deployment surface are version-locked per project, and they move fast in preview. Remembered signatures are routinely wrong against the installed version.

Order of authority, highest first:

  1. .agents/skills/rayfin/SKILL.md in the project — the version-matched skill the CLI installs. If it exists, it wins over this file for every in-project specific.
  2. rayfin docs CLI and the package READMEs under node_modules/@microsoft/rayfin-*.
  3. AGENTS.md at the project root, when the template ships a capability router.
  4. Microsoft Learn: Fabric Apps overview, CLI reference.

This skill owns getting there and the Power BI bridge. Once you are inside a project, load .agents/skills/rayfin/SKILL.md and follow it.

If you can reach none of those sources, say so and stop. Do not offer a "general approach" or placeholder code — fabricated Rayfin APIs are the specific failure this discipline exists to prevent.

Prerequisites

RequirementCheck
Node.js 20+node --version
Rayfin CLInpx rayfin --version (installs on demand; or npm i @microsoft/rayfin-cli)
Fabric capacity on the target workspacefab ls then check the workspace capacity, or the portal
Tenant setting Fabric Apps (preview) enabledFabric admin portal → Tenant settings
Tenant setting Semantic Model Execute Queries REST API enabledonly for the fabric-semanticmodel connector
Contributor / Member / Admin on the workspacefab acl ls or the portal
Build + Read on the semantic modelonly for the fabric-semanticmodel connector
Supported regionregion availability — Fabric Apps is not in every region

Fabric Apps consumes CUs from the assigned capacity. Before standing one up on a shared production capacity, read powerbi-fabric-capacity and tell the user the expected impact.

Is this already a Rayfin project?

Check before scaffolding, even when the user says "new app". A directory is a Rayfin project if either is true:

  • rayfin/rayfin.yml exists
  • package.json depends on any @microsoft/rayfin-* package
SituationDo this
Already a Rayfin projectLoad .agents/skills/rayfin/SKILL.md, continue in place
Existing non-Rayfin app hereAdd Rayfin in place: npx -y -p @microsoft/rayfin-cli@latest rayfin init --project-name <name>
Empty directoryScaffold (below)

Never create a nested or sibling project inside one that already exists.

Scaffold

Agents run non-interactively (stdin is not a TTY), so use the npx -y form — npm create can mishandle piped stdin and strip flags, and --project-name is required non-interactively.

# Analytical app on a semantic model — the Power BI case. Use this template.
npm create @microsoft/rayfin@latest -- "<app-name>" --template dataapp --workspace "<workspace-name>"

# Minimal app, no framework opinions
npx -y @microsoft/create-rayfin@latest --project-name <app-name> --template blankapp

# Add Rayfin to a directory that already has source
npx -y -p @microsoft/rayfin-cli@latest rayfin init --project-name <app-name> [directory]

# See what the installed CLI offers before choosing
npx rayfin init --list-templates

create-rayfin creates a child directory named from a slugified --project-name, so cd into it. An in-place rayfin init scaffolds into the current directory.

For the gallery of community templates and how to author one, see powerbi-fabric-app-templates.

Then read AGENTS.md (if present) and .agents/skills/rayfin/SKILL.md before writing a line of app code.

Project shape

<app>/
├── rayfin/
│   ├── rayfin.yml           # services, auth, static hosting, connectors — the contract
│   ├── .env                 # deployment properties; never commit secrets
│   ├── .deployments.json    # recorded deployments: fabricWorkspaceId, fabricItemId,
│   │                        #   hostingUrl, fabricDeepLink, deployedAt
│   ├── data/                # TypeScript entity classes — the schema source of truth
│   ├── connectors/<name>/   # generated connector schema (schema.ts, connectorConfig)
│   └── functions/           # Functions package (optional)
├── .agents/skills/rayfin/   # version-locked in-project skill — authoritative
├── AGENTS.md                # capability router, when the template ships one
└── src/                     # frontend

rayfin/.deployments.json is how any tool (including Kurt Buhler's /fabric-app-pane mod) knows where an app is deployed. Read it rather than asking the user for IDs.

Data model

Entities are plain TypeScript classes with decorators from @microsoft/rayfin-core. Verify the decorator set against the in-project skill — this shape is the documented pattern, not a guarantee for your installed version:

import { entity, role, text, boolean, date, uuid } from '@microsoft/rayfin-core';

@entity()
@role('authenticated', '*', {
  policy: (claims, item) => claims.sub.eq(item.user_id),
})
export class Todo {
  @uuid() id!: string;
  @text({ min: 1, max: 100 }) title!: string;
  @boolean() isCompleted!: boolean;
  @date() createdAt!: Date;
  @date({ optional: true }) dueDate?: Date;
  @text() user_id!: string;
}

Rayfin derives the table definitions, the GraphQL endpoints, the row-level authorization rules and the type-safe client methods from this.

The code is the only safe place to change schema. The child SQL database is editable in the Fabric portal, and editing it there causes schema conflicts that break the app. Change rayfin/data/, then npx rayfin up db apply.

The Power BI bridge: fabric-semanticmodel

This is the connector that makes Fabric Apps interesting to a Power BI practice. It gives the app typed, delegated, read-only DAX execution against a semantic model.

# 1. Find the model (omit --workspace-id to search the project's recorded workspaces)
npx rayfin connector search --workspace-id <workspace-id> --type fabric-semanticmodel --json

# 2. Add it
npx rayfin connector add \
  --type fabric-semanticmodel \
  --workspace-id <workspace-id> \
  --item-id <semantic-model-item-id> \
  --name salesModel \
  --operations executeQuery

# 3. Run the npm install command the CLI prints — verbatim. It is version-matched.

# 4. Inspect without changing anything; --url accepts a portal URL and derives both IDs
npx rayfin connector inspect --name salesModel --entity Sales --rows 10
npx rayfin connector inspect --url "https://app.powerbi.com/groups/<ws>/datasets/<id>"
npx rayfin connector inspect --name salesModel --query ./queries/top-products.dax

# 5. Smoke-test an operation from the terminal before wiring the UI
npx rayfin connector invoke salesModel executeQuery --input '{"query":"EVALUATE ROW(\"n\", 1)"}'

connector add writes to rayfin/rayfin.yml:

connectors:
  - name: salesModel
    type: fabric-semanticmodel
    config:
      workspaceId: "<workspace-id>"
      itemId: "<semantic-model-item-id>"
    auth:
      type: delegated
    version: "1"
    operations:
      - name: executeQuery

Keep the generated version value. Do not hand-edit workspaceId / itemId when a connector subcommand can set them.

Client side — one data-access path, the connector client:

const result = await client.connectors.salesModel.executeQuery({
  query: 'EVALUATE TOPN(10, Sales)',
});

if (result.status === 'success') {
  render(result.table.columns, result.table.rows);
} else {
  showError(result.error.category, result.error.message);
}

Always branch on status before touching table. A failed query must surface an error state — never substitute mock data for a connector failure.

DAX inside a Fabric App

The DAX discipline does not change because the host is a web app. powerbi-dax-mastery and powerbi-dax-performance still apply, plus:

  • Query the model metadata before writing DAX. Never guess table, column or measure names. pbi-agent model tables / model measures against the model (or rayfin connector inspect --entity) first.
  • Bound every result set. TOPN, an explicit row cap, or a filtered SUMMARIZECOLUMNS. An unbounded EVALUATE Sales on a real fact table will take the app down, not just slow it.
  • Reuse results. Each executeQuery is a capacity-billed query against the model. Cache per interaction rather than per component render.
  • Apply the model's format strings to cards, axes, tooltips, data labels and grid cells, so the app agrees with the reports built on the same model.
  • Delegated auth only. RLS on the model is enforced because the caller is the signed-in user. Never add a service principal, a stored token, or a direct call to the Execute Queries REST API to work around a permission error — fix the permission.

Other connector types are available; npx rayfin connector types -v lists what the installed CLI supports (lakehouse, warehouse, SQL database in Fabric, semantic model).

Local development

npx rayfin dev                              # full stack locally
npx rayfin dev --workspace "<ws-name>"      # first run, names the backend workspace
npx rayfin dev --skip-db-apply              # don't auto-apply schema
npx rayfin dev functions apply              # local Functions host (default port 7071)
npx rayfin env --framework vite             # emit .env.local from rayfin/.env
npx rayfin env --framework nextjs --show    # preview without writing

Local dev may use email/password auth. Deployed apps are Fabric SSO only — no other provider is available after deployment. Do not build a sign-in flow that assumes otherwise.

Deploy

npx rayfin login                            # and: rayfin login status / rayfin logout
npx rayfin up --dry-run --verbose           # always first: validates and resolves the workspace
npx rayfin up --workspace-id <id> --yes     # non-interactive deploy
npx rayfin up --exclude-services functions  # skip functions or staticHosting
npx rayfin up status --json
npx rayfin up list                          # every recorded deployment
npx rayfin up switch --list                 # then: rayfin up switch <workspace>

Targeted re-deploys, when only one service changed:

CommandDeploys
npx rayfin up db applyDAB config / schema to the remote item
npx rayfin up staticapp deploy [--skip-build]built frontend assets
npx rayfin up functions deploy [--skip-build]Functions
npx rayfin up connector apply [--name <n>]declared GraphQL connector config

--force on rayfin up allows destructive data-schema changes. Treat it the way you treat DROP: name the entity and the column, say what data is lost, and get an explicit yes before running it. Never add --force to clear an error you have not diagnosed.

--capacity-id cannot be combined with --workspace, --workspace-id or --workspace-uri.

Deployed topology

One backend endpoint fronts every service:

https://<your-app>-app.rayfin.windows.net/
  /api/graphql    data API, used by the Rayfin client
  /auth           authentication
  /storage        file storage

Child items appear under the Fabric app in the portal: the SQL database (read-only there), authentication, and static content. Item permissions do not inherit from workspace roles — a user needs Run and interact to use the app, Edit to deploy to it, Reshare to grant access.

Agent context files

npx rayfin init ai-files status --json      # up-to-date / update-available / user-modified / missing / …
npx rayfin init ai-files install --yes      # idempotent; preserves user config
npx rayfin init ai-files install --force skill:rayfin
npx rayfin init ai-files install --dry-run

This manages AGENTS.md, .mcp.json and .agents/skills/rayfin/SKILL.md. --force never overwrites AGENTS.md. Run status at the start of any session in an existing project: a user-modified or stale in-project skill is the usual cause of code that compiles against the wrong Rayfin version.

Security

You own, and Fabric does not:

  • No secrets in the repo, in rayfin/.env commits, or in frontend assets — regardless of the assetAccess setting. Static assets are shipped to the browser.
  • What authenticated users can see and do. SSO proves identity; your @role policies and your queries decide authorization.
  • Least privilege for contributors. Edit on the item means they can rayfin up.
  • Compliance accountability for whatever the app stores. An app over a governed semantic model that persists extracts into its own SQL database has created a second copy of that data — say so, and check it against powerbi-data-governance-traceability.

Not a fit

Say so early rather than fighting the platform:

  • Complex multi-step transactions or stored procedures.
  • Custom auth providers beyond Fabric SSO (and email/password locally).
  • Anything needed in a region where Fabric Apps is not yet available.
  • A report. If the deliverable is a report, build a report — powerbi-create-pbi-report. Fabric Apps is for interactions a report cannot express.

Related skills

NeedSkill
Template gallery, choosing and authoring templatespowerbi-fabric-app-templates
CU cost of running the app on a capacitypowerbi-fabric-capacity
Workspace / item plumbing around the apppowerbi-fabric-cli
DAX the app will executepowerbi-dax-mastery, powerbi-dax-performance
Chart choice and formatting in the frontendpowerbi-report-design
Governance of a second copy of governed datapowerbi-data-governance-traceability

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.