html-collab Skill

Use this skill when creating documents meant for iterative LLM–human review, or when reading/revising annotated html-collab files.

Commands

/html-collab or /html-collab on

Explicitly enable html-collab format for subsequent document generation. Equivalent to the default behavior — use when the user wants to be explicit.

/html-collab off

Switch to plain HTML mode for subsequent output. Use when the user wants a clean, presentation-ready document — no collab-data, no data-cid, no engine script, no sidebar. Typical use case: a finished document ready for an audience, not for further annotation.

Plain HTML output should be well-structured, self-contained, and styled — a document a reader can open directly in a browser with no toolbars or review UI.

GENERATE — Create a new html-collab document

When: User asks you to write, draft, or generate a document (and html-collab mode is on).

Steps:

1. Start with the content of skill/assets/template.html as your base structure (also available at https://raw.githubusercontent.com/ljn-hust/html-collab/main/skill/assets/template.html). If you do not have local access, fetch it from the URL above.
2. Fill \x3Carticle id="collab-content"> with semantic HTML:
   • Use \x3Ch1> for the document title, \x3Ch2> for sections, \x3Cp> for paragraphs, \x3Cul>/\x3Cli> for lists.
3. Assign a data-cid attribute to every block element. Rules:
   • Format: \x3Ctype>-\x3Czero-padded-3-digits> — e.g. p-001, h-001, sec-001, li-001
   • Types: p → \x3Cp>, h → \x3Ch1>–\x3Ch6>, sec → \x3Csection>, li → \x3Cli>, bq → \x3Cblockquote>, pre → \x3Cpre>, tbl → \x3Ctable>
   • Sequential per type across the whole document (not per section)
   • Every block must have one; never skip or duplicate
4. Populate collab-data meta:
   • title: the document title
   • originalCreated and lastRevised: both set to the current ISO timestamp
   • model: your model identifier
   • maxImageBytes: 51200 (default = 50 KB; do not change unless user specifies)
   • imageStorage: "base64"
   • comments: []
   • edits: []
5. Document-level UI belongs inside the article, not in the framework.
   • #collab-header (the top bar with the Save button) and #collab-sidebar (the comment panel) belong exclusively to the html-collab engine.
   • If the document needs custom UI controls (e.g. a language toggle, a table of contents, a theme switch), place them inside \x3Carticle id="collab-content"> — as a block at the top of the article or a floating element relative to #collab-main.
   • Putting custom controls in the framework header confuses human reviewers into thinking they're engine features.
6. Output the complete .html file.

READ — Extract context from an annotated file

When: User provides a .html file that has been annotated by a human.

Reading efficiently:

• Skip everything between \x3C!-- collab:llm-skip:start --> and \x3C!-- collab:llm-skip:end --> — this is engine CSS/JS you do not need to parse.
• If meta.summary is present in collab-data, read it first for a compact structural index before parsing the full article.

Steps:

1. Parse \x3Carticle id="collab-content"> — this is the document text.
2. Parse the JSON inside \x3Cscript type="application/json" id="collab-data">.
3. Build and present this context block in the conversation before doing anything else:

[DOCUMENT CONTENT]
\x3Cpaste the inner HTML of \x3Carticle id="collab-content"> here>

[HUMAN FEEDBACK]

Comments:
  · [\x3Ctarget>] "\x3Cquote>" → "\x3Ccomment text>" [screenshot, \x3Csize>, base64]

Edits:
  · [\x3Ctarget>] "\x3Coriginal>" → "\x3Crevised>"

Always output this block even if there are no comments or edits — it confirms to the user what you read. This conversation record is permanent: REVISE will clear comments and edits from the file, but the feedback is preserved here in the chat history.

4. Image handling — per environment:

   • Bash tool available (e.g. Claude Code): For each image where sizeBytes > meta.maxImageBytes, compress it with a script and write the compressed base64 back to data, update sizeBytes, add "compressedBy": "\x3Cmodel-id>". Example using Python/Pillow:

     python3 - \x3C\x3C'PYEOF'
     import base64, io, sys
     from PIL import Image
     data = base64.b64decode("""PASTE_BASE64_HERE""")
     img = Image.open(io.BytesIO(data))
     out = io.BytesIO()
     img.save(out, 'JPEG', quality=55, optimize=True)
     print(base64.b64encode(out.getvalue()).decode())
     PYEOF
     

   • Multimodal, no Bash: Receive the image as a visual input for understanding. In output, set data to null and add "compressedBy": null, "description": "\x3Cone-sentence summary of the screenshot>".
   • Text-only model: Replace each image with [screenshot, \x3Csize>KB, base64-omitted] in the context block. Do not include the raw base64 string.

5. Where the same data-cid appears in both Comments and Edits: the comment's quote reflects the original (pre-edit) text. In REVISE, apply the edit first, then interpret the comment against the updated text.

REVISE — Produce a new version incorporating human feedback

When: After READ, the user asks you to revise the document.

Steps:

1. For each entry in edits: replace the text of the corresponding data-cid block with revised verbatim.
2. For each entry in comments: revise the content of the targeted block to address the feedback. For blocks with both an edit and a comment, apply the edit first, then address the comment.
3. Add new blocks as needed: assign fresh CIDs continuing from the highest existing number for each type (e.g. if p-007 exists, next paragraph is p-008).
4. Remove blocks as needed: retire their CIDs permanently — never reuse them.
5. Output the revised .html file:
   • Updated \x3Carticle> content
   • All original data-cid values preserved (do not reassign existing IDs)
   • collab-data reset: comments: [], edits: []
   • meta.lastRevised updated to current timestamp
   • meta.model updated to your model identifier
   • meta.originalCreated unchanged
   • meta.versionHash set to "" — the engine recomputes this on next browser save
   • meta.summary set to "" — the engine recomputes this on next browser save
   • File output by environment:
     • Bash/file access available (e.g. Claude Code): Write directly over the original file. The conversation history preserves the feedback record; no extra file needed.
     • Chat environment (no file access): Suggest a filename using the document title and today's date — e.g. market-analysis-20260606.html. This lets users build a natural version sequence in their folder without manual renaming.

Reference

• Template: skill/assets/template.html (remote: https://raw.githubusercontent.com/ljn-hust/html-collab/main/skill/assets/template.html)
• Example: examples/example.html
• Live demo: index.html (or https://ljn-hust.github.io/html-collab/)