docs(writing-skills): add character-safety guidance for inline exclamation parsing

[stablegenius49]

Summary

• add a new "Character Safety Gotcha" section to skills/writing-skills/SKILL.md
• document that exclamation marks inside single-backtick inline code spans can break skill loading in Claude Code
• add practical workarounds and links to upstream bug reports

Verification

• bash tests/opencode/test-skills-core.sh
• inline safety check: no single-backtick inline code spans in skills/writing-skills/SKILL.md contain exclamation marks

Closes #451

[coderabbitai]

📝 Walkthrough

Walkthrough

Added a "Character Safety Gotcha (Claude Code parser bug)" subsection to the writing-skills guide documenting that exclamation marks in inline code spans cause parser failures. Includes three workarounds and references to related open issues.

Changes

Cohort / File(s)	Summary
Documentation Addition skills/writing-skills/SKILL.md	Added new subsection warning against using ! characters in inline code spans (backticks), which trigger Claude Code parser errors. Provides workarounds: spelling out operators in prose, using fenced code blocks, and avoiding ! adjacent to backticks. Includes references to known issues.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Poem

🐰 A warning for writers in the burrow so deep,
Exclaim marks in backticks will make parsers weep!
Use fenced code blocks, spell prose with care,
And your skills will load safely in Claude's cool air! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: adding character-safety guidance for inline exclamation mark parsing issues in writing-skills documentation.
Description check	✅ Passed	The description is directly related to the changeset, clearly explaining the new 'Character Safety Gotcha' section, the parsing bug it documents, workarounds, and verification steps performed.
Linked Issues check	✅ Passed	The PR fully addresses the coding-related requirements from issue #451: documenting the exclamation-mark parsing bug, providing workarounds, and including links to upstream issues.
Out of Scope Changes check	✅ Passed	All changes are scoped to the stated objective: adding documentation guidance about character safety in inline code spans; no unrelated modifications are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

🧹 Nitpick comments (1)

skills/writing-skills/SKILL.md (1)

353-354: Consider clarifying why spelled-out text in backticks is safe.

The first workaround demonstrates exclamation-equals in backticks, which might momentarily confuse readers who just read "Never put exclamation marks inside single-backtick inline code spans." While the distinction is clear to careful readers (spelled-out text contains no ! character), making this explicit would prevent any misunderstanding.

✨ Proposed clarity improvement

 Workarounds:
-- Spell operators out in prose (`exclamation-equals`, `exclamation-tilde`) instead of writing symbols inline
+- Spell operators out in prose (e.g., `exclamation-equals`, `exclamation-tilde`) instead of using the actual `!` character in backticks
 - Put exact syntax in fenced code blocks when needed

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@skills/writing-skills/SKILL.md` around lines 353 - 354, Add a short
clarifying sentence after the workaround that explains why spelled-out operators
in single-backtick inline code (e.g., `exclamation-equals`, `exclamation-tilde`)
are safe: explicitly state that the spelled-out text contains no literal `!`
character so it does not trigger the warning "Never put exclamation marks inside
single-backtick inline code spans." Update the line listing the workarounds to
include this brief note so readers immediately understand the distinction.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@skills/writing-skills/SKILL.md`:
- Around line 353-354: Add a short clarifying sentence after the workaround that
explains why spelled-out operators in single-backtick inline code (e.g.,
`exclamation-equals`, `exclamation-tilde`) are safe: explicitly state that the
spelled-out text contains no literal `!` character so it does not trigger the
warning "Never put exclamation marks inside single-backtick inline code spans."
Update the line listing the workarounds to include this brief note so readers
immediately understand the distinction.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 5d24e7ad-2197-4828-8825-ad99264f1ee9

📥 Commits

Reviewing files that changed from the base of the PR and between e4a2375 and 7e6071c.

📒 Files selected for processing (1)

• skills/writing-skills/SKILL.md