fix(skill): split output rules + fix blank-reply bug for plain-text tools

[grlee]

Problem

The CRITICAL OUTPUT RULES section in skills/buddy/SKILL.md treats every buddy tool result as ASCII art that must be echoed verbatim with no commentary. That's correct for some tools, but several buddy tools return plain text:

buddy_help, buddy_unmute, buddy_mute, buddy_frequency, buddy_style, buddy_statusline, buddy_list, buddy_rename, buddy_save, buddy_dismiss, buddy_set_personality

Combined with the end-of-turn <!-- buddy: ... --> HTML comment pattern, the verbatim-no-commentary rule produced replies whose only visible content was the HTML comment. Markdown renderers hide HTML comments by default, so calling /buddy help, /buddy mute, /buddy list, etc. could result in a blank-looking reply to the user.

Fix

Splits the rules into two buckets matching the actual tool response shapes:

• Visual-card outputs (strict verbatim) — buddy_show, buddy_stats, buddy_pet, buddy_achievements, buddy_react. Same rules as before: output exactly as returned, no commentary.
• Plain-text outputs (verbatim + visible) — the eleven plain-text tools listed above. Output the tool result verbatim inside the reply, with an optional one-sentence confirmation, so the user can actually see what happened. Explicitly warns against emitting a reply whose only visible content is the end-of-turn HTML comment.

The "name reactions" rule moves into its own subsection rather than being a trailing paragraph after the verbatim rules.

Bonus markdown fix

Adds blank lines around the fenced code blocks in the MCP-failure diagnostic section so the bash blocks render correctly inside their numbered list items. CommonMark renderers vary on whether blank lines are required around fences inside list items; adding them is the safe form.

Verification

• Pure docs change to a skill markdown file — no code, no tests, no runtime impact.
• The tool categorization was derived by reading server/index.ts and checking which server.tool(...) registrations return raw card markdown vs string templates.

Out of scope

• Whether to add a similar plain-text bucket to other skills in this repo (none identified yet).
• Rewriting the visual-card rules themselves.

[grlee]

Friendly heads-up: a user (me, in this case) just hit the blank-reply behavior live with /buddy help returning empty content to Claude in the rendered output. Happy to rebase, split further, or adjust framing if anything in this PR would land better differently — let me know what's most helpful.

[grlee]

Pushed an additional commit (81bb23e) that hardens the visibility rule based on a live regression I observed today.

What I saw: the original "verbatim + visible" wording held on the first one or two /buddy help calls in a session, but on the third repetition I (Claude) implicitly treated the result as "already shown" and emitted a reply containing only the <!-- buddy: ... --> end-of-turn comment — i.e., the exact silent-failure mode the rule was meant to prevent.

What the new commit changes:

• Explicit "every time, every call, even on repeated calls in the same session" language to defeat the "they've seen it" inference
• Reframes HTML-comment-only reply as a hard floor (broken send) rather than a guideline
• Adds a pre-send self-check: "does your visible reply contain the tool's result text? If no, paste it in"

After applying and reloading, three consecutive /buddy help calls all rendered cleanly. Not a long sample, but the change is small and the failure mode is well-defined, so I think it's worth landing.

Happy to drop the new commit / squash / rebase / split into its own PR if any of that lands better — let me know.

[ramarivera]

Hey @grlee — thanks for the patience here, and for the live-regression follow-up commit. Yes please: a rebase onto current main would be great. Heads up that main moved quite a bit recently (project renamed to Coding Buddy, native Pi / Oh My Pi extensions added, npm publishing wired up), which is what put this PR into conflict — the skills/buddy/SKILL.md you're touching was part of that churn.

The blank-reply fix and the hardened visibility rule both look worth landing. Once it's rebased and green we'll get it reviewed promptly.

🤖 This content was generated with AI assistance using Claude Fable 5.