From 6bd56ec264e7389540711b0baab940a5b23272bf 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/2] 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 48c954dbd..5bfbce8ad 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.
@@ -49,6 +80,29 @@ Aspire CLI collects the following data:
| 13.2 | CLI launch. | Includes command name and exit code. Option and argument values are not sent to Microsoft. |
| 13.2 | Ensure .NET SDK install. | Includes .NET SDK version installed. |
| 13.2 | CLI-related unhandled exceptions. | — |
+| 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 2d7d40b00fe0dab60ead08a515cc243bc5fbb199 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/2] 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 5bfbce8ad..9bace1375 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.
@@ -102,7 +77,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