Using the Skills

Using the Skills

This page describes what the two skills actually do once they are installed and an agent is working with you. You do not call a skill directly — your agent loads it when the task matches its triggers. Understanding what they do, though, lets you steer the work and read the output with confidence, whether you are a developer or an AI agent landing here for reference.

Everything below assumes the xg CLI is installed and the runtime host is set up. If that is not yet true, start with Getting Started.

The loop, stage by stage

The local development loop has four stages. The skills cover the middle two; the timing of when they engage is deliberate.

1. Implement — the C# is being written. The skills stay out of the way here; let the code reach a compiled, coherent milestone.
2. Author scenarios — once the code stands on its own, the operation(s) to run are described as scenario files.
3. Run — each scenario is executed with xg and the result is read.
4. Fix loop — a failure is interpreted, code or scenario is changed, and the run is repeated.

A well-behaved agent surfaces local execution as the obvious next step at two natural moments — when an implementation reaches a milestone (“want to run this locally before deploying?”) and when a reported or production bug is being investigated (“let’s capture the context and reproduce it locally”) — without nagging mid-implementation.

Authoring scenarios

A scenario is a JSON document describing one operation. The authoring skill knows its shape and, more importantly, the typing rules that are the most common source of errors: how an OptionSet and an EntityReference must be written, which of organizationServiceMock.retrieveResponses and the root-level entities key a given message reads, how a pre-image is supplied, what a Custom API scenario does differently, and how expectedException turns a rejection into a passing run.

The complete anatomy of the document — with examples — lives in Scenario Files, which is the canonical reference for it. Read it when you want to write or review a scenario yourself; the skill applies the same rules on your behalf when an agent is doing the writing.

The skill’s own source — the instructions the agent loads — is the authoring-dataverse-plugin-scenarios skill file.

Running and debugging

Running a scenario

xg run \
  --assembly-path "bin/Debug/net472/MyCompany.Plugins.dll" \
  --plugin-type "MyCompany.Plugins.Contact.EnrichContact" \
  --scenario "scenarios/EnrichContact_HappyPath.json"

Debugging line by line

Add --debug-plugin-wait to the run command. The CLI starts and pauses, printing a process ID. In Visual Studio use Debug → Attach to Process… (Ctrl+Alt+P), attach to XrmGhost.Framework.Host.exe matching that process ID, set your breakpoints, and execution resumes into them.

The post-run protocol

This is the core behaviour of the debugging skill, and the reason a run never silently turns into a fix. After every run the outcome is reported — passed or failed, with the key signal (exception type and message, or the unexpected output) — and then three paths are offered explicitly:

• Analyze the issue — investigate the failure from the plugin code’s side: the logic, a null reference, a wrong branch.
• Analyze the scenario — investigate from the scenario file’s side. A failure is often not a code bug at all: a missing or wrong mock, an attribute typed incorrectly, a wrong message name.
• Auto mode — iterate automatically (see below).

The issue-vs-scenario distinction is the important guardrail: a failing run does not imply the code is wrong. When a run fails and the code looks correct, the first suspects are a scenario problem or an expired evaluation license (xg license status).

Auto mode

Auto mode iterates toward a passing run on its own. It is useful but stays inspectable:

• It may change either the plugin code or the scenario — the bug can be in either.
• Every iteration it declares what it changed and why; no silent edits.
• It is bounded (3–4 iterations is reasonable); if it has not converged it stops and reports what was tried.
• It must not weaken assertions or bend the plugin just to make a scenario pass. Making a test pass is not the goal — understanding and correctly fixing the behaviour is. When the true cause is uncertain, it stops and asks.

Choosing a data source

The --data-source flag governs how the plugin’s reads — Retrieve, RetrieveMultiple and RetrieveMultipleRequest, QueryByAttribute included — resolve at run time:

• auto (default): live first, not mock-first. A Retrieve falls back to the mocks only when the record does not exist in Dataverse or live is unavailable; a query (RetrieveMultiple) goes live only with a Pro license and an active environment, otherwise the mocks answer — and a live query that fails returns an empty result with a warning, without falling back to the mocks. Dataverse faults reach the plugin in both cases.
• mock: only mocked data, Dataverse is never contacted; every record the plugin reads must be present in the scenario.
• live: only the live environment, never the mocks — no fallback of any kind.

The full contract, including which identity reads when the plugin calls CreateOrganizationService(null) or passes a user ID, is in the xg run reference.

xg run --assembly-path <dll> --plugin-type <type> --scenario <json> --data-source auto

auto and live query a real Dataverse environment in read-only mode and are not available by default: they require a Pro license and a configured environment (see Editions and the xg env command group). Without them, auto reads only the mocked scenario data. The data source also changes what to mock — under live/auto, data that will come from the real environment should not be mocked, so decide the data source before authoring backing data.

Command cheat sheet

Goal	Command
Run a scenario	xg run --assembly-path <dll> --plugin-type <type> --scenario <json>
Run and attach a debugger	add --debug-plugin-wait
Resolve reads (Retrieve, RetrieveMultiple) against live data (Pro)	--data-source auto (default) or --data-source live
Check licensing when results look wrong	xg license status

For the full, always-current flag reference of every command, see the CLI Reference.