add-comments

Add Comments Skill

Purpose

Safely add your work to a shared file without overwriting or interfering with other agents' work. Each agent has an isolated workspace section.

Default peer policy: the Antigravity workspace exists only for an explicitly selected Antigravity peer. Do not recruit or assume Antigravity participation just because this skill reserves a workspace header for it.

When to Use

• When asked to "add comments" to a file
• When asked to "add your review" to a file
• When asked to "add work" or "add results" to a file
• When the adherence-check skill needs to deliver results

Critical Rules

Rule 1: Work ONLY in Your Workspace

Each agent has exactly ONE workspace section. You write ONLY there.

Agent	Workspace Header (EXACT match required)
Claude Code	## Claude Code Workspace
Codex	## Codex Workspace
Antigravity, only when explicitly selected	## Antigravity Workspace

Header matching: Use EXACT string match only. Do NOT match partial headers like "## Workspace" or "## CC Workspace".

Rule 2: Never Touch Other Workspaces

• Do NOT read other agent workspaces to "coordinate"
• Do NOT edit other agent workspaces
• Do NOT delete other agent workspaces
• Do NOT add content above or between other workspaces

Rule 3: Insert Into Your Workspace (Not File Append)

Critical distinction: "Append to your workspace" means INSERT your content at the end of YOUR workspace section, BEFORE the next ## header (or end of file). Do NOT blindly append to the end of the file—this breaks the structure if your workspace is in the middle.

Rule 4: Use Edit Operations Only

NEVER use Write/file-replace operations. Always use Edit/append/insert operations that preserve existing content. Using Write to replace the entire file will destroy other agents' work.

Procedure

Step 1: Open or Create the Target File

The file path will be given in your assignment (e.g., "add to projects/collector.md").

If the file does NOT exist:

1. Create it with just the main header: # AI AGENT COMMENTS AND WORK FOLLOW
2. Then add your workspace header and content

Step 2: Find the Main Header

Look for this EXACT header (search from bottom of file upward):

# AI AGENT COMMENTS AND WORK FOLLOW

If multiple main headers exist: Use the LAST one (closest to end of file).

If it does NOT exist: Add it at the very bottom of the file. For non-markdown files, add a blank line before the header to avoid gluing to prior content.

Step 3: Find or Create Your Workspace

Look for your EXACT workspace header under the main header.

If your workspace does NOT exist:

• Add it after any existing workspaces (preserve existing order)
• If no workspaces exist yet, use this default order: Claude Code first, Codex second
• If Antigravity was explicitly selected for this file, place ## Antigravity Workspace after Claude Code and before Codex when creating a new set of workspaces
• Do NOT reorder existing workspaces

EXACT header format required (copy from table in Rule 1).

Step 4: Add Your Content

INSERT your content at the END of your workspace section, BEFORE the next ## header.

Entry format:

### YYYY-MM-DD HH:MM:SS UTC - [Title up to 10 words]

[Your content here]

---

Format requirements:

• Timestamp MUST be UTC: YYYY-MM-DD HH:MM:SS UTC (e.g., 2026-01-22 14:30:00 UTC)
• Title: up to 10 words (be descriptive but concise)
• Content: any length, but if exceeding 50 lines, summarize and link to a separate file
• MUST end with --- separator on its own line

Batching: If you have multiple related updates, batch them into a single entry rather than creating many rapid entries.

Step 5: Verify Before Saving

Before finishing, confirm:

