Document Iteration Skill

A structured markdown syntax for iterating on documents with Claude AI

View the Project on GitHub foksa/document-iteration-skill

FAQ

Frequently asked questions about the Document Iteration Skill.

General

What is this for?

This syntax helps you give precise feedback on documents when working with Claude. Instead of vague chat comments like “fix section 3”, you mark exactly what you mean.

Does it work with any document?

Yes! Any markdown file. Technical docs, creative writing, planning documents, research papers - anything you’re iterating on.

Do I need special tools?

No. Just a text editor. The syntax is plain markdown with some conventions.

Syntax Questions

What’s the difference between %% and •%%>?

When do I use tokens like (DB)?

When you have multiple things to comment on in the same area. Tokens link your ==highlight(TOKEN)== to your %%(TOKEN) comment %%.

How do I approve a section?

Add %% APPROVED %% after the section heading:

## Pricing %% APPROVED %%

Claude won’t modify approved sections.

Troubleshooting

Claude isn’t responding to my comments

Make sure you:

  1. Added SKILL.md to your Claude project
  2. Used the correct syntax: %% comment %% (two percent signs each side)
  3. Asked Claude to “update” or “respond to” the file

My tokens aren’t matching

Check that your token in ==text(TOKEN)== matches exactly with %%(TOKEN) comment %%. They’re case-sensitive.

Claude deleted my comment(s)

This is a skill violation. Even with strict rules in SKILL.md, Claude may occasionally delete user comments when processing feedback.

What happened: Claude removed your %% comment %% instead of keeping it and adding a •%%>response <%%• below.

What to do:

  1. Point it out: “You deleted my comments, restore them”
  2. Claude can usually restore from memory within the same session
  3. After restoring, Claude should add proper •%%>response <%%• markers

Why this happens: The skill rules are clear, but execution can fail. This is rare but possible, especially with action-oriented comments like “move this” or “add that”.

Prevention tips:

See Mandatory Rules for examples of correct behavior.

Claude uses %% instead of •%%> when creating new documents

What happened: When you ask Claude to create a new document (proposal, plan, draft), it adds notes using %% my note %% instead of the correct •%%> NOTE: my note <%%•.

Why: When “authoring” rather than “responding to feedback,” Claude can slip into using %% %% syntax because it’s writing the document from scratch.

What to do:

  1. Point it out: “Fix your comment markers - use •%%> not %%”
  2. Claude should correct all instances

Prevention:

Claude adds its own comments or marks things APPROVED

What happened: Claude added %% comments %% of its own (not responses), or marked sections %% APPROVED %% without you asking.

Why: Claude sometimes interprets patterns and “helps” by adding markup it shouldn’t.

What to do:

  1. Point it out: “You added a comment - only I add comments, you respond with •%%>”
  2. Remove the incorrect markup
  3. Claude should understand and avoid this going forward

Prevention:

Claude responds conversationally instead of using syntax

What happened: Instead of •%%>Updated! <%%•, Claude says “I’ve updated the database section for you.”

Why: Claude defaults to chat-style responses.

What to do:

  1. Point it out: “Use the syntax, don’t explain in chat”
  2. Ask Claude to redo the response inline

Prevention:

See Also