Consolidate Fabric monitoring into one operable skill
Fabric estates accumulate half-scripts: a notebook that checks capacities, a shell history that lists failed jobs, a wiki page with screenshots from last quarter. Each produces a different health story. On-call picks a favorite. Coding agents inherit the contradiction.
Consolidate into one operable skill. Clear verbs beat tribal shell history. Agents consuming monitor tools need stable output contracts. Separate diagnosis from remediation. Version runbooks like product code. Many half-scripts create contradictory signals; one interface creates a shared truth you can improve.
Figure 1. Monitoring should be an operable interface with stable outputs, not a pile of one-off scripts. Source: Microsoft Learn: monitoring hub.
I learned this when three "is Fabric healthy?" answers disagreed before lunch. None were wrong for their narrow lens. Together they trained people to distrust automation. A single skill with verbs and contracts made humans and agents ask the same questions.
The core idea
Monitoring is a product surface for operators and agents, not a folder of souvenirs.
Scripts without contracts drift. Contracts without versioning fossilize. Diagnosis mixed with remediation makes every check feel dangerous. A skill-shaped interface with read verbs first gives you a place to hang tests, docs, and safe defaults.
A model that stays explainable
1. One skill, many verbs
Expose list-failures, capacity-snapshot, job-status, and lineage-neighbors as named verbs. Operators learn a menu. Agents call tools without scraping wiki HTML. New checks become new verbs, not new repos.
2. Stable output contracts
Return structured fields: workspace, item, status, time window, link. Humans can read tables; agents can parse JSON. Pretty-printed chaos is not a contract. Schema versions belong in the header.
3. Diagnosis before remediation
Read-only verbs are the default. Mutating verbs (retry, cancel, scale request) require explicit confirmation modes and audit logs. A monitor that silently fixes things is an unowned change agent.
4. Kill contradictory half-scripts
Inventory personal scripts and retire them into the skill or into archive with a pointer. Dual sources of health truth will always fight. Consolidation is a deletion exercise as much as a build exercise.
5. Version runbooks like product code
Store runbook markdown next to the skill. Tag releases. When capacity semantics change, bump the skill and the doc together. Tribal updates in chat are not version control.
6. Design for agent consumers explicitly
Coding agents need deterministic tool results and non-interactive defaults. Avoid prompts that only humans can answer mid-flight. If a verb needs judgment, return candidates and reasons, not a hanging question.
Failure modes I design against
Script museums. Everyone has a different truth.
Remediation in disguise. Checks mutate state.
Unstructured stdout. Agents hallucinate status from prose.
Wiki drift. Screenshots older than the platform UI.
No audit on mutate. Retries without a trail.
Infinite verbs. A junk drawer with a CLI wrapper.
What good verb design feels like
A verb names an operator intent, not an API souvenir. Prefer "list failed pipeline runs in window" over "call this undocumented REST path." Wrap platform APIs behind the skill so API churn hits one place. Document rate limits and required permissions beside the verb. If two verbs overlap, merge them before agents learn both.
Separating human UX and agent UX without forking truth
Humans like summaries and links into the Fabric portal. Agents like compact JSON. Serve both from one contract: structured data plus an optional presentation layer. Do not maintain a "human script" and an "agent script" that diverge. The skill is shared; the renderer differs.
How to migrate without a big-bang
Pick the top five questions on-call asks. Implement those verbs first. Point the wiki at the skill. Delete or archive the old scripts in the same PR when possible. Add contract tests that freeze sample outputs. Expand verbs only when a real incident shows a gap. Consolidation fails when it tries to boil the ocean before the first useful lunchtime check.
Trade-offs
Building a skill costs packaging and ownership. Living with script museums costs every incident. Strict output contracts slow casual hacking and speed automation. Separating diagnosis from remediation adds a confirmation step; mixing them adds surprise. Versioning runbooks is ceremony; unversioned runbooks are fiction.
What I would put on an ADR
- Fabric monitoring converges on one versioned skill/runbook interface.
- Verbs are named, documented, and covered by output contracts.
- Diagnosis verbs are default; remediation verbs are explicit, audited, and gated.
- Contradictory personal scripts are retired or archived with pointers.
- Runbooks version with the skill; platform changes bump both.
- Agent consumers are first-class: non-interactive, structured, deterministic.
Primary references: Fabric Monitoring hub and capacity metrics guidance on Microsoft Learn, plus your internal tool-calling conventions for agents. Pair the skill README with on-call expectations so humans and agents share verbs.
Permissions and least privilege for monitor verbs
Monitor skills often start with a broad admin identity because it is easy. That teaches agents and humans the wrong habit. Prefer read scopes for diagnosis verbs and separate identities or elevation paths for remediation. Document which workspace roles each verb needs. If a verb requires more than it uses, shrink it. Least privilege is part of the output contract: a tool that can silently delete pipelines is not a monitor.
Closing
Health should not depend on whose shell history you trust.
Consolidate verbs. Freeze contracts. Diagnose before you mutate. Version the runbook. Design for agents without abandoning humans. One operable skill beats a museum of almost-monitors.