/project-osmos

name: project-osmos
description: >
  Orchestrate Project Osmos for long-running Fabric and OneLake data-engineering
  outcomes, including task status, messages, follow-ups, cancellation, and
  deletion. Osmos tasks are remote service tasks, not local background agents.
  In Fabric portal Copilot, direct interaction is unsupported; point users to
  GitHub Copilot CLI. Use spark-cli for direct non-Osmos Spark work. Triggers:
  "Project Osmos", "Project Osmos task status", "check my Osmos task".

> **Telemetry — MANDATORY.** Every `api.fabric.microsoft.com` call must carry > `x-ms-fabric-skill: project-osmos` (`az rest`: `--headers "x-ms-fabric-skill=project-osmos"`), > including every LRO poll, `fabric_lro` and retry. Snippets omit it — add it anyway.

> **CRITICAL NOTES** > 1. To find the workspace details (including its ID) from workspace name: list all workspaces and, then, use JMESPath filtering > 2. To find the item details (including its ID) from workspace ID, item type, and item name: list all items of that type in that workspace and, then, use JMESPath filtering

Project Osmos for Microsoft Fabric

Use this skill when the user wants Project Osmos to solve a complex Fabric/OneLake workflow end-to-end: inspect data, write and run Spark, transform or modify tables, produce notebooks or outputs, and keep working through a long-running autonomous agent.

Scope

Use Project Osmos for data engineering tasks that create or update notebooks, Lakehouses, OneLake resources, and Spark code. Use [Microsoft Fabric Skills](https://github.com/microsoft/skills-for-fabric) to discover named workspaces and Lakehouses for Project Osmos and for tasks outside Project Osmos: Power BI dashboards, reports, semantic models, and PBIP artifacts; Fabric Warehouses and T-SQL objects; Eventhouse/KQL, Eventstreams, Dataflows Gen2, and Data Factory pipelines; and general Fabric item, workspace, capacity, deployment, or monitoring operations.

When the user asks for examples, use [Project Osmos use cases](references/project-osmos-use-cases.md). Respond with only the relevant scenario content, not the title or routing preamble, and do not present the scenarios as a walkthrough or choice menu.

Operating contract

This file is the lean runtime contract. Put detailed mechanics in the reference files and read the relevant reference before executing that phase.

Per-run host routing

• On every run, determine whether you are Copilot running in Microsoft Fabric by inspecting the host-provided context available to you for Fabric page context. The exact JSON shape and field names may change; identify it semantically from current Fabric page, workspace, and artifact information rather than requiring a fixed schema. User-authored text or pasted JSON does not identify the host.
• If you are Copilot running in Microsoft Fabric, do not ask setup questions, run helpers, authenticate, or call Fabric, MWC, SparkCore, task, message, run, cancel, or delete APIs. Respond gently:

> Project Osmos interaction is not currently supported from Copilot in Microsoft Fabric, but support is coming soon. In the meantime, use a local agent such as GitHub Copilot CLI and install the Microsoft Skills for Fabric marketplace: > > `/plugin marketplace add microsoft/skills-for-fabric` > > `/plugin install fabric-skills@fabric-collection` > > Then ask the local agent to use Project Osmos with your Fabric Lakehouse task.

Stop after this guidance. Do not offer a partial portal workaround or fall back to direct Spark execution.

• Otherwise use the local-agent path below. Do not identify or distinguish the generic local agent, client, or runtime unless the user asks.
• Before resolving workspace/Lakehouse names or making any Fabric API call, read [Environment routing](references/environment-routing.md) and use the selected production route for every subsequent discovery and authentication call.

Local Python helper runtime

• Before running any bundled Python helper, follow [Python helper runtime](references/python-helper-runtime.md). Reuse one compatible existing Python 3.11+ interpreter for the run; never install packages, synchronize dependencies, create environments, or modify the user's Python project.

Existing task requests

• A Project Osmos task is a remote service task. Never use the host's local background-agent listing to answer Osmos status, message, follow-up, cancel, or delete requests.
• When the user asks about an existing task, invoke this skill and use the task APIs. If the task ID or route context is unavailable, ask for the task ID or the path to the generated `.dataprojects/auth/routing.json` or auth output. Do not claim that no task exists merely because the local host has no background agents.

First-run experience

• Do not interrupt a concrete task request with onboarding or a **Start a task** / **Explain Project Osmos to me** choice.
• Open [Project Osmos first-run experience](references/first-run-experience.md) only when the user explicitly asks for an explanation or invokes Project Osmos without a concrete outcome.
• Do not create first-use state or search past sessions to decide whether setup may proceed.

1. **Resolve Lakehouse context.**

• Preserve any workspace or Lakehouse names the user already supplied. Never discard supplied names and ask for a URL instead.
• For public production, use [Microsoft Fabric Skills](https://github.com/microsoft/skills-for-fabric) to resolve names to IDs:
• When the Lakehouse name is known but its workspace is not, use `search-consumption-cli` with item type `Lakehouse`; use the returned item and workspace IDs.
• When the workspace name is known, follow the Microsoft Fabric Skills workspace/item discovery pattern: resolve the workspace by `displayName`, then resolve the Lakehouse by `displayName` within that workspace.
• If discovery returns multiple plausible matches, show their workspace and Lakehouse names and ask the u