Creates, reads, edits, and comments on monday.com docs with support for live board column embeds and user mentions.
- GitHub stars
- 6
- Files
- 8
- Last commit
- Nov 10, 2026
- License
- MIT
- Allowed tools
- —
What does the docs-collaborator skill do?
docs-collaborator is an agent skill. Creates, reads, edits, and comments on monday.com docs with support for live board column embeds and user mentions.
Summary generated from the skill's SKILL.md.
About the docs-collaborator skill
Writing meeting notes, RFCs, runbooks, and weekly updates within monday.com is what this skill enables. It allows agents to manage the full lifecycle of rich-content documents, including creating, reading, editing, and commenting. Unlike standard markdown editors, it supports platform-native features like inline user and board mentions, notice boxes, and layouts. A standout capability is the ability to embed live board column values, ensuring that documents reflect real-time status from connected boards.
Agents should load this skill when tasked with drafting or updating documentation. To prevent errors, the skill requires a closed-loop workflow where the agent first uses read_docs with include_blocks set to true to identify specific block IDs before attempting any updates. It supports creating documents in workspaces or attaching them directly to specific board items. Users should note that certain block types like images or tables require specific operations, and some embeds are restricted to deletion only.
What an agent can do with it
- 1Drafting structured documentationCreate a new RFC or runbook using common document shapes as a starting point.
- 2Syncing live board dataEmbed real-time status values from a board column directly into a document.
- 3Updating existing contentModify specific sections of a document by targeting precise block IDs.
- 4Collaborating via mentionsTag specific users, boards, or other documents within the text to notify teammates.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the docs-collaborator skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the docs-collaborator skill in Claude Code
~/.claude/skills/docs-collaborator/SKILL.md
$ npx degit mondaycom/skills/skills/docs-collaborator ~/.claude/skills/docs-collaboratorInstall the docs-collaborator skill in Claude Code (project)
.claude/skills/docs-collaborator/SKILL.md
$ npx degit mondaycom/skills/skills/docs-collaborator .claude/skills/docs-collaboratorInstall the docs-collaborator skill in Codex
~/.agents/skills/docs-collaborator/SKILL.md
$ npx degit mondaycom/skills/skills/docs-collaborator ~/.agents/skills/docs-collaboratorInstall the docs-collaborator skill in Gemini CLI
~/.gemini/skills/docs-collaborator/SKILL.md
$ npx degit mondaycom/skills/skills/docs-collaborator ~/.gemini/skills/docs-collaboratorInstall the docs-collaborator skill in Claude.ai
npx degit mondaycom/skills/skills/docs-collaborator docs-collaborator && zip -r docs-collaborator.zip docs-collaborator # claude.ai → Customize → Skills → + → Create skill → Upload a skill → docs-collaborator.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablemondaycom/skills/skills/docs-collaborator is public and reachablegithub.com/mondaycom/skills/tree/HEAD/skills/docs-collaborat ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-10github.com/mondaycom/skills/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/mondaycom/skills/blob/HEAD/skills/docs-collaborat ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/mondaycom/skills/blob/HEAD/skills/docs-collaborat ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 264 linesgithub.com/mondaycom/skills/blob/HEAD/skills/docs-collaborat ↗Pass
SKILL.md
View on GitHubDocs Collaborator
Create, read, edit, and comment on monday.com docs. The skill is a capability surface, not a template engine. Every doc is a stream of typed blocks (headings, paragraphs, lists, tables, code, dividers, notice boxes, layouts, embedded boards / widgets / docs / images / videos / GIFs). The named shapes listed below are starting points - compose and extend freely. The differentiators (live column-value embeds, inline mentions, notice boxes, layouts) apply to any shape, named or invented.
The platform-native value over a raw markdown editor lives in three things most builders miss: inline mentions of users / docs / boards, live column-value embeds that reflect the current state of a board item, and a closed-loop edit pattern that prevents corrupting the doc's block graph.
Core constraint - read this first
Never edit a block you have not read. monday's update_doc API is block-ID-based, and block IDs are only knowable through read_docs with include_blocks: true. Skipping the read leads to operations referencing IDs that do not exist (silent failure) or - worse - reusing an ID from another doc. The closed-loop pattern is non-negotiable:
read_docswithinclude_blocks: trueto get block IDs, types, and positions.- Identify the target block(s) by type and position or by content.
update_docwith the operation that matches the target block's type (see the routing rule below).
Block operation routing - the non-obvious part
Each block type has a different set of allowed mutations. Picking the wrong operation is the #1 cause of "the call succeeded but the doc looks wrong" bugs. The short rule:
- text, code, list_item:
update_blockedits content;replace_blockchanges a text subtype or list variant, whichupdate_blockcannot. - divider, table, image, video, notice_box, layout:
replace_blockonly (their properties are immutable after creation). - BOARD, WIDGET and DOC embeds, GIPHY:
delete_blockonly. No public API creates or modifies them.
Read references/block-operations-matrix.md before any structural edit: it has the full routing matrix, a list_item rendering quirk, and example payloads.
Workflow: Create a doc
Step 1: Decide the location
monday docs live in one of two places:
- Workspace (most common). Requires
workspace_id. Optionaldoc_kind:public(default),private(only the creator),share(specific people). Optionalfolder_idto nest under a folder. - Item-attached. The doc lives in a doc-type column on a specific board item. Requires
item_id. Optionalcolumn_idif the user picked a specific doc column; otherwise the tool auto-creates one.
Cell-limit preflight for item-attached docs. Doc-type cells hold one doc per cell - hard API limit. Before calling create_doc location=item, preflight the target column via get_board_items_page with columnIds: [<doc_col_id>] to check whether the cell is already populated. If populated, do NOT attempt the create - it will fail with CellLimitExceededException. Fall back to creating a workspace-level doc and adding a bi-directional DOC mention cross-link between the new doc and the existing attached doc. Never auto-detach the existing doc.
If the user does not name a workspace, fall back to the user's primary workspace via get_user_context. Ask once if it's still ambiguous; do not guess across multiple workspaces.
Step 2: Plan-tier guard before creating a 4th doc
Free and Basic plans cap at 3 docs per account. Before calling create_doc on a Free / Basic account, check whether this would be the 4th doc. There is no direct doc-count tool, so the practical guard is: if the user has hit this limit before or asks "can I create more than 3 docs?", warn them - upgrade to Standard+ removes the cap. Treat plan-tier as an open question rather than blocking the create call; the platform itself will reject if the cap is hit.
Step 3: Compose the body - shapes are examples, not boundaries
create_doc takes a markdown parameter that is parsed into blocks on import. Keep it to a few sections; append long bodies with add_markdown_content (see references/errors.md). When the user names a use case (meeting notes, weekly update, RFC, runbook, postmortem), start from its common shape in references/create-modes.md, then extend freely.
When the user invents a shape ("partner enablement page", "AI readiness snapshot", "Q3 onboarding context"), compose with judgment - sections, tables, notice boxes, embeds - rather than forcing a named template. The differentiators apply to any shape.
Passive vs active mode. By default, scaffold with visible slot markers (_[embed: ...]_, _[mention: ...]_) where embeds and mentions belong. Switch to active mode - wiring real embeds and mentions - when the user refers to items, boards or people by name; resolve names to IDs yourself (if a name is ambiguous, ask once with the top 3 candidates) and state what you picked. Read references/create-modes.md before wiring anything: it has the marker formats, escalation triggers, name-to-ID resolution chain and the communication contract.
Put table content in the markdown. A markdown table is the only way to get pre-filled table cells; cells cannot be populated after creation. Markdown has no syntax for notice boxes, layouts, embeds, mentions, live column values or asset images: add those with update_doc after the doc is created. Details in "Markdown notes" in references/create-modes.md.
Step 4: Call create_doc
create_doc({
doc_name: "<title>",
location: "workspace",
workspace_id: <id>,
doc_kind: "public" | "private" | "share", // optional
folder_id: <id>, // optional
markdown: "<full markdown body>"
})
For item-attached (after preflight):
create_doc({
doc_name: "<title>",
location: "item",
item_id: <id>,
column_id: "<doc_column_id>", // optional
markdown: "<full markdown body>"
})
Capture the returned doc_id, object_id, and doc_url. The user wants the URL to share or open; the doc_id is the primary key for every subsequent edit.
Step 5: Layer in the rich-content extras
Mentions, live column-value embeds, notice boxes, layouts, and asset images all need a follow-up update_doc call. In active mode, wire them now using the resolved IDs from Step 3. In passive mode, leave the slot markers in place - the user fills slots later by naming items. See "Common patterns" in references/delta-format-cheatsheet.md.
Step 6: Confirm and suggest next steps
Plain-language confirmation: name, workspace, doc URL. State the mode used (passive scaffold or active). Then 2-3 follow-ups appropriate to the shape:
- "Want me to tag the attendees with @mentions?"
- "Want me to embed live status from the project board?"
- "Should I add a notice box at the top with the meeting outcome?"
- "Want me to share the doc URL in a Slack channel?"
Workflow: Read a doc
Step 1: Resolve the doc identifier
Three ways the user might point at a doc:
- doc_id (e.g.,
41302579) - the API's primary key, returned bycreate_docandread_docs. - object_id (e.g.,
18411484379) - the numeric segment of the doc URL:https://monday.monday.com/docs/{object_id}. - doc name or fuzzy reference ("the Q3 retro doc") - resolve via
read_docswithtype: "workspace_ids"to list docs in a workspace, then match by name.
read_docs is forgiving: if you call it with type: "ids" and the value is actually an object_id, it auto-retries as object_ids. Lean on this rather than guessing.
Step 2: Decide what to read
Two modes:
- content (default) - returns the doc's blocks and / or markdown projection.
include_blocks: trueis mandatory if any edit will follow. Do not omit it.include_comments: trueto fetch all comments and replies. Usecomments_limitto cap (default 50).
- version_history - returns the doc's edit history (restoring points). Pass the
object_id, not theid. Setversion_history_limitfor "last N changes" requests; setinclude_diff: trueto see what changed (slower).
Step 3: Render with resolved mentions and embeds, not placeholders
The API's blocks_as_markdown projection renders mentions as @{USER-XXX} placeholders and live column-value embeds as empty space. This is not the right rendering for a "show me what's in this doc" prompt - the user sees pills and live chips when they open the doc; the textual rendering should mirror that.
For "show me / what's in / read this doc" prompts: resolve every mention to a display name, resolve embeds to their current values when cheap, and add an enumeration table of inline non-text elements with their IDs. Read references/read-rendering.md for the exact rules.
Do not use show-table for doc content - the doc itself is the UI. Render in chat with markdown.
Workflow: Edit a doc
Step 1: Read first
read_docs with include_blocks: true. This is the closed-loop precondition. Capture every block's id, type, and position.
Step 2: Pick the right operation
Reach for the simplest one that does the job:
- Add new content at the end:
add_markdown_content(no block IDs needed; supports text, lists, tables, code). - Add asset-based images:
create_blockwithblock_type: "image"andasset_id(markdown does not support asset images). - Edit existing text / code / list_item content in place:
update_blockwith the matchingblock_content_type(text,code, orlist_item). - Change a block's subtype (paragraph -> H2, bulleted -> numbered, INFO notice -> WARNING notice):
replace_block. Subtypes are set on creation only. - Insert a block at a precise position:
create_blockwithafter_block_idset. There is nobefore_block_idoperation - to insert at the very top of a doc, the only path is to insert after the doc's first block. - Delete:
delete_block. The only path for BOARD / WIDGET / DOC embed / GIPHY blocks. - Comment:
add_comment- HTML body; tag people viamentions_list, not@in the body (see "Comments" inreferences/rich-content.md). - Rename the doc:
set_name.
The full type-to-operation routing lives in references/block-operations-matrix.md.
Step 3: Compose the delta_format (for text / code / list_item)
update_block and create_block for content blocks take a delta_format array of insert ops. Three rules govern every delta:
- The last op MUST be
{insert: {text: "\n"}}. Always. No exceptions. - Plain text uses
{insert: {text: "..."}}with optionalattributes(bold, italic, underline, strike, code, link, color, background). - Two non-text inserts unlock the differentiators:
- Mention:
{insert: {mention: {id: <numeric-id>, type: "USER" | "DOC" | "BOARD"}}}. Resolve user IDs vialist_users_and_teams(always passnameto scope the call). - Live column-value embed:
{insert: {column_value: {item_id: <id>, column_id: "<column_id>"}}}. Renders the current value of that column on that item, live, every time the doc is opened.
- Mention:
Worked examples and the full attribute table live in references/delta-format-cheatsheet.md.
Step 4: Batch operations carefully
update_doc accepts up to 25 operations in one call, executed in order, stopping at the first failure. Four gotchas:
- Notice box nesting requires two calls. A notice_box created in the same call cannot be referenced by
parent_block_idin a later operation in the same call. Create the notice_box, capture the returned ID, then make a secondupdate_doccall to nest children. - Position dependencies. If operation B references the position of a block created by operation A, prefer two calls. Failures partway through the array leave the doc in a partial state.
- Same-block conflict detection. When multiple operations in the same call (or the same user turn) target the same
block_id, surface the conflict to the user before executing - "last write wins" is the observed behavior. Example:update_blockadds a mention to paragraph X, then a laterupdate_blockreplaces paragraph X entirely. The second wins; the mention is lost. - Comment anchors live in the delta. When a block has anchored comments, the read response shows
attributes.comments: [<update_id>, ...]on the relevant text insert.update_blockreplaces the entire delta_format, so a clean rewrite detaches the comment from the block (the comment itself survives on the backing item but loses its block link). To preserve anchored comments through an edit, include thecommentsattribute on the matching text insert in the new delta.
Step 5: Verify and confirm
After a non-trivial edit, re-read with include_blocks: true to confirm the blocks landed as intended. Plain-language confirmation: what changed, the doc URL. Do not narrate the API calls.
Rich content: tables, notice boxes, layouts, mentions, live embeds, comments
Live column-value embeds are the differentiator: they keep a doc in sync with real board data. Before adding any of these elements, read references/rich-content.md. It covers table constraints, notice-box nesting, layouts, mention types, live column-value embeds and comments.
Smart defaults
When the user does not specify all values:
- Workspace: the user's primary workspace via
get_user_context. State the default. Ask once if multiple workspaces are plausible. - doc_kind:
public(the platform default). - Folder: none (root of the workspace).
- Doc shape: if the user names a use case ("meeting notes", "RFC", "weekly update"), scaffold the matching shape as a starting point and extend per the user's specific asks. If the user invents a shape, compose with judgment - no template needed.
- Mode: passive scaffold (slot markers) by default. Escalate to active mode (real embeds / mentions / cross-links) only when name-based intent signals are present.
- Embeds and mentions in active mode: state the resolved choices and reasoning before wiring. Offer override.
State every default in the response so the user can override.
Validate preconditions before writing
- Doc exists:
read_docssucceeded for the target ID before any write. - Block IDs are real: every
block_idin the operations array came from the most recentread_docscall. - User IDs for mentions: resolved via
list_users_and_teams(always with anameoruserIdsfilter). - Item IDs and column IDs for embeds:
get_board_infoandget_board_items_pageconfirm both before the write. Status column IDs are always board-specific (e.g.color_mm2x25ey), never the generic literal"status". - Workspace exists:
list_workspacesif the user named one but did not provide an ID. - Cell capacity for item-attached docs: preflight the target doc column via
get_board_items_pagebeforecreate_doc location=item(see Step 1). - Empty-data fallback for active mode: when the user's intent references a column with no values set (e.g. "top priorities" but the Priority column is entirely null), do NOT silently pick. Detect the empty state, disclose to the user ("no Priority values set on any items"), offer a fallback heuristic with explicit reasoning ("picking by Status + Due Date proximity instead"), and offer override.
Duplicate detection before writing
Before any create_block, add_markdown_content, add_comment, or content-replacing update_block, compare the proposed content against existing blocks in the doc. On a match, skip and report it, then offer the user: skip, duplicate, replace, or move (move only when the request names a position). Never silently duplicate. Comments are excluded except for a repeat within 60 seconds. Read references/duplicate-detection.md for the match heuristic per block type and the full exclusions.
Surface errors with remediation
When a call fails, tell the user what went wrong and how to fix it. The catalog of common failures and their remediation (malformed or stale block IDs, schema mismatches, nesting in one call, cell limits, blank embeds, plan limits, unsupported block types, orphan comment anchors) is in references/errors.md.
Be conservative on destructive operations
Require explicit confirmation for:
- Deleting 3+ blocks in one call.
- Deleting a block that is the only content in its parent (deletes the parent's only content; the parent stays as an empty shell).
- Deleting a notice_box, table, or layout - children are NOT auto-deleted; they become orphaned. Either delete children first or accept the orphan state.
- Bulk replace_block operations (each replace is a delete + create; non-reversible).
- Renaming a doc that has live external references (Slack messages, other docs, item updates).
Single block edits, single block creates, and single comments need no extra confirmation - the user already asked.
When to use MCP UI widgets
The doc is the UI. Do not render show-table or show-chart to display doc content. Plain-text confirmations and markdown summaries are the right output.
Plain language over raw JSON
Never tell the user "I called read_docs then update_doc with an update_block operation." Tell them what changed in human terms: "Updated the second paragraph of your runbook with the new escalation contact." Always include the doc URL.
Tools used
get_user_context- resolve the user's primary workspacelist_workspaces- find a workspace by name when not providedcreate_doc- create a doc in a workspace or attached to an item; markdown body imported as blocks on creationread_docs- fetch one or more docs (content mode) or version history;include_blocks: trueis mandatory before any edit;include_comments: truefor comment threadsupdate_doc- sequential operations:set_name,add_markdown_content,update_block,create_block,delete_block,replace_block,add_commentlist_users_and_teams- resolve user IDs for mentions andmentions_list(always passnameoruserIdsto scope)get_board_info- validate column IDs before writing live column-value embeds; preflight board structure for active-mode embed wiringget_board_items_page- validate item IDs before writing live column-value embeds; preflight doc-column cells for item-attached create; resolve item names to IDs in active modesearch- fuzzy-resolve a doc by name or a board by name in active mode
Additional resources
references/block-operations-matrix.md- per-block-type allowed operations, gotchas, and example payloads.references/create-modes.md- passive-scaffold slot markers, active-mode triggers, name-to-ID resolution, the communication contract, common doc shapes and markdown notes.references/duplicate-detection.md- match heuristics per block type, what to offer on a match, and when duplication is normal.references/rich-content.md- tables, notice boxes, layouts, mentions, live column-value embeds and comments.references/read-rendering.md- how to render mentions, embeds and inline elements when reading a doc.references/errors.md- common failures and how to remediate them.references/delta-format-cheatsheet.md- delta_format insert ops, attributes, mentions, column_value embeds, the terminator rule, common patterns, and the passive-mode slot marker format.
Files in this skill
8docs-collaborator skill questions
How do I install the docs-collaborator skill in Claude Code?
Run npx degit mondaycom/skills/skills/docs-collaborator ~/.claude/skills/docs-collaborator. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the docs-collaborator skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How can I edit an existing document?
You must first read the document with include_blocks: true to obtain the necessary block IDs, then use the appropriate update operation based on the block type.
Can I embed live data from a monday board into a doc?
Yes, the skill allows for embedding live column-value embeds that reflect the current real-time status of a board item.
What is the limit for creating docs on free or basic plans?
Free and Basic plans are capped at 3 docs per account.