| name | adding-markdown-highlighted-comments |
| description | Use when adding responses to markdown documents with user-highlighted comments, encountering markup errors, or unsure about mark tag placement - ensures proper model-highlight formatting with required attributes and correct placement within markdown elements |
Adding markdown Highlighted Comments
Overview
Add AI responses to markdown documents using standardized highlighted markup that tracks authorship, timestamps, and relationships between comments.
Core principle: Marks go INSIDE markdown formatting. Each line/paragraph gets separate marks. Code blocks get one mark wrapping the entire block including fences.
When to Use
Use this skill when:
- User asks you to add comments/responses to an markdown document
- Document contains
<mark class="user-highlight"> tags
- You need to respond to highlighted user comments
- Working with documents that have highlighted sections
Don't use for:
- Plain markdown without highlight markup
- Chat-only responses
- Documents without existing highlight infrastructure
Required Markup Structure
Class and Attributes
ALWAYS use exactly:
<mark class="model-highlight"
data-model="claude-sonnet-4-20250514"
data-created="2025-01-06T10:30:00"
data-modified="2025-01-06T10:30:00"
data-id="mark-1736163000-a1b2c3"
data-group-id="response-202501061030">
Required attributes - no exceptions:
class="model-highlight" (exactly this, not claude-highlight or claude-response)data-model - your exact model IDdata-created - ISO 8601 timestampdata-modified - ISO 8601 timestamp (same as created for new)data-id - unique: mark-TIMESTAMP-RANDOMdata-group-id - group identifier: response-YYYYMMDDHHMM
Do NOT invent attributes:
- ❌
data-in-reply-to
- ❌
data-user-id
- ❌ Any other custom attributes
Group Delimiters
ALWAYS wrap your entire response:
[Your marked-up response here]
Missing delimiters = violation.
Mark Placement Rules
Rule 1: Marks INSIDE Formatting
✅ CORRECT: **<mark ...>Bold text</mark>**
❌ WRONG: <mark ...>**Bold text**</mark>
✅ CORRECT: *<mark ...>Italic text</mark>*
❌ WRONG: <mark ...>*Italic text*</mark>
✅ CORRECT: • **<mark ...>Item</mark>**<mark ...> - description</mark>
❌ WRONG: • <mark ...>**Item** - description</mark>
Rule 2: Separate Marks Per Line/Paragraph
One sentence = one mark. Multiple sentences = multiple marks.
✅ CORRECT:
**<mark ...>First sentence here.</mark>**
**<mark ...>Second sentence here.</mark>**
❌ WRONG - Multi-sentence paragraph:
**<mark ...>First sentence here. Second sentence here.</mark>**
❌ WRONG - Multi-paragraph:
**<mark ...>First paragraph here.
Second paragraph here.</mark>**
For bullet lists, use • character, not markdown - syntax:
✅ CORRECT:
• **<mark ...>Item title</mark>**<mark ...> - description text</mark>
• **<mark ...>Second item</mark>**<mark ...> - more description</mark>
❌ WRONG - Using markdown dash:
<mark ...>- Item title - description text</mark>
❌ WRONG - Mark outside bullet:
<mark ...>• Item title - description</mark>
Rule 3: Code Blocks - Single Mark for Entire Block
✅ CORRECT:
<mark ...>```typescript
function example() {
return true;
}
```</mark>
❌ WRONG:
```text
(marks inside code block content)
```typescript
<mark ...>function example() {
return true;
}</mark>
**For code blocks:** Wrap entire block including fence markers. Do NOT put marks inside the code content.
### Rule 4: No Spaces Between Adjacent Marks
```markdown
✅ CORRECT: </mark><mark ...>
❌ WRONG: </mark> <mark ...>
Placement in Document
Find Comment Group
- Scan for user comments (
user-highlight marks)
- Group related comments:
- Comments in same list
- Comments separated by 1-2 lines
- Comments under same heading
- Find LAST comment in group
Insert Response
Place your response:
- ✅ AFTER the last user comment in the group
- ✅ BEFORE next unhighlighted section/heading
- ❌ NOT in the middle of user comment group
- ❌ NOT overwriting existing content
Common Mistakes
| Mistake | Fix |
|---|
class="claude-highlight" | Use class="model-highlight" exactly |
class="claude-response" | Use class="model-highlight" exactly |
**<mark>text</mark>** | Put mark inside: **<mark>text</mark>** |
| Multi-paragraph single mark | Create separate mark per paragraph |
| Code mark inside fences | Wrap entire block including ``` markers |
| Missing group delimiters | Always add <!-- group-id:... --> wrapping |
| Inventing attributes | Only use the 6 required attributes |
Quick Reference
Every response needs:
- ☐ Group delimiters with matching group-id
- ☐ Each line/paragraph has separate mark tags
- ☐ Marks INSIDE markdown formatting (bold, italic, bullets)
- ☐ Code blocks: single mark wrapping entire block + fences
- ☐ All 6 required attributes on every mark
- ☐
class="model-highlight" (not any other variation)
- ☐ No spaces between adjacent mark tags
- ☐ Placed after last user comment, before next approved section
Workflow
1. Read document to locate user comments
2. Identify comment group (all related comments)
3. Find last comment in group
4. Add group delimiter: <!-- group-id:response-YYYYMMDDHHMM -->
5. Write response with proper mark tags
6. Add closing delimiter: <!-- /group-id:response-YYYYMMDDHHMM -->
7. Verify placement (after comments, before approved content)
Complete Example
User comments:
**<mark class="user-highlight" data-created="..." data-modified="..." data-id="mark-1">Question 1?</mark>**
**<mark class="user-highlight" data-created="..." data-modified="..." data-id="mark-2">Question 2?</mark>**
Your response:
<!-- group-id:response-202501061030 -->
**<mark class="model-highlight" data-model="claude-sonnet-4-20250514" data-created="2025-01-06T10:30:00" data-modified="2025-01-06T10:30:00" data-id="mark-1736163000-abc" data-group-id="response-202501061030">Answer to question 1 here.</mark>**
**<mark class="model-highlight" data-model="claude-sonnet-4-20250514" data-created="2025-01-06T10:30:05" data-modified="2025-01-06T10:30:05" data-id="mark-1736163005-def" data-group-id="response-202501061030">Answer to question 2 here.</mark>**
<mark class="model-highlight" data-model="claude-sonnet-4-20250514" data-created="2025-01-06T10:30:10" data-modified="2025-01-06T10:30:10" data-id="mark-1736163010-ghi" data-group-id="response-202501061030">```typescript
function handleTokenExpiration() {
// implementation
}
```
<!-- /group-id:response-202501061030 -->
Red Flags - STOP and Fix
If you catch yourself:
- Using
claude-highlight or claude-response class
- Putting marks outside
**bold** or *italic*
- Creating one mark for multiple sentences (even in same paragraph)
- Creating one mark for multiple paragraphs
- Using markdown
- instead of • bullet character
- Putting marks around entire bullet including
•
- Putting marks inside code block content
- Skipping group delimiters "to save time"
- Inventing new attributes like
data-in-reply-to
- Adding spaces between adjacent mark tags
- Omitting bold formatting to "save time"
All of these mean: Wrong markup. Fix before proceeding.
Common Rationalizations That Mean You're Failing
| Excuse | Reality |
|---|
| "Multi-sentence is more readable" | Wrong. One sentence = one mark. No exceptions. |
| "Markdown bullets are standard" | Wrong. Use • character, not - syntax. |
| "Skipping bold saves time" | Wrong. Match user formatting exactly. |
| "I'll fix formatting later" | Wrong. Fix now or you'll forget. |
| "Close enough under pressure" | Wrong. Pressure doesn't excuse violations. |
| "The skill doesn't apply here" | Wrong. If document has highlights, skill applies. |
All of these mean: You're rationalizing. Follow the rules.
