#120

fix(docs): skill describes the media MCP profile as additive

Opencoygeekopened 9d ago

Summary

The official agent skill says the media profile "adds" the video and audio tools after listing the four core tools. This can be read as retaining the core tools when selecting --profile media, but that profile exposes only the four media tools. The authored MCP documentation and runtime agree on separate profile sets. Please make the skill's profile-selection wording reflect that contract.

Steps to reproduce

  1. Read the MCP paragraph under Commands in skills/ai-cli/SKILL.md at the release baseline below. It lists text, image, decide, and models, followed by: "The media profile adds video_start, video_status, audio_speak, and audio_transcribe."
  2. Start ai mcp --profile media and send these newline-delimited JSON-RPC messages on stdin:
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"profile-probe","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
  1. Repeat the same exchange with --profile core and --profile all. Compare the names returned by tools/list with the skill's additive wording.

Expected behavior

The skill should distinguish the separate core and media tool sets and identify all as their union, consistent with the authored MCP documentation. A reader who needs core tools together with video and audio should be able to select the combined profile from the skill's guidance.

Actual behavior

The skill uses additive wording without mentioning the combined profile in that paragraph. The executed release probes returned these tool names:

core:  text, image, decide, models
media: video_start, video_status, audio_speak, audio_transcribe
all:   text, image, decide, models, video_start, video_status, audio_speak, audio_transcribe

Each server initialized as ai with protocol 2025-11-25, exited 0 after stdin closed, and emitted no stderr. The MCP paragraph and profile implementation remain unchanged on the inspected default branch. This is a wording discrepancy; no user choosing the wrong profile or failed generation is claimed.

Runtime or environment

  • Executed release: ai-cli 0.8.0, the latest stable release in both npm metadata and GitHub Releases when checked; release source bd9d87a8ead2ff247b669fc6d4bcac90e8d96353.
  • Inspected default branch: main at 20592fdd6deb68e09856f675a54e685b05b02226; its package version is 0.8.1, which was not the latest published stable release. No source build was executed.
  • Environment: Node.js v26.12.1, macOS arm64. Each probe ran with an isolated temporary HOME and working directory and an environment containing only HOME, PATH, and NO_COLOR. No credentials, provider requests, or tool calls were used.

Evidence

  • Expected source: Authored MCP profile documentation explicitly defines four media tools and eight tools in all.
  • Failure source: Official agent skill MCP paragraph uses "adds" after listing the core tools; the observed tools/list names above establish the different runtime sets.
  • Evidence provenance: observed
  • Local verification: reproduced
  • Reproduction completeness: complete

The primary evidence is the observed runtime profile lists and direct reading of the skill and authored documentation. Source inspection separately confirms default-branch persistence.

Profile construction populates independent core and media arrays and places every tool in all.

Restoration check

Read the revised skill's MCP guidance and compare it with the same three tools/list exchanges. The guidance should make clear that selecting media exposes the four media tools, while selecting all exposes both groups. The existing runtime lists can remain unchanged.

Additional context

Use ai mcp --profile all when both groups are needed; the isolated listing probe verified all eight names. That observation establishes tool discovery, not successful generation or provider dispatch.

Co-contributor credit

No, do not credit me.

Checklist

  • I have searched existing issues for duplicates.
  • I have removed API keys, tokens, credentials, and private data from this report.

Triage assessment

  • Impact level: P3
  • Assessment status: supported
  • Impact basis: The supported defect is ambiguous profile-selection wording. No downstream workflow failure or actual incorrect user selection was observed, and the runtime agrees with the explicit MCP documentation.
  • Workaround status: available
  • Workaround basis: The authored documentation defines the profile sets explicitly, and the executed all listing exposes all eight tools without changing settings or source.

Activity

0

No activity yet.