fix(cli): print the skills staleness notice on stdout under --format markdown

[wmadden-electric]

--format markdown (added in #260, cli-engine 0.4.0) makes one promise: everything the run produces — blocks, next actions, diagnostics, structured errors, help, --version, live events — lands on stdout, and nothing is written to stderr, so an agent reads a single stream.

The skills staleness notice did not honour it. packages/cli/src/skills-check.ts always wrote to runtime.stderr, and its suppression list (--json, --quiet, -q, --version, --format json, --format=json) never mentioned markdown, so under markdown the notice landed on the stream the format promises is empty.

The notice is kept — agents are exactly its audience. Under --format markdown or --format=markdown it is now written to stdout as a trailing section, after the command's own document, in the heading-then-bullet shape the engine uses for ### Diagnostics:

### Notice
Prisma agent skills are out of date (installed @prisma/orm-postgres 8.1.0, synced 8.0.0).
- Sync agent skills: `prisma skills sync`

The leading blank line is the one-blank-line separator between sections that joinSections in packages/cli-engine/src/execution/markdown.ts uses. Under every other format the behaviour is unchanged: the same one-line notice on stderr, and the same silence under --json, --quiet, -q, --version, --format json, CI, PRISMA_SKILLS_CHECK=0, the persisted opt-out, and the skills/init commands.

Argv detection for markdown reuses the same helper the json check now calls, so --format=markdown and --format markdown are both recognised, and both are ignored after a bare --.

Tests in packages/cli/tests/skills-check.test.ts cover: the notice on stdout with nothing on stderr for both spellings, a never-synced project, silence on both streams when the copies are current, an unchanged exit code on a failing command, --format human staying on stderr, and a markdown format after a bare -- staying on stderr. The existing off-switch cases now also assert stdout is empty.

docs/product/output-conventions.md is updated in both places that state the rule: the "Out-Of-Date Agent Skills" section and the --format markdown section. docs/product/cli-style-guide.md does not mention the notice, so it needed no change.

Fixes #267

Commands run

Command	Result
pnpm --filter @prisma/cli test	61 test files passed, 971 tests passed, 2 skipped
pnpm typecheck	9/9 tasks successful
pnpm lint	458 files checked, no findings

e2e and conformance were not run.

🤖 Generated with Claude Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 2f75d757-35fe-4420-a2e6-555ea188ff75

📥 Commits

Reviewing files that changed from the base of the PR and between 38e4ab3 and 8febcec.

📒 Files selected for processing (4)

• docs/product/output-conventions.md
• packages/cli/src/main.ts
• packages/cli/src/skills-check.ts
• packages/cli/tests/skills-check.test.ts

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

Summary by CodeRabbit

• New Features
  • Markdown-formatted command output now includes an appended ### Notice section when agent skills are out of date.
  • The notice includes guidance to run the skills synchronization command.
• Bug Fixes
  • Notices remain on stderr for non-Markdown formats, keeping standard output clean.
  • Markdown notices are omitted when skills are current.
  • Format flags appearing after -- no longer affect notice routing.

Walkthrough

The skills staleness notice now uses stdout as a trailing ### Notice section for --format markdown and --format=markdown. Other formats continue to write the plain-text notice to stderr. The CLI runtime supplies stdout to the skills check. Tests cover output streams, format parsing, exit codes, synced projects, and disabled checks. Documentation defines the updated output contract.

Priority: ➖ Normal

Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to 8febc

No concrete merge-blocking issue is established by the available evidence.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The implementation meets the main behavior in issue #267. It detects --format markdown and --format=markdown, ignores arguments after --, writes a trailing ### Notice section to stdout, and ke…	Update apps/docs/content/docs/cli/skills.mdx in the staleness-check section. Document that Markdown output writes the notice to a trailing ### Notice section on stdout, that other formats use stderr, and that the existing suppression fl…
Docstring Coverage	⚠️ Warning	Docstring coverage is 63.64% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 3 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: printing the skills staleness notice to stdout when markdown format is active.
Description check	✅ Passed	The description is directly related to the changeset. It explains the markdown output behavior, preserved suppression rules, tests, documentation updates, and validation results.
Out of Scope Changes check	✅ Passed	The changed CLI wiring, notice rendering, tests, and output documentation directly support issue #267. The supplied summary shows no unrelated product or behavior changes.

Full details: Linked Issues check

Explanation

The implementation meets the main behavior in issue #267. It detects --format markdown and --format=markdown, ignores arguments after --, writes a trailing ### Notice section to stdout, and keeps stderr empty for Markdown output. Other formats and suppression flags retain their behavior. Tests cover these cases. The supplied change summary lists an update to docs/product/output-conventions.md, but it does not list the issue-named skills documentation page, apps/docs/content/docs/cli/skills.mdx, which must describe the updated suppression and output behavior.

Resolution

Update apps/docs/content/docs/cli/skills.mdx in the staleness-check section. Document that Markdown output writes the notice to a trailing ### Notice section on stdout, that other formats use stderr, and that the existing suppression flags remain effective.

Full details: Docstring Coverage

Explanation

Docstring coverage is 63.64% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 3 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/skills-notice-markdown

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch fix/skills-notice-markdown

Warning

Git: CodeRabbit could not clone the repository, so clone-backed analysis was skipped and this review may be incomplete. Verify repository clone access, such as SSH credentials, before requesting another full review. If clone access is intentionally unavailable, use path_filters to narrow the review scope.

---

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

npx https://pkg.pr.new/@prisma/cli@272

npx https://pkg.pr.new/@prisma/cli-engine@272

commit: 8febcec