commentary

Adds attributed inline comments to Markdown documents using a structured marker syntax.

Updated Nov 21, 2025
One-click install
npx skills add https://github.com/alatyshau/duet --skill commentary-alatyshau
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: commentary
Source: https://github.com/alatyshau/duet/tree/main/packages/skills/modes/commentary
Command: npx skills add https://github.com/alatyshau/duet --skill commentary-alatyshau

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When humans and AI agents collaborate on Markdown documents, feedback often gets lost in chat history or overwrites the original text. This Skill defines a persistent, attributed comment syntax so discussions live directly inside the file with full traceability of who said what. ## Core Features & Use Cases - Structured Comment Syntax: Uses the ::: AUTHOR ::: marker inside list items, with nesting rules that define which lines belong to a comment. - Full AI Attribution: AI agents sign comments with Name (Client@Model) format, e.g. ::: Socrates (Cursor@Opus) :::, so you can later trace which model produced which reasoning. - Contextual Placement & Dialogue Rules: Comments attach to list items or paragraphs, replies sit at the same level as the original comment, and existing comments are never overwritten during edits. - Use Case: During a design review, ask the AI to comment on an architecture document; it inserts attributed remarks inline, you reply at the same level, and the structured debate remains archived in the file. ## Quick Start Enter commentary mode and add attributed comments to the open Markdown document, then return to dialogue mode when finished.

Frequently Asked Questions about commentary

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add comments to a Markdown file without changing the content?

Use list items with the ::: AUTHOR ::: marker placed as nested sub-items under the target line or as first-level items after a paragraph. The original text stays untouched, and everything indented deeper than the marker belongs to that comment.

How should AI agents sign comments in shared documents?

AI agents use the full format ::: Name (Client@Model) :::, for example ::: Socrates (Cursor@Opus) :::. This records the persona, the IDE or tool, and the model, giving traceability of which brain produced each comment.

Can I reply to a specific line inside a comment?

Yes. Nest your reply marker directly under the specific line inside the comment you are addressing. Replies to a whole comment go at the same indentation level as that comment, never nested directly under another comment marker.

What happens to existing comments when the document is edited?

All existing comments must be preserved during edits. You may add your own attributed replies, and a separate Secretary step can prettify or transform comments during archiving, but overwriting others' comments is not allowed.

When is inline commentary better than chat-based feedback?

Inline commentary fits when feedback must persist with the document, such as design debates or architecture reviews. Chat feedback disappears with the session, while attributed comments keep the dialectic archived in the file itself.