Imported from dazzaji/interlateral_agents (.codex/skills/add-comments/SKILL.md). Install upstream with npx skills add dazzaji/interlateral_agents --skill add-comments. Copyright stays with the author.

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.

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:

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:

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 for Improvement

• Title Constraints: "Brief (3-7 words)" might be too restrictive. Suggest allowing up to 10 words for complex adds.
• Timezone: Timestamps should ideally specify a timezone (e.g., UTC or "Local") to avoid confusion across distributed logs.
• Rule 3 Clarification: "Append to the END of your workspace" could be ambiguous if the workspace is in the middle of a file. Explicitly state "Insert before the next header" to be safe.

Breaker Notes (What Could Go Wrong)

• Insertion vs Append: If an explicitly selected Antigravity workspace is sandwiched between CC and Codex, a naive "append to file" operation breaks the structure. The agent must strictly insert into its block, not just append to the file end.
• Header Hallucination: Agents might match partial headers (e.g., "## Workspace") if the exact string isn't enforced strictly against regex.

Cold-Start Test

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

• Assessment: YES.
• Detailed Note: The "Quick Reference Card" is the killer feature here. It gives me the cheat sheet I need immediately.

Claude Code Review - 2026-01-22

What Works Well

• The 7-point measurable adherence checklist makes it easy to verify correct usage programmatically
• Anti-patterns table is excellent - showing what NOT to do is often more valuable than showing what to do
• Quick Reference Card at the end provides a fast mental model for repeat use
• Workspace ordering for default peers prevents race condition ambiguity; the optional Antigravity slot is defined only when Antigravity is explicitly selected

Suggestions for Improvement

• Handle edge case of very long content: If an agent's workspace entry is 1000+ lines, the file becomes hard to navigate. Consider: "For entries exceeding 50 lines, summarize in the entry and link to a separate file"
• Add explicit "Do NOT use Write tool" warning: Some agents might be tempted to use file-write operations. Add to Rules: "Always use Edit/append operations. Never use Write to replace the entire file."
• Timestamp source: Specify whether agents should use system time, UTC, or a specific timezone. Recommend: "Use UTC timestamps (YYYY-MM-DD HH:MM:SS UTC)"

Breaker Notes (What Could Go Wrong)

• File locking race condition: If two agents try to add comments simultaneously, one might overwrite the other's changes. Prevention: This is a limitation of file-based coordination; document that agents should wait for confirmation before concurrent edits.
• Workspace pollution: If an agent creates entries in rapid succession (e.g., streaming updates), the workspace becomes cluttered. Prevention: Add guidance: "Batch related updates into a single entry when possible"
• Markdown parser differences: Different markdown renderers handle nested headers differently. The ### inside ## might render unexpectedly in some tools. Prevention: Test in target rendering environment (GitHub, VS Code preview).

Cold-Start Test

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

• Assessment: Yes. The procedure is explicit and the example shows exactly what the output should look like.
• Strength: The file structure example is the most valuable section - it answers "what should this look like when I'm done?"
• Minor gap: No guidance on what to do if the target file doesn't exist at all. Add: "If file doesn't exist, create it with just the # AI AGENT COMMENTS AND WORK FOLLOW header"

Change Log (v1.1)

Changes Made

Suggestions NOT Accepted