From 0fd03ad35db0154131bfb05c3fc5dc842765749a Mon Sep 17 00:00:00 2001 From: David Pine <7679720+IEvangelist@users.noreply.github.com> Date: Mon, 8 Jun 2026 09:29:35 -0500 Subject: [PATCH 1/3] Document AI agent skill usage telemetry in CLI telemetry reference Extend the Microsoft-collected CLI telemetry page to cover the agent telemetry hooks installed by 'aspire agent init': the three event types (skill_invocation, tool_invocation, reference_file_read), the exact low-cardinality fields recorded, the privacy guarantees (only Aspire-owned skill/tool names and skill-relative reference paths; never absolute paths, repo or user names, file contents, or tool arguments), and the ASPIRE_CLI_AGENT_TELEMETRY_OPTOUT / --no-telemetry-hooks opt-out paths. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../cli/microsoft-collected-cli-telemetry.mdx | 54 +++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/src/frontend/src/content/docs/reference/cli/microsoft-collected-cli-telemetry.mdx b/src/frontend/src/content/docs/reference/cli/microsoft-collected-cli-telemetry.mdx index 00ee2525e..5dd8dcc50 100644 --- a/src/frontend/src/content/docs/reference/cli/microsoft-collected-cli-telemetry.mdx +++ b/src/frontend/src/content/docs/reference/cli/microsoft-collected-cli-telemetry.mdx @@ -11,6 +11,12 @@ The Aspire CLI collects usage telemetry to help Microsoft improve the product. T Aspire CLI telemetry is collected when using the CLI to run commands. Telemetry is gathered during normal CLI usage, unless you have [opted out](#how-to-opt-out) of telemetry collection. +### AI agent skill usage + +When you run `aspire agent init`, Aspire installs Aspire's AI skills and a `PostToolUse` hook into each detected agent client's user-level configuration (for example, GitHub Copilot CLI and Claude Code). The hook lets Aspire understand which of its AI skills and tools are actually used so the team can invest in the most valuable ones. + +After each agent tool use, the hook inspects the event and—only when an **Aspire** skill, Aspire MCP tool, or Aspire skill reference file was involved—forwards a low-cardinality usage event to the hidden `aspire agent telemetry` command, which records it through the same CLI telemetry pipeline. Tool uses that don't involve Aspire skills or tools are ignored. See [AI agent skill usage data](#ai-agent-skill-usage-data) for exactly what's recorded. + ## How to opt-out To opt-out of telemetry collection, set the `ASPIRE_CLI_TELEMETRY_OPTOUT` environment variable to `true`. This will disable telemetry collection for all CLI commands: @@ -32,6 +38,31 @@ $env:ASPIRE_CLI_TELEMETRY_OPTOUT="true" +### Opt out of AI agent skill usage only + +If you want to keep general CLI telemetry but disable only the [AI agent skill usage](#ai-agent-skill-usage) reporting, set the `ASPIRE_CLI_AGENT_TELEMETRY_OPTOUT` environment variable to `true`. Both the hook scripts and the `aspire agent telemetry` command honor this variable, so no agent usage events are recorded or sent: + + +
+ +```bash +export ASPIRE_CLI_AGENT_TELEMETRY_OPTOUT=true +``` + +
+
+ +```powershell +$env:ASPIRE_CLI_AGENT_TELEMETRY_OPTOUT="true" +``` + +
+ + +Setting `ASPIRE_CLI_TELEMETRY_OPTOUT` to `true` also disables AI agent skill usage reporting. + +To skip installing the agent telemetry hooks entirely, pass `--no-telemetry-hooks` when running `aspire agent init`. Existing hooks are removed and refreshed on the next `aspire agent init` run. + ## Disclosure The first time you run an Aspire CLI command, you'll see a disclosure message informing you that telemetry is being collected and how to opt out. @@ -50,6 +81,29 @@ Aspire CLI collects the following data: | 13.2 | Ensure .NET SDK install. | Includes .NET SDK version installed. | | 13.2 | CLI-related unhandled exceptions. | — | | 13.5 | Coding agent detection. | When the CLI is invoked from a known coding agent environment (such as GitHub Copilot, Claude, Cursor, or others), the detected agent name is recorded. Only the known agent name is sent — no environment variable values or other identifying data are included. This data point is omitted entirely when no known coding agent is detected. | +| 13.5 | AI agent skill usage. | Recorded only for Aspire's own skills and tools. See [AI agent skill usage data](#ai-agent-skill-usage-data). | + +### AI agent skill usage data + +The agent telemetry hook installed by `aspire agent init` reports a single event each time one of Aspire's own AI skills or tools is used. Three event types are reported: + +- `skill_invocation` — an Aspire skill was invoked, or its `SKILL.md` was read. +- `tool_invocation` — an Aspire MCP tool was called. +- `reference_file_read` — a reference file bundled alongside an Aspire skill was read. + +Each event records only the following low-cardinality, Aspire-owned values: + +| Field | Description | +|-------|-------------| +| Event type | One of `skill_invocation`, `tool_invocation`, or `reference_file_read`. | +| Client name | The agent client that produced the event, for example `copilot-cli`, `claude-code`, or `vscode`. | +| Session ID | The agent session identifier (an opaque GUID), used to group events from one session. | +| Skill name | The Aspire skill name, matched against the fixed list of skills Aspire ships (for example `aspire-deployment`). | +| Tool name | The Aspire MCP tool name (for example `aspire-list_resources`). | +| File reference | The skill-relative path of a reference file, for example `aspire/references/deploy.md`. | +| Event timestamp | The UTC time the event occurred. | + +To protect your privacy, the hook only forwards an event when the skill or tool name matches the fixed set Aspire ships, and a file reference is reported only as the path **after** the skill folder. Absolute paths, repository names, user names, file contents, and tool arguments are never recorded. The `aspire agent telemetry` command independently re-validates each value and re-checks the opt-out settings before anything is sent, and discards anything it doesn't recognize. ## See also From 8ff136bc9d431da208dc934d88f15cdaee0f75f3 Mon Sep 17 00:00:00 2001 From: David Pine <7679720+IEvangelist@users.noreply.github.com> Date: Mon, 8 Jun 2026 10:42:24 -0500 Subject: [PATCH 2/3] Simplify CLI telemetry docs to a single opt-out Remove the AI-only opt-out section (ASPIRE_CLI_AGENT_TELEMETRY_OPTOUT) and the 'aspire agent init --no-telemetry-hooks' note. The single ASPIRE_CLI_TELEMETRY_OPTOUT switch disables all CLI telemetry including AI agent skill usage. Soften the over-claimed opt-out re-check wording. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../cli/microsoft-collected-cli-telemetry.mdx | 27 +------------------ 1 file changed, 1 insertion(+), 26 deletions(-) diff --git a/src/frontend/src/content/docs/reference/cli/microsoft-collected-cli-telemetry.mdx b/src/frontend/src/content/docs/reference/cli/microsoft-collected-cli-telemetry.mdx index 5dd8dcc50..8348d46fd 100644 --- a/src/frontend/src/content/docs/reference/cli/microsoft-collected-cli-telemetry.mdx +++ b/src/frontend/src/content/docs/reference/cli/microsoft-collected-cli-telemetry.mdx @@ -38,31 +38,6 @@ $env:ASPIRE_CLI_TELEMETRY_OPTOUT="true" -### Opt out of AI agent skill usage only - -If you want to keep general CLI telemetry but disable only the [AI agent skill usage](#ai-agent-skill-usage) reporting, set the `ASPIRE_CLI_AGENT_TELEMETRY_OPTOUT` environment variable to `true`. Both the hook scripts and the `aspire agent telemetry` command honor this variable, so no agent usage events are recorded or sent: - - -
- -```bash -export ASPIRE_CLI_AGENT_TELEMETRY_OPTOUT=true -``` - -
-
- -```powershell -$env:ASPIRE_CLI_AGENT_TELEMETRY_OPTOUT="true" -``` - -
- - -Setting `ASPIRE_CLI_TELEMETRY_OPTOUT` to `true` also disables AI agent skill usage reporting. - -To skip installing the agent telemetry hooks entirely, pass `--no-telemetry-hooks` when running `aspire agent init`. Existing hooks are removed and refreshed on the next `aspire agent init` run. - ## Disclosure The first time you run an Aspire CLI command, you'll see a disclosure message informing you that telemetry is being collected and how to opt out. @@ -103,7 +78,7 @@ Each event records only the following low-cardinality, Aspire-owned values: | File reference | The skill-relative path of a reference file, for example `aspire/references/deploy.md`. | | Event timestamp | The UTC time the event occurred. | -To protect your privacy, the hook only forwards an event when the skill or tool name matches the fixed set Aspire ships, and a file reference is reported only as the path **after** the skill folder. Absolute paths, repository names, user names, file contents, and tool arguments are never recorded. The `aspire agent telemetry` command independently re-validates each value and re-checks the opt-out settings before anything is sent, and discards anything it doesn't recognize. +To protect your privacy, the hook only forwards an event when the skill or tool name matches the fixed set Aspire ships, and a file reference is reported only as the path **after** the skill folder. Absolute paths, repository names, user names, file contents, and tool arguments are never recorded. Before sending, the `aspire agent telemetry` command validates each value, discards anything it doesn't recognize, and honors the same `ASPIRE_CLI_TELEMETRY_OPTOUT` opt-out. ## See also From bbc5fc8dfc96d6da1f51213ebd21b352a4bdcd1a Mon Sep 17 00:00:00 2001 From: David Pine Date: Mon, 6 Jul 2026 06:34:49 -0500 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: Alistair Matthews --- .../docs/reference/cli/microsoft-collected-cli-telemetry.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/frontend/src/content/docs/reference/cli/microsoft-collected-cli-telemetry.mdx b/src/frontend/src/content/docs/reference/cli/microsoft-collected-cli-telemetry.mdx index 8348d46fd..ef3c17590 100644 --- a/src/frontend/src/content/docs/reference/cli/microsoft-collected-cli-telemetry.mdx +++ b/src/frontend/src/content/docs/reference/cli/microsoft-collected-cli-telemetry.mdx @@ -15,7 +15,7 @@ Aspire CLI telemetry is collected when using the CLI to run commands. Telemetry When you run `aspire agent init`, Aspire installs Aspire's AI skills and a `PostToolUse` hook into each detected agent client's user-level configuration (for example, GitHub Copilot CLI and Claude Code). The hook lets Aspire understand which of its AI skills and tools are actually used so the team can invest in the most valuable ones. -After each agent tool use, the hook inspects the event and—only when an **Aspire** skill, Aspire MCP tool, or Aspire skill reference file was involved—forwards a low-cardinality usage event to the hidden `aspire agent telemetry` command, which records it through the same CLI telemetry pipeline. Tool uses that don't involve Aspire skills or tools are ignored. See [AI agent skill usage data](#ai-agent-skill-usage-data) for exactly what's recorded. +After each agent tool use, the hook checks if an **Aspire** skill, Aspire MCP tool, or Aspire skill reference file was involved. If so, the hook inspects the event and forwards a low-cardinality usage event to the hidden `aspire agent telemetry` command. The command records the event through the same CLI telemetry pipeline. Tool uses that don't involve Aspire skills or tools are ignored. See [AI agent skill usage data](#ai-agent-skill-usage-data) for exactly what's recorded. ## How to opt-out @@ -66,7 +66,7 @@ The agent telemetry hook installed by `aspire agent init` reports a single event - `tool_invocation` — an Aspire MCP tool was called. - `reference_file_read` — a reference file bundled alongside an Aspire skill was read. -Each event records only the following low-cardinality, Aspire-owned values: +Each event records only a subset of the following low-cardinality, Aspire-owned values (depending on the event type): | Field | Description | |-------|-------------|