• Your content is INSIDE your workspace section (between your ## header and the next ## or EOF)
• Your content is AFTER any previous entries in your workspace
• You did NOT modify anything outside your workspace
• Timestamp is UTC format: YYYY-MM-DD HH:MM:SS UTC
• Entry ends with --- separator
• You used Edit/insert, NOT Write/replace

File Structure Example

Note: This is an EXAMPLE. Replace timestamps and content with your actual data.

# Project Documentation

[Original file content here...]

Some existing documentation that was already in the file.

# AI AGENT COMMENTS AND WORK FOLLOW

## Claude Code Workspace

### 2026-01-22 14:30:00 UTC - Code Review of parser.js

Found 3 issues in the parser:
1. Missing null check on line 45
2. Inefficient loop on lines 67-80
3. Hardcoded path on line 112

Suggested fixes provided inline.

---

### 2026-01-22 15:45:00 UTC - Follow-up Analysis

After reviewing the suggested changes, confirmed the null check fix
resolves the edge case failures in test suite.

## Codex Workspace

### 2026-01-22 14:40:00 UTC - Edge Case Analysis

Tested the following edge cases:
- Empty input: PASS
- Very large input (10MB): FAIL - memory spike
- Unicode characters: PASS
- Concurrent access: UNTESTED

---

Measurable Adherence Checklist

An agent ADHERED to this skill if ALL of the following are true:

#	Check	How to Verify
1	Main header exists	File contains EXACTLY # AI AGENT COMMENTS AND WORK FOLLOW
2	Workspace header correct	Agent's workspace header matches table EXACTLY (no partial matches)
3	Content is contained	All agent's content is between their ## header and the next ## header (or EOF)
4	Timestamp format correct	Each entry has ### YYYY-MM-DD HH:MM:SS UTC format
5	Separator present	Each entry ends with --- on its own line
6	No cross-contamination	Agent's content does not appear in other workspaces
7	Append-only	New content is after previous entries (not inserted above)
8	Edit operation used	File was modified via Edit/insert, not Write/replace

Adherence score: Count how many of the 8 checks pass. 8/8 = full adherence.

Anti-Patterns (Skill Violations)

These are WRONG - do not do these:

Anti-Pattern	Why It's Wrong
Adding content before # AI AGENT COMMENTS AND WORK FOLLOW	Violates structure; content may be overwritten
Using wrong workspace name (e.g., "CC Workspace")	Breaks parsing; other tools won't find it
Matching partial headers (e.g., "## Workspace")	Header hallucination; wrong workspace targeted
Adding content inside another agent's workspace	Cross-contamination; corrupts their work
Missing timestamp header	Cannot track when work was done
Missing --- separator	Cannot parse where entries end
Editing/deleting previous entries	Violates append-only rule; loses history
Using MM/DD/YYYY or non-UTC timestamps	Breaks timestamp parsing and timezone ambiguity
Using Write to replace entire file	Destroys other agents' work
Appending to file end when workspace is in middle	Breaks structure; content lands outside workspace
Copying example verbatim without replacing values	Creates invalid timestamps and placeholder content

Concurrency Warning

File locking is not guaranteed. If two agents try to add comments simultaneously, one might overwrite the other's changes.

Prevention: When working in a multi-agent context, wait for confirmation that the previous agent has finished before adding your comments. The coordination lead should sequence add-comments operations.

Quick Reference Card

1. Open target file (or create with just main header if new)
2. Find LAST "# AI AGENT COMMENTS AND WORK FOLLOW" header
3. Find your EXACT workspace header (## Claude Code Workspace / ## Codex Workspace; ## Antigravity Workspace only when explicitly selected)
4. If workspace missing: add after existing workspaces, don't reorder
5. INSERT (not append) your entry at END of your workspace, BEFORE next ##:
   ### YYYY-MM-DD HH:MM:SS UTC - Title (up to 10 words)
   [content]
   ---
6. Verify: in workspace, UTC timestamp, separator, used Edit not Write

Example Prompts That Invoke This Skill

"Add your code review to projects/reviews.md using the add-comments skill"

"Run the add-comments skill to add your analysis to docs/findings.md"

"Use add-comments to deliver your results to projects/conformance_results.md"

---

Agent Reviews

Codex Review - 2026-01-22

What Works Well

• Clear workspace rules and exact header names reduce ambiguity.
• Step-by-step procedure plus a realistic file example makes behavior testable.
• Measurable adherence checklist is concrete and easy to verify.

Suggestions for Improvement

• Clarify that if some workspaces already exist, do not reorder them; only add the missing workspace in place.
• Add a brief note for non-markdown files: insert a blank line before the main header to avoid gluing to prior content.

Breaker Notes (What Could Go Wrong)

• If the file already contains multiple "# AI AGENT COMMENTS AND WORK FOLLOW" headers, an agent may append to the wrong block.
• Agents might copy the example text verbatim and forget to replace timestamps, breaking parsing.

Cold-Start Test

"If I woke up cold and saw this skill, would I have what I need to do a good job?"

• Yes, the required headers and format are explicit and repeatable.
• Missing: guidance for handling duplicate main headers.
• Suggested addition: one sentence to pick the last/main header if duplicates exist.

---

Optional Antigravity Review - 2026-01-22

What Works Well

• Rules 1-3: The strict isolation rules are excellent for preventing merge conflicts in shared files.
• Adherence Checklist: The 7-point measurable list makes self-correction very easy.
• Anti-Patterns: This is a high-value section for avoiding common "dumb agent" mistakes like overwriting headers.

Suggestions f

---

Content truncated.