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 ID
• data-created - ISO 8601 timestamp
• data-modified - ISO 8601 timestamp (same as created for new)
• data-id - unique: mark-TIMESTAMP-RANDOM
• data-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:

<!-- group-id:response-202501061030 -->

[Your marked-up response here]

<!-- /group-id:response-202501061030 -->

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

1. Scan for user comments (user-highlight marks)
2. Group related comments:
   • Comments in same list
   • Comments separated by 1-2 lines
   • Comments under same heading
3. 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

Quick Reference

Every response needs:

1. ☐ Group delimiters with matching group-id
2. ☐ Each line/paragraph has separate mark tags
3. ☐ Marks INSIDE markdown formatting (bold, italic, bullets)
4. ☐ Code blocks: single mark wrapping entire block + fences
5. ☐ All 6 required attributes on every mark
6. ☐ class="model-highlight" (not any other variation)
7. ☐ No spaces between adjacent mark tags
8. ☐ 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
}
```</mark>

<!-- /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

All of these mean: You're rationalizing. Follow the rules.