diff --git a/.gemini-plugin/plugin.json b/.gemini-plugin/plugin.json index b015655..4fea036 100644 --- a/.gemini-plugin/plugin.json +++ b/.gemini-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "monday-work-management", "displayName": "monday.com", - "version": "1.0.0", + "version": "1.0.1", "description": "Plan and track work in monday.com from Gemini: set up boards, create, update and assign items, get project status reports, write docs, and build forms that turn requests into items.", "author": { "name": "monday.com", diff --git a/CHANGELOG.md b/CHANGELOG.md index 9b2115d..8a8f5c0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,12 @@ All notable changes to this plugin are documented here. Versions follow [Semantic Versioning](https://semver.org). +## 1.0.1 + +- Skills synced from `mondaycom/skills` with every tool call matched to the current monday.com MCP tool schemas + (parameter names, required fields and return values). +- MCP UI widgets are used only when the client lists them; otherwise skills answer in markdown with the board link. + ## 1.0.0 - First release for Gemini Agent: the monday.com MCP server (`https://mcp.monday.com/mcp`) and six skills, diff --git a/skills.json b/skills.json index 57089aa..e03699b 100644 --- a/skills.json +++ b/skills.json @@ -1,6 +1,6 @@ { "repo": "https://github.com/mondaycom/skills.git", - "ref": "b41be7f7b84134d0b074968482c70fc9e8e53418", + "ref": "6be49b9ae40a5d4a72b11564698519d34dc1786d", "prefix": "monday-", "skills": [ "onboard-to-monday", diff --git a/skills/monday-board-setup/SKILL.md b/skills/monday-board-setup/SKILL.md index 434cb2c..bf7d63a 100644 --- a/skills/monday-board-setup/SKILL.md +++ b/skills/monday-board-setup/SKILL.md @@ -11,9 +11,8 @@ description: | license: MIT metadata: author: monday.com - version: "0.2.2" + version: "0.2.3" --- - # Board Setup Create and configure monday.com boards with proper structure - the right column types, meaningful groups, and initial items. In monday.com, a board is the central workspace where a team tracks any workflow: project delivery, sales pipeline, bug triage, content production, event planning, and more. This skill provides the domain knowledge needed to build well-organized boards that match how teams actually work. @@ -62,7 +61,7 @@ Call `create_board` with: Fill only the gaps with Steps 4-6. Do not rebuild the board. Tell the user in one line what you corrected. -**If `create_board` fails or times out, do not call it again straight away** - the board may already exist. Call `search` for the board name first and only retry if it is not there; re-sending creates duplicate boards. +**If `create_board` fails or times out, do not call it again straight away** - the board may already exist. Call `search` with `searchType: "BOARD"` and `searchTerm: ""` first and only retry if it is not there; re-sending creates duplicate boards. Without `creationPrompt` you get an empty board; build it with Steps 4-6. @@ -81,6 +80,8 @@ Call `create_group` for each workflow stage or category. - Rename: `mutation { update_group(board_id: , group_id: "", group_attribute: title, new_value: "New name") { id title } }` - Move above another group: `group_attribute: relative_position_before, new_value: ""` (or `relative_position_after`), selecting `{ id position }`. +If any raw GraphQL mutation via `all_monday_api` is rejected, inspect the live GraphQL schema (`get_graphql_schema` / `get_type_details` if available) before retrying. + Renaming the default `topics` group into your first workflow group is an alternative to deleting it. `create_group` only accepts the exact hex values listed in its `groupColor` enum - a similar shade is rejected. @@ -106,7 +107,7 @@ Common group patterns: If you used `creationPrompt`, only add the columns `get_board_info` shows are missing. Otherwise, call `create_column` for each data field. For each column, specify: - `boardId`: the board ID from Step 3 -- `title`: the display name +- `columnTitle`: the display name - `columnType`: the monday.com column type (see Column Type Selection below) - `columnSettings`: JSON-stringified label config when the column needs custom labels (see "Custom labels for status columns" below) @@ -156,12 +157,12 @@ For the primary workflow Status column, leave `columnSettings` off - the default `update_column` replaces the column's whole label list: -1. Call `get_board_info` with `filters.columns.ids` for the column to get its `revision` and current `settings.labels`. -2. Send **every label you want to keep**, each with its existing `id`, `label`, `color`, and `index`. **A label you leave out is deleted.** +1. Call `get_board_info` with `filters.columns.ids` for the column to get its `revision`, `type`, and current `settings.labels`. +2. Call `update_column` with `boardId`, `columnId`, `columnType` (matching the existing type), `revision`, and **every label you want to keep**, each with its existing `id`, `label`, `color`, and `index`. **A label you leave out is deleted.** 3. Add new labels **without** an `id` - an invented id is rejected ("Label ids: 5 do not exist"). A new label may reuse a color that is already taken. 4. Use the new `revision` from the response for any further update. -Changing the color of an existing label is not supported: the call reports success but the color stays the same. To change a color, tell the user to do it from the column's label editor in monday. +To recolor an existing label, send its existing `id` with the new `color`, then read the column back with `get_board_info` to confirm the change; if the color did not change, tell the user to change it from the column's label editor in monday. ### Step 6: Seed initial items (optional) @@ -240,39 +241,13 @@ If the user is unsure of their plan, just create the board with standard columns ## Board Templates by Use Case -### Project Tracker -- **Groups:** To Do, In Progress, In Review, Done -- **Columns:** Status, Owner (people), Due Date (date), Priority (status, custom labels Low/Medium/High/Critical), Notes (text) - -### Bug Tracker -- **Groups:** New, Triaged, In Progress, Fixed, Verified -- **Columns:** Status, Assignee (people), Severity (status, custom labels Low/Medium/High/Critical), Due Date (date), Steps to Reproduce (long_text), Environment (dropdown) - -### Sales/CRM Pipeline -- **Groups:** Lead, Qualified, Proposal, Negotiation, Closed Won, Closed Lost -- **Columns:** Stage (status, custom labels matching the group names: Lead/Qualified/Proposal/Negotiation/Closed Won/Closed Lost), Owner (people), Company (text), Deal Value (numbers), Close Date (date), Source (dropdown) - -### Content Calendar -- **Groups:** Ideas, In Production, In Review, Published -- **Columns:** Status, Author (people), Publish Date (date), Content Type (dropdown), Channel (dropdown), Link (link) - -### Event Planning -- **Groups:** Planning, Logistics, Marketing, Day-Of, Post-Event -- **Columns:** Status, Owner (people), Timeline (timeline), Budget (numbers), Priority (status), Notes (text) - -### Sprint Board -- **Groups:** Backlog, Sprint [current], In Progress, Done -- **Columns:** Status, Assignee (people), Story Points (numbers), Sprint (dropdown), Due Date (date), Type (status) - -### Request/Intake -- **Groups:** New Requests, Under Review, Approved, In Progress, Completed -- **Columns:** Status, Requester (people), Assigned To (people), Priority (status), Due Date (date), Request Type (dropdown), Description (long_text) +For common workflows (project tracker, bug tracker, CRM pipeline, content calendar, event planning, sprint board, request intake), start from the groups and columns in `references/board-templates.md`. ## Error Prevention and Remediation - If `create_board` fails due to permissions, suggest using an existing workspace the user has admin access to, or ask which workspace they want to use. - If a column type is rejected (e.g., formula on a non-Pro plan), explain the plan gating and propose an alternative column type. -- **Detect name collisions before creating.** monday allows two boards with the same name in the same workspace, which is a usability trap. Before calling `create_board`, call `search` with the requested board name scoped to the target workspace. If a board with that name already exists, ask the user: use the existing one, create with a suffix (e.g., "Board Name (2)"), or pick a different name. Skipping this check and creating a duplicate is a fail. +- **Detect name collisions before creating.** monday allows two boards with the same name in the same workspace, which is a usability trap. Before calling `create_board`, call `search` with `searchType: "BOARD"` and `searchTerm: ""`, scoped with `workspaceIds: []`. If a board with that name already exists, ask the user: use the existing one, create with a suffix (e.g., "Board Name (2)"), or pick a different name. Skipping this check and creating a duplicate is a fail. - If `columnSettings` JSON is malformed, `create_column` returns an error. The label format requires an array of `{label, color, index}` objects, not a name->color map. See "Custom labels for status columns" above. - **Date filters in saved views** (`create_view_table` / `update_view_table`) take different values from item filters. Use `between` with two plain `YYYY-MM-DD` dates, `greater_than` / `lower_than` with `"TODAY"`, or `within_the_next` / `within_the_last` with `["DAYS", 7]`. `any_of` with `["EXACT", ""]` is rejected in views, even though `get_column_type_info` guidelines list it - those guidelines are for `get_board_items_page` filters. @@ -282,9 +257,9 @@ If the user is unsure of their plan, just create the board with standard columns - `get_column_type_info` - understand available column types and their schemas (including the `columnSettings` shape for status columns) - `create_board` - create the board, preferably with `creationPrompt` so monday builds the structure in one call - `create_group` - add groups to the board -- `create_column` - add columns with correct types and custom `columnSettings` for Priority / Severity / Stage / Risk / etc. -- `update_column` - change labels on an existing status column (full label list, existing ids) -- `get_board_info` - read a column's `revision` and current labels before `update_column` +- `create_column` - add columns with `columnTitle`, `columnType`, and custom `columnSettings` for Priority / Severity / Stage / Risk / etc. +- `update_column` - change labels on an existing status column (`columnType`, `revision`, full label list with existing ids) +- `get_board_info` - read a column's `revision`, `type`, and current labels before `update_column` - `create_items` - seed initial items in one call (optional) - `create_view_table` - saved table views with filters (optional) - `get_board_items_page` - check starter-item values after `creationPrompt` @@ -296,4 +271,5 @@ If the user is unsure of their plan, just create the board with standard columns ## Additional Resources +- **`references/board-templates.md`** - Starting groups and columns for common workflows - **`references/column-types-guide.md`** - Complete guide to all monday.com column types, when to use each, and configuration options diff --git a/skills/monday-board-setup/references/board-templates.md b/skills/monday-board-setup/references/board-templates.md new file mode 100644 index 0000000..5069b7e --- /dev/null +++ b/skills/monday-board-setup/references/board-templates.md @@ -0,0 +1,31 @@ +# Board Templates by Use Case + +Starting structures for common workflows. Adjust groups and columns to what the user describes. + +### Project Tracker +- **Groups:** To Do, In Progress, In Review, Done +- **Columns:** Status, Owner (people), Due Date (date), Priority (status, custom labels Low/Medium/High/Critical), Notes (text) + +### Bug Tracker +- **Groups:** New, Triaged, In Progress, Fixed, Verified +- **Columns:** Status, Assignee (people), Severity (status, custom labels Low/Medium/High/Critical), Due Date (date), Steps to Reproduce (long_text), Environment (dropdown) + +### Sales/CRM Pipeline +- **Groups:** Lead, Qualified, Proposal, Negotiation, Closed Won, Closed Lost +- **Columns:** Stage (status, custom labels matching the group names: Lead/Qualified/Proposal/Negotiation/Closed Won/Closed Lost), Owner (people), Company (text), Deal Value (numbers), Close Date (date), Source (dropdown) + +### Content Calendar +- **Groups:** Ideas, In Production, In Review, Published +- **Columns:** Status, Author (people), Publish Date (date), Content Type (dropdown), Channel (dropdown), Link (link) + +### Event Planning +- **Groups:** Planning, Logistics, Marketing, Day-Of, Post-Event +- **Columns:** Status, Owner (people), Timeline (timeline), Budget (numbers), Priority (status), Notes (text) + +### Sprint Board +- **Groups:** Backlog, Sprint [current], In Progress, Done +- **Columns:** Status, Assignee (people), Story Points (numbers), Sprint (dropdown), Due Date (date), Type (status) + +### Request/Intake +- **Groups:** New Requests, Under Review, Approved, In Progress, Completed +- **Columns:** Status, Requester (people), Assigned To (people), Priority (status), Due Date (date), Request Type (dropdown), Description (long_text) diff --git a/skills/monday-board-setup/references/column-types-guide.md b/skills/monday-board-setup/references/column-types-guide.md index d8d5cdf..c544a24 100644 --- a/skills/monday-board-setup/references/column-types-guide.md +++ b/skills/monday-board-setup/references/column-types-guide.md @@ -24,7 +24,7 @@ Visual color-coded labels representing workflow states. The most important colum **Anti-pattern:** Passing labels as a name->color map (`{"Low": "sky", ...}`) - the API rejects this. Must be an array of objects. -**`is_done` flag:** Each label has an optional `is_done` boolean. Setting `is_done: true` on a label tells reports, automations, and progress widgets that this label means "complete". On user-created boards via the UI, this flag is often left unset on every label including "Done". When creating status columns programmatically and you care about correct progress reporting, set `is_done: true` explicitly on the success label(s). +**`is_done` flag:** Each label has an optional `is_done` boolean. Setting `is_done: true` on a label tells reports, automations, and progress indicators that this label means "complete". On user-created boards via the UI, this flag is often left unset on every label including "Done". When creating status columns programmatically and you care about correct progress reporting, set `is_done: true` explicitly on the success label(s). ### people @@ -200,7 +200,7 @@ Reflects data from linked items on other boards. **Use for:** Cross-board data visibility without duplication. -### connect_boards +### board_relation (Connect boards) Links items across different boards. diff --git a/skills/monday-docs-collaborator/SKILL.md b/skills/monday-docs-collaborator/SKILL.md index 6a25fc6..3e90469 100644 --- a/skills/monday-docs-collaborator/SKILL.md +++ b/skills/monday-docs-collaborator/SKILL.md @@ -1,24 +1,18 @@ --- name: monday-docs-collaborator description: | - Creates, reads, edits, and comments on monday.com docs - the rich-content - surface inside monday for meeting notes, RFCs, runbooks, weekly updates, - postmortems, and any work-adjacent writing. Goes beyond markdown shuffling - by embedding live board column values inline (so the doc reflects real-time - status), tagging users / docs / boards via mentions, scaffolding common doc - shapes, and routing each edit through the correct update_doc operation. - Use when user asks to "create a doc", "make a monday doc", "draft meeting - notes", "write an RFC", "scaffold a runbook", "summarize a meeting in a - doc", "add a section to my doc", "edit my doc", "update the doc", - "comment on a doc", "tag someone in a doc", "embed a status in a doc", + Creates, reads, edits, and comments on monday.com docs - meeting notes, RFCs, runbooks, weekly + updates, and postmortems - with live board column-value embeds and user, doc, or board mentions. + Use when user asks to "create a doc", "make a monday doc", "draft meeting notes", "write an RFC", + "scaffold a runbook", "summarize a meeting in a doc", "add a section to my doc", "edit my doc", + "update the doc", "comment on a doc", "tag someone in a doc", "embed a status in a doc", "show live board data in a doc", "rename a doc", or "show me my docs". Don't use for creating or updating board items (use monday-task-management), a status report from board data (use monday-project-status-report), or building forms (use monday-forms-builder). license: MIT metadata: author: monday.com - version: "0.2.2" + version: "0.2.3" --- - # Docs 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. @@ -27,7 +21,7 @@ The platform-native value over a raw markdown editor lives in three things most ## 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: +**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: 1. `read_docs` with `include_blocks: true` to get block IDs, types, and positions. 2. Identify the target block(s) by type and position or by content. @@ -39,7 +33,7 @@ Each block type has a different set of allowed mutations. Picking the wrong oper - **text, code, list_item:** `update_block` edits content; `replace_block` changes a text subtype or list variant, which `update_block` cannot. - **divider, table, image, video, notice_box, layout:** `replace_block` only (their properties are immutable after creation). -- **BOARD, WIDGET and DOC embeds, GIPHY:** `delete_block` only. No public API creates or modifies them. +- **BOARD, WIDGET and DOC embeds, GIPHY:** `delete_blocks` only. 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. @@ -50,15 +44,15 @@ Read `references/block-operations-matrix.md` before any structural edit: it has monday docs live in one of two places: - **Workspace** (most common). Requires `workspace_id`. Optional `doc_kind`: `public` (default), `private` (only the creator), `share` (specific people). Optional `folder_id` to nest under a folder. -- **Item-attached**. The doc lives in a doc-type column on a specific board item. Requires `item_id`. Optional `column_id` if the user picked a specific doc column; otherwise the tool auto-creates one. +- **Item-attached**. The doc lives in a doc-type column on a specific board item. Requires `item_id`. Optional `column_id` if the user picked a specific doc column; otherwise the tool uses the board's existing doc column, or creates one if there is none. -**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: []` 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. +**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 that cell via `get_board_items_page` (`boardId`, `itemIds`, `includeColumns: true`, `columnIds: []`). If populated, do not create: the tool would return the existing doc unchanged (`existing_doc_found: true`) without applying your name or markdown. Offer to append to that doc with `add_markdown_content`, or **create a workspace-level doc with a bi-directional DOC mention cross-link** to it. 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. +If the user does not name a workspace, check their favorite workspaces in `get_user_context`, then `list_workspaces` (their own first). 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. +**Free and Basic plans cap at 3 docs per account.** `get_user_context` returns the plan (`account.tier`). There is no 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 @@ -99,7 +93,7 @@ Capture the returned `doc_id`, `object_id`, and `doc_url`. The user wants the UR ### 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`. +Mentions, live column-value embeds, notice boxes, layouts, and 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 @@ -108,7 +102,6 @@ Plain-language confirmation: name, workspace, doc URL. State the mode used (pass - "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 @@ -116,9 +109,9 @@ Plain-language confirmation: name, workspace, doc URL. State the mode used (pass Three ways the user might point at a doc: -- **doc_id** (e.g., `41302579`) - the API's primary key, returned by `create_doc` and `read_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_docs` with `type: "workspace_ids"` to list docs in a workspace, then match by name. +- **doc_id** (e.g., `12345678`) - the API's primary key, returned by `create_doc` and `read_docs`. +- **object_id** (e.g., `9876543210`) - the numeric segment of the doc URL: `https://.monday.com/docs/{object_id}`. +- **doc name or fuzzy reference** ("the Q3 retro doc") - resolve via `read_docs` with `type: "workspace_ids"` to list docs in a workspace, or `search` with `searchType: "DOCUMENTS"` and `searchTerm: ""`, 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. @@ -127,7 +120,7 @@ Three ways the user might point at a doc: Two modes: - **content** (default) - returns the doc's blocks and / or markdown projection. - - `include_blocks: true` is **mandatory** if any edit will follow. Do not omit it. + - `include_blocks: true` is **mandatory** if any edit will follow. Blocks come 25 per page; use `blocks_limit` / `blocks_page` for longer docs. - `include_comments: true` to fetch all comments and replies. Use `comments_limit` to cap (default 50). - **version_history** - returns the doc's edit history (restoring points). Pass the `object_id`, not the `id`. Set `version_history_limit` for "last N changes" requests; set `include_diff: true` to see what changed (slower). @@ -137,7 +130,7 @@ The API's `blocks_as_markdown` projection renders mentions as `@{USER-XXX}` plac 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. +Render doc content directly in chat using Markdown. ## Workflow: Edit a doc @@ -149,12 +142,12 @@ Do not use `show-table` for doc content - the doc itself is the UI. Render in ch 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_block` with `block_type: "image"` and `asset_id` (markdown does not support asset images). +- **Add new content at the end:** `add_markdown_content` (no block IDs needed; supports text, lists, tables, code; optional `after_block_id`). +- **Add images:** `create_block` with `block_type: "image"` and `public_url`, or `asset_id` of an existing monday file (see `references/create-modes.md`). - **Edit existing text / code / list_item content in place:** `update_block` with the matching `block_content_type` (`text`, `code`, or `list_item`). -- **Change a block's subtype** (paragraph -> H2, bulleted -> numbered, INFO notice -> WARNING notice): `replace_block`. Subtypes are set on creation only. +- **Change a block's subtype** (paragraph -> H2, bulleted -> numbered, INFO notice -> WARNING notice): `replace_block`. Pass `after_block_id` (the preceding block), or the new block lands at the end. - **Insert a block at a precise position:** `create_block` with `after_block_id` set. There is no `before_block_id` operation - 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. +- **Delete:** `delete_blocks` with `block_ids: ["", ...]` (1-100 IDs in one operation). The only path for BOARD / WIDGET / DOC embed / GIPHY blocks. - **Comment:** `add_comment` - HTML body; tag people via `mentions_list`, not `@` in the body (see "Comments" in `references/rich-content.md`). - **Rename the doc:** `set_name`. @@ -165,7 +158,7 @@ The full type-to-operation routing lives in `references/block-operations-matrix. `update_block` and `create_block` for content blocks take a `delta_format` array of insert ops. Three rules govern every delta: 1. The last op MUST be `{insert: {text: "\n"}}`. Always. No exceptions. -2. Plain text uses `{insert: {text: "..."}}` with optional `attributes` (bold, italic, underline, strike, code, link, color, background). +2. Plain text uses `{insert: {text: "..."}}` with optional `attributes` (`bold`, `italic`, `underline`, `strike`, `code`, `link`, `color`, `background`). 3. Two non-text inserts unlock the differentiators: - Mention: `{insert: {mention: {id: , type: "USER" | "DOC" | "BOARD"}}}`. Resolve user IDs via `list_users_and_teams` (always pass `name` to scope the call). - Live column-value embed: `{insert: {column_value: {item_id: , column_id: ""}}}`. Renders the current value of that column on that item, live, every time the doc is opened. @@ -179,7 +172,7 @@ Worked examples and the full attribute table live in `references/delta-format-ch - **Notice box nesting requires two calls.** A notice_box created in the same call cannot be referenced by `parent_block_id` in a later operation in the same call. Create the notice_box, capture the returned ID, then make a second `update_doc` call 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_block` adds a mention to paragraph X, then a later `update_block` replaces 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: [, ...]` on the relevant text insert. `update_block` replaces 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 the `comments` attribute on the matching text insert in the new delta. +- **Comment anchors and `update_block`.** `update_block` replaces the whole `delta_format` and detaches block-anchored comments (the comment survives, but loses its block link). Never send a `comments` attribute - it is ignored, and cannot keep the anchor. Warn the user before rewriting a block with anchored comments, or add content beside it instead. ### Step 5: Verify and confirm @@ -193,7 +186,7 @@ Live column-value embeds are the differentiator: they keep a doc in sync with re 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. +- **Workspace**: a favorite workspace from `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. @@ -205,10 +198,10 @@ State every default in the response so the user can override. ## Validate preconditions before writing - **Doc exists:** `read_docs` succeeded for the target ID before any write. -- **Block IDs are real:** every `block_id` in the operations array came from the most recent `read_docs` call. +- **Block IDs are real:** every `block_id` (or ID in `block_ids`) in the operations array came from the most recent `read_docs` call. - **User IDs for mentions:** resolved via `list_users_and_teams` (always with a `name` or `userIds` filter). -- **Item IDs and column IDs for embeds:** `get_board_info` and `get_board_items_page` confirm both before the write. Status column IDs are always board-specific (e.g. `color_mm2x25ey`), never the generic literal `"status"`. -- **Workspace exists:** `list_workspaces` if the user named one but did not provide an ID. +- **Item IDs and column IDs for embeds:** `get_board_info` and `get_board_items_page` confirm both before the write. Use the column ID exactly as `get_board_info` returns it (for example, `status` on older boards or `color_mk...` on newer ones) — never guess without checking `get_board_info`. +- **Workspace exists:** `search` with `searchType: "WORKSPACES"` if 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_page` before `create_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. @@ -224,17 +217,17 @@ When a call fails, tell the user what went wrong and how to fix it. The catalog Require explicit confirmation for: -- Deleting 3+ blocks in one call. +- Deleting 3+ blocks in one call (use a single `delete_blocks` operation with all IDs in `block_ids`, up to 100 per 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). +- Bulk `replace_block` operations (each replace is a delete + create; non-reversible). +- Renaming a doc that has live external references (chat 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 +## Output format -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. +The doc is the UI. Even when `show-table` or `show-chart` widgets are available, do not use them for doc content; present confirmations and summaries in plain text and Markdown. ## Plain language over raw JSON @@ -242,15 +235,15 @@ Never tell the user "I called `read_docs` then `update_doc` with an `update_bloc ## Tools used -- `get_user_context` - resolve the user's primary workspace -- `list_workspaces` - find a workspace by name when not provided +- `get_user_context` - favorite workspaces and plan tier +- `list_workspaces` - list workspaces when the user names none - `create_doc` - create a doc in a workspace or attached to an item; markdown body imported as blocks on creation - `read_docs` - fetch one or more docs (content mode) or version history; `include_blocks: true` is mandatory before any edit; `include_comments: true` for comment threads -- `update_doc` - sequential operations: `set_name`, `add_markdown_content`, `update_block`, `create_block`, `delete_block`, `replace_block`, `add_comment` +- `update_doc` - sequential operations: `set_name`, `add_markdown_content`, `update_block`, `create_block`, `delete_blocks`, `replace_block`, `add_comment` - `list_users_and_teams` - resolve user IDs for mentions and `mentions_list` (always pass `name` or `userIds` to scope) - `get_board_info` - validate column IDs before writing live column-value embeds; preflight board structure for active-mode embed wiring - `get_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 mode -- `search` - fuzzy-resolve a doc by name or a board by name in active mode +- `search` - fuzzy-resolve a doc (`searchType: "DOCUMENTS"`, `searchTerm`) or board (`searchType: "BOARD"`, `searchTerm`) or workspace (`searchType: "WORKSPACES"`) by name ## Additional resources diff --git a/skills/monday-docs-collaborator/references/block-operations-matrix.md b/skills/monday-docs-collaborator/references/block-operations-matrix.md index a0eb9ba..b638e14 100644 --- a/skills/monday-docs-collaborator/references/block-operations-matrix.md +++ b/skills/monday-docs-collaborator/references/block-operations-matrix.md @@ -7,7 +7,7 @@ Per-block-type guide to which `update_doc` operation to use. Picking the wrong o 1. Call `read_docs` with `include_blocks: true` to get the doc's blocks. 2. Find the target block by `id` and look up its `type` field. 3. Match the row below to choose the operation. -4. Compose the operation per the column "Example payload". +4. Compose the operation per the example payload below. ## Type naming - input vs output @@ -22,21 +22,21 @@ When matching a read block to a row in this table, normalize on the lowercase ou | Output type | Subtypes | Allowed ops | Disallowed | Notes | |---|---|---|---|---| -| `large title`, `medium title`, `small title`, `normal text`, `quote` | text block subtypes (LARGE_TITLE / MEDIUM_TITLE / SMALL_TITLE / NORMAL_TEXT / QUOTE) | `update_block` (content), `replace_block` (subtype change), `delete_block`, `add_comment` | Cannot change subtype with `update_block` | Use `block_content_type: "text"` in update_block | -| `code` | language-tagged code block | `update_block`, `replace_block`, `delete_block`, `add_comment` | - | Use `block_content_type: "code"` in update_block; pass `language` to update or change | -| `bulleted list`, `numbered list`, `check list` | list_item subtypes (BULLETED_LIST / NUMBERED_LIST / CHECK_LIST) | `update_block` (content), `replace_block` (variant change), `delete_block`, `add_comment` | Cannot change list variant with `update_block` | Use `block_content_type: "list_item"` in update_block; pass `checked: bool` for CHECK_LIST items; `indentation: 0..N` for nesting | -| `divider` | - | `replace_block`, `delete_block` | `update_block` (no mutable properties), `add_comment` | Replace with another divider is a no-op visually; rarely needed | -| `page break` | - | `delete_block` | `update_block`, `replace_block`, `add_comment` | Print-layout only; treat as decorative | -| `table` | row_count, column_count, column widths | `replace_block`, `delete_block` | `update_block` (cell content not addressable), `add_comment` | See "Tables" below | -| `cell` (table cell) | - | `delete_block` only via parent table replacement | `update_block`, `replace_block`, `create_block` with parent_block_id, `add_comment` | Cells are pseudo-blocks; cannot be mutated directly | -| `image` | public_url or asset_id | `replace_block` (swap source), `delete_block` | `update_block`, `add_comment` | URL / asset_id immutable after creation | -| `video` | raw_url | `replace_block` (swap source), `delete_block` | `update_block`, `add_comment` | URL immutable after creation | -| `notice box` | theme: INFO / TIPS / WARNING / GENERAL | `replace_block` (theme change), `delete_block`, `create_block` with parent_block_id (in a SEPARATE later call) | `update_block`, `add_comment` directly on the notice_box itself | Theme immutable; content lives in child blocks. See "Notice boxes" below | -| `layout` | column_count: 2-6, column_style widths | `replace_block`, `delete_block` | `update_block`, `create_block` with parent_block_id, `add_comment` | Cell content not populatable via API at all. See "Layouts" below | -| `BOARD` embed | - | `delete_block` only | `update_block`, `replace_block`, `create_block`, `add_comment` | No public API to create or modify; must be added from the monday UI | -| `WIDGET` embed | - | `delete_block` only | `update_block`, `replace_block`, `create_block`, `add_comment` | No public API to create or modify | -| `DOC` embed | - | `delete_block` only | `update_block`, `replace_block`, `create_block`, `add_comment` | No public API to create or modify | -| `GIPHY` | - | `delete_block` only | `update_block`, `replace_block`, `create_block`, `add_comment` | No public API to create or modify | +| `large title`, `medium title`, `small title`, `normal text`, `quote` | text block subtypes (LARGE_TITLE / MEDIUM_TITLE / SMALL_TITLE / NORMAL_TEXT / QUOTE) | `update_block` (content), `replace_block` (subtype change), `delete_blocks`, `add_comment` | Cannot change subtype with `update_block` | Use `block_content_type: "text"` in update_block | +| `code` | language-tagged code block | `update_block`, `replace_block`, `delete_blocks`, `add_comment` | - | Use `block_content_type: "code"` in update_block; pass `language` to update or change. `create_block` / `replace_block` ignore `language`, so set it with a follow-up `update_block` | +| `bulleted list`, `numbered list`, `check list` | list_item subtypes (BULLETED_LIST / NUMBERED_LIST / CHECK_LIST) | `update_block` (content), `replace_block` (variant change), `delete_blocks`, `add_comment` | Cannot change list variant with `update_block` | Use `block_content_type: "list_item"` in update_block; pass `checked: bool` for CHECK_LIST items; `indentation: 0..N` for nesting | +| `divider` | - | `replace_block`, `delete_blocks` | `update_block` (no mutable properties), `add_comment` | Replace with another divider is a no-op visually; rarely needed | +| `page break` | - | `delete_blocks` | `update_block`, `replace_block`, `add_comment` | Print-layout only; treat as decorative | +| `table` | row_count, column_count, column widths | `replace_block`, `delete_blocks` | `update_block` (cell content not addressable), `add_comment` | See "Tables" below | +| `cell` (table cell) | - | `delete_blocks` only via parent table replacement | `update_block`, `replace_block`, `create_block` with parent_block_id, `add_comment` | Cells are pseudo-blocks; cannot be mutated directly | +| `image` | public_url or asset_id | `replace_block` (swap source), `delete_blocks` | `update_block`, `add_comment` | URL / asset_id immutable after creation; `asset_id` must be an existing monday asset (see "Markdown notes" in create-modes.md) | +| `video` | raw_url | `replace_block` (swap source), `delete_blocks` | `update_block`, `add_comment` | URL immutable after creation | +| `notice box` | theme: INFO / TIPS / WARNING / GENERAL | `replace_block` (theme change), `delete_blocks`, `create_block` with parent_block_id (in a SEPARATE later call) | `update_block`, `add_comment` directly on the notice_box itself | Theme immutable; content lives in child blocks. See "Notice boxes" below | +| `layout` | column_count: 2-6, column_style widths | `replace_block`, `delete_blocks` | `update_block`, `create_block` with parent_block_id, `add_comment` | Cell content not populatable via API at all. See "Layouts" below | +| `BOARD` embed | - | `delete_blocks` only | `update_block`, `replace_block`, `create_block`, `add_comment` | No public API to create or modify; must be added from the monday UI | +| `WIDGET` embed | - | `delete_blocks` only | `update_block`, `replace_block`, `create_block`, `add_comment` | No public API to create or modify | +| `DOC` embed | - | `delete_blocks` only | `update_block`, `replace_block`, `create_block`, `add_comment` | No public API to create or modify | +| `GIPHY` | - | `delete_blocks` only | `update_block`, `replace_block`, `create_block`, `add_comment` | No public API to create or modify | **Rendering quirk - list_item + mention via `update_block`.** When adding an inline mention to a list_item that previously contained only text, `update_block` may save the mention blot correctly (data confirms) but some clients can fail to render the pill (text-prefix-before-mention case). Workaround: use `replace_block` with a fresh list_item containing the same delta. Same pattern in a `normal_text` block renders correctly; the quirk appears specific to list_item updates. @@ -65,7 +65,7 @@ Variants: `update_block` cannot change the block subtype. To go from a paragraph to an H2, use `replace_block`. -## replace_block - delete + create in one slot +## replace_block - delete, then create Use when: @@ -77,6 +77,7 @@ Use when: { "operation_type": "replace_block", "block_id": "", + "after_block_id": "", "block": { "block_type": "text", "text_block_type": "MEDIUM_TITLE", @@ -88,7 +89,7 @@ Use when: } ``` -Note: `replace_block` is delete + create. Comments anchored to the old block are lost. Children of the old block (notice_box children, table cells) are NOT moved to the new block; they become orphaned blocks. +Note: `replace_block` is delete + create, not an in-place swap. Pass `after_block_id` (the block that precedes the old one; from `read_docs`) or the replacement is appended at the end of the doc. For a block inside a notice_box, also pass `parent_block_id`. If the create step fails, the original block is already deleted. Comments anchored to the old block are lost. Children of the old block (notice_box children, table cells) are NOT moved to the new block; they become orphaned blocks. ## create_block - insert anywhere @@ -125,18 +126,20 @@ Then in a SEPARATE call: } ``` -## delete_block - the only path for embed types +## delete_blocks - the only path for embed types Works for every block type. The only available operation for `BOARD`, `WIDGET`, `DOC` embed, and `GIPHY` blocks. +Put **ALL** block IDs to delete into a single `delete_blocks` operation's `block_ids` array (1-100 IDs). Never emit multiple `delete_blocks` operations in a row. + ```json { - "operation_type": "delete_block", - "block_id": "" + "operation_type": "delete_blocks", + "block_ids": ["", ""] } ``` -Deleting a parent block (notice_box, table, layout) does NOT delete its children. Delete children first if you want a clean removal. +Deleting a parent block (notice_box, table, layout) does NOT delete its children. Include the child IDs in `block_ids` (or delete children first) if you want a clean removal. ## Tables @@ -144,7 +147,7 @@ Tables are pre-populated only via markdown: - **Initial creation:** include the table in the markdown body of `create_doc`. - **After creation:** `add_markdown_content` with a markdown table appends a new pre-filled table. -- **Editing existing cells:** not supported by the API. `replace_block` swaps the entire table; the new one can be populated only by also using `add_markdown_content` (delete the old table, then append a new markdown table). +- **Editing existing cells:** not supported by the API. `replace_block` swaps the entire table; the new one can be populated only by also using `add_markdown_content` (delete the old table with `delete_blocks`, then append a new markdown table). If the user asks to "edit cell B2 of my table", explain the constraint and offer: @@ -216,8 +219,8 @@ Notice box themes (`theme`): | Embed a live status from a board | `update_block` with column_value insert in delta_format | See delta-format-cheatsheet.md | | Add a callout box with content | Two `create_block` calls (notice_box, then child) | Cannot inline in one call | | Change a callout box theme | `replace_block` (notice_box) + recreate children | Theme immutable; children orphaned by replace | -| Swap an image source | `replace_block` (image) | URL / asset_id immutable | -| Add a Slack-style threaded comment | `add_comment` with `parent_update_id` | parent_update_id from include_comments | +| Swap an image source | `replace_block` (image) | URL / asset_id immutable; pass `after_block_id` to keep the position | +| Add a threaded comment | `add_comment` with `parent_update_id` | parent_update_id from include_comments | | Highlight a specific phrase with a comment | `add_comment` with `block_id` + `selection_from` + `selection_length` | Text-only blocks | -| Remove an embedded board | `delete_block` (BOARD type) | No way to create or update embeds | +| Remove an embedded board | `delete_blocks` (`block_ids: [""]`) | No way to create or update embeds | | Rename the doc | `set_name` | One operation, separate from block ops | diff --git a/skills/monday-docs-collaborator/references/create-modes.md b/skills/monday-docs-collaborator/references/create-modes.md index 5d329d9..6cd8762 100644 --- a/skills/monday-docs-collaborator/references/create-modes.md +++ b/skills/monday-docs-collaborator/references/create-modes.md @@ -24,7 +24,7 @@ Triggers that escalate to active mode: Resolution chain (name -> ID, never ask the user for IDs): - Item name -> `get_board_items_page` with `searchTerm` scoped to the named board -- Board name -> `search` with `searchType: BOARD` +- Board name -> `search` with `searchType: "BOARD"` and `searchTerm` - Owner name -> `list_users_and_teams` with `name:` (scoped per cross-skill rule) - Ambiguous match -> ask once with the top 3 candidates; do not silently pick @@ -44,5 +44,5 @@ Starting points when the user names a use case. Extend freely; they are examples - Markdown headings (`#`, `##`, `###`) map to LARGE_TITLE / MEDIUM_TITLE / SMALL_TITLE blocks. - Markdown tables work and the cells will be populated with the values you put in. **This is the only way to get pre-filled table content.** Cell-level API population after creation is not supported. -- Markdown images and links work. For asset-based images (uploaded files in monday), use `update_doc` with `create_block` and `block_type: "image"` plus `asset_id` after creation - markdown cannot reference assets. +- Markdown images and links work. Markdown cannot reference monday assets: for an image block, use `update_doc` `create_block` with `block_type: "image"` and either `public_url` or `asset_id`. An `asset_id` must already exist - the `assetId` in an item's file column, or the `asset_id` that `finalize_asset_upload` returns after `get_asset_upload_url` (only when the client can PUT the file itself). Do not use the `public_url` from `get_assets` as an image source: it expires after an hour. - Markdown does not have notice_box, layout, embed, divider-with-spacing, mention, or live column-value syntax. Add those via `update_doc` after the doc is created. diff --git a/skills/monday-docs-collaborator/references/delta-format-cheatsheet.md b/skills/monday-docs-collaborator/references/delta-format-cheatsheet.md index 80217cd..48dfe8b 100644 --- a/skills/monday-docs-collaborator/references/delta-format-cheatsheet.md +++ b/skills/monday-docs-collaborator/references/delta-format-cheatsheet.md @@ -5,7 +5,7 @@ ## The three rules 1. **Always end with `{insert: {text: "\n"}}`.** No exceptions. The terminator is mandatory; the API rejects deltas without it. -2. **Each operation is one insert.** No update / delete / retain ops. To change content, send a fresh delta_format and the API replaces the entire block content. +2. **Each operation is one insert.** No update / delete / retain ops. To change content, send a fresh `delta_format` and the API replaces the entire block content. 3. **Three insert types:** - `{insert: {text: "..."}}` - plain or styled text. - `{insert: {mention: {id, type}}}` - inline mention of a user, doc, or board. @@ -35,7 +35,8 @@ Supported attributes (all optional, all apply to text inserts only): | `link` | string | URL; the text is the link label | | `color` | string | text color (CSS-style or named) | | `background` | string | background highlight color | -| `comments` | array of update IDs | anchors comments to this text insert. Preserve when editing blocks that have existing comments - clean rewrites detach comments. | + +> **Important (comment anchors):** The `update_doc` write schema accepts **only** the 8 attributes above (`additionalProperties: false`). Do **not** include a `comments` attribute in `delta_format` — it is ignored, and cannot keep the anchor. Because `update_block` replaces the entire delta and detaches block-anchored comments, warn the user before rewriting a block that has anchored comments, or leave the block as is and add content beside it with `add_markdown_content` / `create_block`. Combine attributes: @@ -51,7 +52,7 @@ Combine attributes: Tag a user, doc, or board inline. Mention inserts ignore `attributes` (do not bold, italicize, or color them). ```json -{ "insert": { "mention": { "id": 38288909, "type": "USER" } } } +{ "insert": { "mention": { "id": "", "type": "USER" } } } ``` Three mention types: @@ -60,18 +61,18 @@ Three mention types: |---|---|---| | `USER` | numeric user ID | `list_users_and_teams` with `name: ""` | | `DOC` | doc's `object_id` | `read_docs` to find the target doc, use the `object_id` field | -| `BOARD` | numeric board ID | `search` with `searchType: "BOARD"`, or the user provides it | +| `BOARD` | numeric board ID | `search` with `searchType: "BOARD"` and `searchTerm`, or the user provides it | Always pass `name` (or `userIds`) to `list_users_and_teams`. The unfiltered call returns the entire account user list and breaks token limits on real tenants. -Example - "Hey @daniel, the @Q3-Plan doc is ready": +Example - "Hey @daniel, the @Q3-Plan doc is ready" (substitute real numeric IDs from `list_users_and_teams` and `read_docs`): ```json [ { "insert": { "text": "Hey " } }, - { "insert": { "mention": { "id": 48202303, "type": "USER" } } }, + { "insert": { "mention": { "id": "", "type": "USER" } } }, { "insert": { "text": ", the " } }, - { "insert": { "mention": { "id": 18234567890, "type": "DOC" } } }, + { "insert": { "mention": { "id": "", "type": "DOC" } } }, { "insert": { "text": " doc is ready." } }, { "insert": { "text": "\n" } } ] @@ -82,28 +83,28 @@ Example - "Hey @daniel, the @Q3-Plan doc is ready": Embed the current value of a board column on a specific item. Renders live every time the doc is opened. Enables dashboards-as-paragraphs. ```json -{ "insert": { "column_value": { "item_id": 11890636850, "column_id": "color_mm2x25ey" } } } +{ "insert": { "column_value": { "item_id": "", "column_id": "" } } } ``` -`item_id` accepts string or number. `column_id` is a string (e.g. `"status"`, `"date4"`, `"color_mm2x25ey"`). +`item_id` accepts string or number. Use `column_id` exactly as `get_board_info` returns it (for example, `"status"` on older boards or `"color_mk..."` on newer ones). Resolution rules: -- Validate `item_id` exists via `get_board_items_page` or `get_full_board_data`. +- Validate `item_id` exists via `get_board_items_page` (`boardId`, `itemIds`, `includeColumns: true`). - Validate `column_id` matches a real column on the item's board via `get_board_info`. - Wrong column IDs render as empty space - silent failure. - The viewer's permissions on the source board apply. Private boards mean private embeds. -Example - status report paragraph with live status: +Example - status report paragraph with live status (substitute real IDs from `get_board_info` and `get_board_items_page`): ```json [ { "insert": { "text": "Q3 plan is currently " } }, - { "insert": { "column_value": { "item_id": 11890636850, "column_id": "color_mm2x25ey" } } }, + { "insert": { "column_value": { "item_id": "", "column_id": "" } } }, { "insert": { "text": ", owned by " } }, - { "insert": { "column_value": { "item_id": 11890636850, "column_id": "multiple_person_mm2x4gzh" } } }, + { "insert": { "column_value": { "item_id": "", "column_id": "" } } }, { "insert": { "text": ", due " } }, - { "insert": { "column_value": { "item_id": 11890636850, "column_id": "date_mm2x10qd" } } }, + { "insert": { "column_value": { "item_id": "", "column_id": "" } } }, { "insert": { "text": "." } }, { "insert": { "text": "\n" } } ] @@ -121,7 +122,7 @@ When you read a doc back, column_value embeds appear in storage as `macro` blots "macro": { "type": "COLUMN_VALUE", "macroId": "...", - "macroData": { "itemId": 11890636850, "columnId": "color_mm2x25ey" } + "macroData": { "itemId": "", "columnId": "" } } } } @@ -213,7 +214,7 @@ To toggle a checkbox: ```json [ { "insert": { "text": "See the " } }, - { "insert": { "text": "design doc" }, "attributes": { "link": "https://monday.monday.com/docs/123456" } }, + { "insert": { "text": "design doc" }, "attributes": { "link": "https://.monday.com/docs/" } }, { "insert": { "text": " for details." } }, { "insert": { "text": "\n" } } ] @@ -223,9 +224,9 @@ To toggle a checkbox: ```json [ - { "insert": { "mention": { "id": 38288909, "type": "USER" } } }, + { "insert": { "mention": { "id": "", "type": "USER" } } }, { "insert": { "text": " is owning, current status: " } }, - { "insert": { "column_value": { "item_id": 11890636850, "column_id": "color_mm2x25ey" } } }, + { "insert": { "column_value": { "item_id": "", "column_id": "" } } }, { "insert": { "text": "\n" } } ] ``` @@ -292,9 +293,9 @@ When the skill creates a doc in **passive scaffold mode** (the default, before u ## Anti-patterns - things that look reasonable but fail -- **Forgetting the terminator.** Every delta_format MUST end with `{insert: {text: "\n"}}`. Even short ones. +- **Forgetting the terminator.** Every `delta_format` MUST end with `{insert: {text: "\n"}}`. Even short ones. - **Mention with attributes.** `attributes` on a mention insert is ignored. Use formatting on adjacent text inserts instead. - **column_value in a code block.** Code blocks render the column_value insert as literal text, not as a live embed. Use a regular text block for embeds. -- **Mention id as a string when the API expects a number** - the schema accepts string OR number, but be consistent. User IDs from `list_users_and_teams` come back as numeric strings; cast to number before sending if mixing. +- **Non-numeric mention id** - the schema accepts a string or a number, and the tool converts it to a number. A string that is not a number (a name, an email) fails the operation. Use the numeric ID from `list_users_and_teams`, `read_docs` or `search`. - **Multiple terminators.** Only one `{insert: {text: "\n"}}` at the end. Embedded `\n` characters inside other inserts are fine for line breaks within the block, but the terminator must be the last entry. -- **Trying to delete a mention by clearing the text around it.** `update_block` replaces the whole delta. To remove a mention, omit it from the new delta_format and re-send the rest. +- **Trying to delete a mention by clearing the text around it.** `update_block` replaces the whole delta. To remove a mention, omit it from the new `delta_format` and re-send the rest. diff --git a/skills/monday-docs-collaborator/references/errors.md b/skills/monday-docs-collaborator/references/errors.md index 42b9059..566dd96 100644 --- a/skills/monday-docs-collaborator/references/errors.md +++ b/skills/monday-docs-collaborator/references/errors.md @@ -4,13 +4,13 @@ Detail for "Surface errors with remediation" in `SKILL.md`. Common failures and how to remediate: -- **"block_id must be UUID"** - the ID is malformed (not a valid UUID). The API validates UUID format before lookup. Re-read with `include_blocks: true` and use the actual block IDs returned. +- **Malformed block_id** - the ID is not one `read_docs` returned (block IDs are UUIDs). Re-read with `include_blocks: true` and use the actual block IDs returned. - **"Block not found" / no-op** - the block_id is well-formed but stale. Re-read with `include_blocks: true` and retry. Block IDs change when blocks are deleted and recreated (e.g. via `replace_block`). -- **"Cannot use update_block on a divider / table / image"** - schema mismatch. Switch to `replace_block`. +- **`update_block` on a divider / table / image** - `update_block` content only accepts `block_content_type` `text`, `code` or `list_item`. Switch to `replace_block`. - **"parent_block_id references a block not yet created"** - notice_box nesting attempted in the same call. Split into two calls. -- **"CellLimitExceededException" on `create_doc location=item`** - the target doc column cell is already populated (1-doc-per-cell limit). Fall back to a workspace-level doc with a bi-directional DOC mention cross-link to the existing attached doc. See the Step 1 preflight in `SKILL.md` ("Workflow: Create a doc"). +- **`existing_doc_found: true` on `create_doc location=item`** - the target doc column cell is already populated (1-doc-per-cell limit). The tool returns the existing doc unchanged; your name and markdown were not applied. Append to it with `add_markdown_content`, or fall back to a workspace-level doc with a bi-directional DOC mention cross-link to the existing attached doc. See the Step 1 preflight in `SKILL.md` ("Workflow: Create a doc"). - **Live embed renders blank** - either the item / column was deleted, or the viewer lacks permission on the source board. Verify with `get_board_info`. If it's a permissions issue, suggest moving the source data to a less-restricted board. - **INTERNAL_SERVER_ERROR on a long `create_doc` or `add_markdown_content`** - large markdown bodies, especially with many tables, fail on import, and `create_doc` can leave a partly created doc behind. Do not resend the whole body. Call `read_docs` to see what landed, then append the rest in chunks of a few sections each, one `add_markdown_content` operation per `update_doc` call (several in one call can interleave). For a new doc, create it with the first section only and append the rest. -- **"Plan limit reached"** on `create_doc` - Free / Basic 3-doc cap. Suggest upgrading to Standard+ or deleting an unused doc. +- **Plan limit** on `create_doc` - Free / Basic 3-doc cap. Suggest upgrading to Standard+ or deleting an unused doc. - **"Cannot create BOARD / WIDGET / DOC / GIPHY block"** - these block types have no public-create path. Suggest the closest alternative (a markdown link to the board, or `add_markdown_content` with a board URL). -- **Orphan comment anchor** - if `read_docs` shows `attributes.comments: []` on a block but the comment is missing from the comments array, the comment was deleted but the anchor remained. Separately update the block's delta to drop the `comments` attribute for full cleanup. +- **Orphan comment anchor** - if `read_docs` shows `attributes.comments: []` on a block but the comment is missing from the comments array, the comment was deleted while the anchor remained. Rewriting the block with `update_block` (using only valid formatting attributes — never send a `comments` attribute in write deltas) clears the stale anchor. diff --git a/skills/monday-docs-collaborator/references/read-rendering.md b/skills/monday-docs-collaborator/references/read-rendering.md index f575690..4b85e5b 100644 --- a/skills/monday-docs-collaborator/references/read-rendering.md +++ b/skills/monday-docs-collaborator/references/read-rendering.md @@ -4,6 +4,6 @@ Detail for Step 3 of "Workflow: Read a doc" in `SKILL.md`. For read responses to "show me / what's in / read this doc" prompts: -- **Always resolve mentions.** Map every USER mention id to a display name (via cached `list_users_and_teams` or a scoped lookup). Map every DOC mention to its doc name. Map every BOARD mention to its board name. Render inline as `**@Alex Polonsky**` (or similar) rather than `@{USER-38288909}`. +- **Always resolve mentions.** Map every USER mention id to a display name (via cached `list_users_and_teams` or a scoped lookup). Map every DOC mention to its doc name. Map every BOARD mention to its board name. Render inline as `**@Alex Smith**` (or similar) rather than `@{USER-}`. - **Resolve embeds when data is cached or cheap to fetch.** If the doc references items / columns already touched in the conversation, use the cached value. If not, fetch with `get_board_items_page` scoped to the specific items + columns. Render as the resolved column value ("**Working on it**", "**No value**", "**2026-05-15**") inline. Skip resolution only if it would require many extra MCP calls for a long doc. - **Always keep the structured enumeration table as a secondary affordance.** List every inline non-text element (mentions, embeds, notice_boxes, code blocks, tables) with block IDs and IDs. Useful for downstream edit operations and for users who want to target a specific element. diff --git a/skills/monday-docs-collaborator/references/rich-content.md b/skills/monday-docs-collaborator/references/rich-content.md index 0a5e6fe..b12c4af 100644 --- a/skills/monday-docs-collaborator/references/rich-content.md +++ b/skills/monday-docs-collaborator/references/rich-content.md @@ -8,7 +8,7 @@ The `table` block type is supported but constrained: - **Pre-filled tables**: only via `add_markdown_content` or the initial `create_doc` markdown body. Markdown table syntax populates cells in one shot. - **Empty tables via `create_block`**: possible, but cells cannot be populated via the API after creation. The user has to fill cells from the monday UI. -- **Restructuring (changing row / column count or widths)**: `replace_block` - the new table can be pre-filled if you replace it via `add_markdown_content` instead, by deleting the old table and appending a new markdown table after the deletion target. +- **Restructuring (changing row / column count or widths)**: `replace_block` - the new table can be pre-filled if you replace it via `add_markdown_content` instead, by deleting the old table (`delete_blocks`) and appending a new markdown table after the deletion target. When the user asks to "edit cell B2", explain the constraint and offer the closest workaround: rewrite the whole table via markdown. @@ -56,9 +56,9 @@ Use cases worth scaffolding: Resolution rules: -- Validate `item_id` exists via `get_board_items_page` or `get_full_board_data` before writing. +- Validate `item_id` exists via `get_board_items_page` (`boardId`, `itemIds`, `includeColumns: true`) before writing. - Validate `column_id` matches a real column on the item's board via `get_board_info`. Wrong column IDs produce silent rendering gaps - the embed shows as empty space. -- **Always use the board-specific status column ID** (e.g. `color_mm2x25ey`), never a generic literal like `"status"`. Cross-skill rule. +- **Use the column ID exactly as `get_board_info` returns it** (for example, `status` on older boards or `color_mk...` on newer ones) — never guess without checking `get_board_info`. - Be careful with private boards: embedded column values respect board permissions, so a viewer without access to the source board sees nothing. ## Comments @@ -71,6 +71,6 @@ Resolution rules: Threading: pass `parent_update_id` (the comment's update ID, returned by `add_comment` or `read_docs` with `include_comments: true`) to reply. -Comment body uses HTML, not markdown. To tag a user in a comment, do not put `@` in the body - use `mentions_list` with a JSON array: `[{"id":"38288909","type":"User"}]`. Valid types: `User`, `Team`, `Board`, `Project`. +Comment body uses HTML, not markdown. To tag a user in a comment, do not put `@` in the body - use `mentions_list` with a JSON array: `[{"id":"","type":"User"}]`. Valid types: `User`, `Team`, `Board`, `Project`. -Deleting a comment via `delete_update` does NOT auto-clean the anchored reference on the host block's text insert (`attributes.comments` still lists the dead update_id). For full cleanup, separately update the block's delta to drop the `comments` attribute. +Deleting a comment is not available through the typed tools; use `all_monday_api` with the `delete_update` mutation only if the user insists. Note that deleting a comment does not auto-clean its anchored reference on the host block; rewriting the block with `update_block` (without any `comments` attribute, which is ignored) clears the stale anchor. diff --git a/skills/monday-forms-builder/SKILL.md b/skills/monday-forms-builder/SKILL.md index f064ccd..dd426af 100644 --- a/skills/monday-forms-builder/SKILL.md +++ b/skills/monday-forms-builder/SKILL.md @@ -14,9 +14,8 @@ description: | license: MIT metadata: author: monday.com - version: "0.1.2" + version: "0.1.3" --- - # Forms Builder Create, edit, and publish monday.com WorkForms. Every WorkForm is paired with a backing board: each form submission becomes a new item on that board, with the form's questions mapped to the board's columns. The form is the front door, the board is the destination. @@ -27,13 +26,13 @@ Create, edit, and publish monday.com WorkForms. Every WorkForm is paired with a ## Plan-tier note -Forms ship in every monday plan, including Free and Basic. **WorkForms branding ("Powered by monday.com") shows by default and can only be removed on Pro plans and above.** If a user asks to remove the branding, check the plan first or warn them: it requires `updateAppearance` with `hideBranding: true` and will silently fail on Free / Basic / Standard. +Forms ship in every monday plan, including Free and Basic. **WorkForms branding ("Powered by monday.com") shows by default and can only be removed on Pro plans and above.** If a user asks to remove the branding, check the plan first (`get_user_context` returns `account.tier`) or warn them: it requires `updateAppearance` with `form.appearance.hideBranding: true` and will silently fail on Free / Basic / Standard. ## Workflow: Create a form ### Step 1: Confirm the destination workspace -Forms must live in a workspace. Ask if not specified, or use the user's primary workspace. Call `list_workspaces` if you need to choose. The workspace ID is the only required parameter for `create_form`. +Forms must live in a workspace. Ask if not specified. `get_user_context` returns the user's favorite workspaces; call `list_workspaces` if you need to choose from all of them. The workspace ID is the only required parameter for `create_form`. ### Step 2: Decide the form's purpose, then call `create_form` @@ -47,13 +46,13 @@ The form's purpose dictates the question set. Common shapes: Call `create_form` with: - `destination_workspace_id` (required) -- `destination_name` (board name; defaults to the form title if omitted) +- `destination_name` (the backing board's name) - `destination_folder_id` or `destination_folder_name` if the user wants the board placed in a specific folder -- `board_kind` defaults to `public`; use `private` if the form's responses are sensitive +- `board_kind` (`public`, `private` or `share`); use `private` if the form's responses are sensitive -Capture the returned `formToken` - you need it for every subsequent edit. +Capture the returned `form_token` (and `board_id`) - every other forms tool takes it as `formToken`. -**`create_form` does not accept a form title parameter.** The form header defaults to "New Form" regardless of `destination_name` (which only names the backing board). Always follow `create_form` with an `update_form` call using `action: "updateFormHeader"` to set a meaningful title (and optional subtitle / description) before showing the URL to the user. Skipping this leaves every form labeled "New Form" in the WorkForms UI - confusing for end users and for the form owner browsing their forms list. +**`create_form` does not accept a form title parameter.** The form header defaults to "New Form" regardless of `destination_name` (which only names the backing board). Always follow `create_form` with an `update_form` call using `action: "updateFormHeader"` to set `form.title` (and optional `form.description`) before showing the URL to the user. Skipping this leaves every form labeled "New Form" in the WorkForms UI - confusing for end users and for the form owner browsing their forms list. ### Step 3: Build the question set @@ -64,7 +63,7 @@ Use `form_questions_editor` with `action: "create"` for each question. Decide qu | Free text, single line | `ShortText` | | Free text, multi-line | `LongText` | | Yes/no | `Boolean` | -| One-of-many | `SingleSelect` (set `display: "Dropdown"` for long lists, `Vertical` for short) | +| One-of-many | `SingleSelect` (set `settings.display: "Dropdown"` for long lists, `"Vertical"` for short) | | Many-of-many | `MultiSelect` | | Numeric | `Number` | | Money / quantity / score | `Number` | @@ -91,38 +90,39 @@ For `SingleSelect` and `MultiSelect`, `options` is required. Each option needs a ### Step 4: Show the user the question set before publishing -After all questions are created, summarize them in a markdown table or a `show-table` widget pointed at the backing board. Include question text, type, and required-yes/no. Ask the user to confirm or edit before activating the form. +After all questions are created, summarize them in a Markdown table (question text, type, required yes/no, and options if applicable). Ask the user to confirm or edit before sharing the form. ### Step 5: Confirm public access and share -Forms are created **active by default**. The form URL works the moment `create_form` returns. If the user wants a draft state (questions still being shaped), call `update_form` with `action: "deactivate"` immediately, finish the questions, then `activate` when ready. Otherwise, share the URL as-is. The form URL follows the pattern: +Forms are created **active by default**. The form URL works the moment `create_form` returns. If the user wants a draft state (questions still being shaped), call `update_form` with `action: "deactivate"` immediately, finish the questions, then `activate` when ready. Otherwise, share the URL as-is. + +`create_form` and `get_form` do not return the public form URL (`get_form` returns `features.shortenedLink.url` once the URL is shortened). Build it from the token. The `?r=` value is the account's data region; `use1` is the example `get_form` documents: ``` https://forms.monday.com/forms/{formToken}?r=use1 ``` -Include both the form URL and the backing board URL in the response. The user will want both - the form for sharing, the board for monitoring submissions. +Include both the form URL and the backing board URL (`get_board_info` with the `board_id` returns its `url`) in the response. The user will want both - the form for sharing, the board for monitoring submissions. ### Step 6: Suggest follow-ups End with 2-3 next-step suggestions: -- **"Want me to switch the layout from OneByOne to Classic?"** - new forms default to OneByOne (one question per screen, Next navigation). Classic (all questions on a single scrolling page) is the better default for most operational and internal forms. Surface this choice every time. The layout change cannot be applied via MCP today (see below); the suggestion points the user to Form Settings -> Layout in the monday UI. +- **"Want the form on a single scrolling page (Classic) instead of one question per screen (OneByOne)?"** - Classic is the better default for most operational and internal forms. Surface this choice every time. The MCP tools cannot change it (see below); the suggestion points the user to Form Settings -> Layout in the monday UI. - "Want me to shorten the form URL?" - "Should I set a password on the form?" -- "Want me to send this link to a Slack channel?" - "Should I set a submission limit or close date?" - "Want to remove the WorkForms branding? (Pro+ only.)" -**Known MCP gap: form layout cannot be changed via API.** `update_form` with `action: "updateAppearance"` accepts `layout.format` without error but the value is silently ignored - the form stays OneByOne. Confirmed across multiple parameter combinations. Do not attempt the API call and report success; the change will not persist. Direct the user to Form Settings -> Layout in the form editor and walk them through it in plain language. Track this gap with the monday MCP team. +**Layout is two settings, and the MCP tools reach only one.** `update_form` `action: "updateAppearance"` sets the frame with `form.appearance.layout.type`: `"CARD"` renders the form inside a bordered card that scrolls within the card, `"FLAT"` renders it edge-to-edge and the whole page scrolls. Optional `alignment` (`FullLeft`, `Left`, `Center`, `Right`, `FullRight`) and `direction` (`LtR`, `Rtl`) sit beside it. The question flow (OneByOne or Classic) has no parameter in `update_form`, so it cannot be changed via MCP: direct the user to Form Settings -> Layout in the form editor. Do not present a CARD/FLAT change as a OneByOne/Classic change. ## Workflow: Edit an existing form ### Step 1: Resolve the formToken -If the user pastes a form URL, extract the token: `https://forms.monday.com/forms/{TOKEN}?r=use1` -> `{TOKEN}` is the alphanumeric string between `/forms/` and `?`. +If the user pastes a form URL, extract the token: `https://forms.monday.com/forms/{TOKEN}?r=...` -> `{TOKEN}` is the alphanumeric string between `/forms/` and `?` (or the end of the URL). -If the user names the form, search via the `search` tool with `searchType: "BOARD"` to find the backing board, then call `get_form` against any candidate token. (The MCP currently has no direct form-search tool; the form is reachable through the board it backs. Mark this as a known gap if it blocks the user.) +If the user names the form, call `search` with `searchType: "BOARD"` and `searchTerm: "
"` to find the backing board. The results carry the board's `id` and `url`, not a formToken, and the MCP has no form-search tool: ask the user for the form URL and mark this as a known gap if it blocks them. ### Step 2: Fetch current state @@ -133,8 +133,8 @@ Call `get_form` with the formToken. This returns questions, structure, appearanc Pick the right tool: - **Add / update / delete a single question:** `form_questions_editor`. -- **Reorder questions:** `update_form` with `action: "updateQuestionOrder"` and the full ordered array of question IDs. -- **Header (title and description):** `update_form` with `action: "updateFormHeader"`. +- **Reorder questions:** `update_form` with `action: "updateQuestionOrder"` and `form: {questions: [{"id": ""}, {"id": ""}, ...]}` (objects with required `id` and optional `page_block_id`, with every existing question included). +- **Header (title and description):** `update_form` with `action: "updateFormHeader"` (`form.title` and optional `form.description`). - **Branding, layout, colors, logo:** `update_form` with `action: "updateAppearance"`. - **Submission rules (anonymous, response limit, close date, login required, captcha):** `update_form` with `action: "updateFeatures"`. - **Activate / deactivate / shorten URL / set password:** corresponding actions. @@ -145,25 +145,25 @@ Plain-language summary: what changed, what stayed the same, and the form URL. Do ## Common edits -**Add a question to the end:** `form_questions_editor` with `action: "create"`, no `insert_after_question_id`. The question appends. +**Add a question to the end:** `form_questions_editor` with `action: "create"`, no `insert_after_question_id`. The question appends. `insert_after_question_id: null` puts it first. **Insert a question between two existing ones:** call `get_form` to get the predecessor's ID, then create with `insert_after_question_id: ""`. -**Make a field required:** `form_questions_editor` with `action: "update"`, the question's `id`, the existing `type`, and `required: true`. The `type` field must always be sent on updates. +**Make a field required:** `form_questions_editor` with `action: "update"`, `questionId: ""`, and `question: {type: "", required: true}`. `question.type` must always be sent on updates. **Update a select question's options without losing past responses:** call `get_form` first, copy each existing option's `value` into the update, then add or modify only the labels. Omitting an existing option deletes it. -**Show / hide a question conditionally:** use `show_if_rules` on the question. Rules are AND/OR-composable with conditions referencing other question IDs and answer values. +**Show / hide a question conditionally:** use `show_if_rules` on the question. Rules are **OR-only** (every operator — top-level, rule-level, and condition-level — must be `"OR"`). Each condition has the shape `{building_block_id: "", operator: "OR", values: [""]}`. -**Reorder questions:** `update_form` with `action: "updateQuestionOrder"` and the full ordered list - every existing question ID must appear, even unchanged ones. After the reorder lands, call `get_form` to re-sync question IDs - any `PAGE_BLOCK` (section heading) IDs are reassigned by the platform on reorder (e.g. `page_block__classic_default` becomes `page_block77dy0px4`). Cached PAGE_BLOCK IDs will 404 on the next edit if you skip the re-sync. +**Reorder questions:** `update_form` with `action: "updateQuestionOrder"` and `form: {questions: [{"id": ""}, {"id": ""}, ...]}` (include optional `page_block_id` if using pages) - every existing question ID must appear, even unchanged ones. After the reorder lands, call `get_form` to re-sync question IDs - any `PAGE_BLOCK` (section heading) IDs are reassigned by the platform on reorder (e.g. `page_block__classic_default` becomes `page_block77dy0px4`). Cached PAGE_BLOCK IDs will 404 on the next edit if you skip the re-sync. -**Sync question titles with column names:** `update_form` with `action: "updateFeatures"` and `monday.syncQuestionAndColumnsTitles: true`. Useful when the user is editing the backing board and wants the form to follow. +**Sync question titles with column names:** `update_form` with `action: "updateFeatures"` and `form.features.monday.syncQuestionAndColumnsTitles: true`. Useful when the user is editing the backing board and wants the form to follow. -**Drop the WorkForms branding (Pro+):** `update_form` with `action: "updateAppearance"` and `appearance.hideBranding: true`. +**Drop the WorkForms branding (Pro+):** `update_form` with `action: "updateAppearance"` and `form.appearance.hideBranding: true`. -**Close the form to new responses:** `update_form` with `action: "deactivate"`. Reactivate with `action: "activate"`. To close on a date, use `updateFeatures` with `closeDate.enabled: true` and `closeDate.date: ""`. +**Close the form to new responses:** `update_form` with `action: "deactivate"`. Reactivate with `action: "activate"`. To close on a date, use `updateFeatures` with `form.features.closeDate.enabled: true` and `form.features.closeDate.date: ""`. -**Password-protect the form:** `update_form` with `action: "setFormPassword"` and `formPassword: ""`. Communicate the password separately - it does not appear in the form URL. +**Password-protect the form:** `update_form` with `action: "setFormPassword"` and `formPassword: ""`. Communicate the password separately - it does not appear in the form URL. To remove it, `updateFeatures` with `form.features.password.enabled: false`. ## Smart defaults @@ -174,29 +174,24 @@ When the user does not specify all values: - **Required flag:** false by default, except for the obvious primary identifier (email on a lead form, title on a bug report). - **Question order:** the order the user listed them, top to bottom. - **Form is active after creation:** yes - `create_form` returns an active, publicly-accessible form. If the user wants to preview before responses can come in, call `deactivate` immediately and reactivate when ready. -- **Form title:** `create_form` defaults the header to "New Form". Always set the title explicitly via `update_form` `action: "updateFormHeader"` after creation - use the user's stated form name (or, if missing, the form's purpose, e.g. "Bug Intake"). State the title in your confirmation. -- **Layout:** the platform default is `OneByOne` (card-per-question). For most operational and internal forms, `Classic` (single scrolling page) is the better default - surface this in Step 6 follow-ups, do not silently rely on OneByOne. The choice is not reachable via MCP today; point the user to Form Settings -> Layout in the form editor. +- **Form title:** `create_form` defaults the header to "New Form". Always set `form.title` explicitly via `update_form` `action: "updateFormHeader"` after creation - use the user's stated form name (or, if missing, the form's purpose, e.g. "Bug Intake"). State the title in your confirmation. +- **Layout:** new forms default to OneByOne (card-per-question). For most operational and internal forms, Classic (single scrolling page) is the better default - surface this in Step 6 follow-ups, do not silently rely on OneByOne. The choice is not reachable via MCP; point the user to Form Settings -> Layout in the form editor. - **Branding:** leave WorkForms branding on by default; mention Pro+ removal as a follow-up rather than auto-toggling it. ## Error prevention and remediation - **WorkForms cannot update existing items.** If asked, redirect to either an internal item-update field, a connected-boards question that links to an existing item, or a separate update-tracking workflow. Do not promise behavior the platform does not support. - **Form URL returns "form is not available":** the form has been deactivated, hit a response limit, or passed a close date. Check `get_form` features state. Reactivate with `update_form` `action: "activate"`, raise the response limit, or extend the close date. -- **`updateQuestionOrder` rejects the call:** the questions array must include every existing question ID. Call `get_form` first, list all IDs, then send the full ordered list. +- **`updateQuestionOrder` rejects the call:** `form.questions` must be an array of `{"id": ""}` objects containing every existing question ID. Call `get_form` first, collect all IDs, then send the full ordered array. - **PAGE_BLOCK question IDs change after `updateQuestionOrder`.** The platform reassigns IDs for `PAGE_BLOCK` section-heading questions on every reorder (e.g. `page_block__classic_default` becomes `page_block77dy0px4`). Always call `get_form` immediately after `updateQuestionOrder` and refresh any cached PAGE_BLOCK IDs before the next edit, otherwise subsequent `form_questions_editor` calls referencing the old ID 404. - **Select option deletion is destructive:** updating a `SingleSelect` or `MultiSelect` and omitting an existing option deletes it, breaking past responses that used that option. Always send all options when editing. - **`hideBranding: true` does not stick:** the account is on a plan below Pro. Tell the user the constraint; do not retry. - **Question type cannot change after creation:** to "convert" a question type, delete and recreate. Past responses for the original question are lost. Confirm with the user before deleting. -- **`existing_column_id`:** only set when the user explicitly asks the question to point at a specific board column. Otherwise let the form auto-create a column to keep wiring clean. - -## When to use MCP UI widgets - -Use `show-table` selectively, not by default: -- **Before publish:** when the question set is more than 5 items, render the backing board with `show-table` so the user can scan question-to-column mapping in one view. Plain-text summary is cleaner for shorter sets. -- **After publish:** if the user asks "what came in this week", `show-table` against the backing board with a date filter is the right answer. Plain-text confirmations for activation, deactivation, and single-question edits. +## Presenting form structure and responses -Do not use `show-table` to confirm a single edit - the form URL plus a one-line confirmation is enough. +- **Before publish:** summarize the question set (question text, type, required flag) in a Markdown table alongside the form and backing board URLs. If `show-table` is available and the set has more than 5 questions, render the backing board with it so the user sees the question-to-column mapping. +- **After publish:** if the user asks "what came in this week", render the backing board with `show-table` and a date filter when it is available; otherwise read submissions with `get_board_items_page` (`includeColumns: true`, a date filter) and summarize them in a Markdown table with the board URL. For activation, deactivation, and single-question edits, a one-line confirmation plus the form URL is enough - no widget. ## Be conservative on destructive operations @@ -212,17 +207,19 @@ Single-question creates and non-destructive edits do not need extra confirmation ## Tools used - `list_workspaces` - locate the destination workspace if not provided -- `create_form` - create the form and its backing board (returns `formToken`) +- `create_form` - create the form and its backing board (returns `form_token` and `board_id`) - `get_form` - read current form state by formToken (always before editing) - `update_form` - 11 actions covering header, appearance, accessibility, features, question order, tags, activation, password, URL shortening - `form_questions_editor` - create / update / delete a single question -- `search` - find a backing board by name when only the form's purpose is known -- `get_user_context` - fall back to the user's primary workspace when none is specified -- `show-table` (selectively) - render the backing board for question-set review or response browsing +- `search` - find a backing board by name (`searchType: "BOARD"`, `searchTerm`) when only the form's purpose is known +- `get_board_info` - read the backing board's `url` +- `get_board_items_page` - read submissions from the backing board to summarize responses +- `get_user_context` - favorite workspaces, and `account.tier` for the branding plan check +- `show-table` (when available) - show the backing board for question-set review or response browsing ## Additional notes -- A `formToken` is the alphanumeric segment of a form URL: `https://forms.monday.com/forms/{TOKEN}?r=use1`. Treat it as the form's primary key. +- A `formToken` is the alphanumeric segment of a form URL (e.g., `https://forms.monday.com/forms/{TOKEN}?r=use1`, where the `?r=...` region parameter varies by data region). Treat `formToken` as the form's primary key. - The backing board's items represent submissions. Editing a board column does not edit the form question - use `form_questions_editor` for the form side. The `monday.syncQuestionAndColumnsTitles` feature flag helps keep them in step. - Forms that require login (`features.requireLogin.enabled: true`) restrict submissions to monday.com users in the same account. - For multilingual forms, set `accessibility.language` via `update_form` `action: "updateAccessibility"`. Combine with `features.ai_translate.enabled: true` for AI-generated translations. diff --git a/skills/monday-onboard-to-monday/SKILL.md b/skills/monday-onboard-to-monday/SKILL.md index 25ebb46..a01c218 100644 --- a/skills/monday-onboard-to-monday/SKILL.md +++ b/skills/monday-onboard-to-monday/SKILL.md @@ -11,9 +11,8 @@ description: | license: MIT metadata: author: monday.com - version: "0.1.0" + version: "0.1.1" --- - # Onboard to monday.com Get a brand-new monday.com user from "just connected" to a working board they recognize as their own, in one short conversation. The goal is a first win in minutes: a board built around the user's real work, with real items, one automation, and a clear next action. @@ -31,11 +30,11 @@ The board itself is built by `create_board` with a `creationPrompt` - monday des ### Step 1: Confirm this is a new user -Call `get_user_context`. +Call `get_user_context` (returns the user's name and title, the account's plan tier and trial status, their favorites, and up to 10 recently used boards - not a full list of workspaces or boards). To pick the workspace for the new board, call `list_workspaces` (the user's own workspaces come first). If you need the complete list of boards in a workspace, call `workspace_info` with `workspace_id`. -- Tell the user, in one line, which account and workspace they are connected to. +- Tell the user, in one line, who they are connected as and which workspace you will build in. - **New user** (trial or recently created account, few or no boards of their own): continue with Step 2. -- **Existing user** (the account already has boards they use): do not run onboarding. Say they already have boards set up, name a few of their most relevant ones, and offer to help with those instead (status update, add items, new board). +- **Existing user** (the account already has boards they use): do not run onboarding. Say they already have boards set up, name a few of their recent/favorite boards, and offer to help with those instead (status update, add items, new board). - **Unexpected account** (the user says it is not the right one, or expected boards are missing): stop and ask them to disconnect and reconnect the monday.com connector, choosing the right account. Note the plan tier and trial status for Step 6. @@ -67,25 +66,25 @@ If they change something, adjust and build. Do not re-confirm after small change ### Step 4: Create the board -1. **Check for a name collision.** Call `search` with the board name. If a board with that name exists, ask whether to use it or create the new one with a different name. -2. **Call `create_board`** with `boardName`, `boardKind: "public"` (or `"private"` if the user asked), the workspace from Step 1, and a `creationPrompt` that describes the board in plain language: what it tracks, the workflow stages, the fields each item needs, and the starter items. Leave the automation out - it is not created from the prompt; Step 6 adds it. Write the prompt from the agreed proposal, for example: +1. **Check for a name collision.** Call `search` with `searchType: "BOARD"` and `searchTerm: ""`. If a board with that name exists, ask whether to use it or create the new one with a different name. +2. **Call `create_board`** with `boardName`, `boardKind: "public"` (or `"private"` if the user asked), `workspaceId` (the workspace from Step 1, as a string), and a `creationPrompt` that describes the board in plain language: what it tracks, the workflow stages, the fields each item needs, and the starter items. Leave the automation out - it is not created from the prompt; Step 6 adds it. Write the prompt from the agreed proposal, for example: > A launch tracker for a marketing team planning a Q4 product launch. Work moves through To Do, In Progress, In Review, Done. Each task needs an owner, a due date, and a priority (Low, Medium, High, Critical). Starter tasks: Finalize messaging, Launch landing page, Partner email, Launch day checklist. -3. **If `create_board` fails or times out, do not call it again straight away** - the board may have been created. Call `search` for the board name first, and only retry if it does not exist. Re-sending creates duplicate boards. +3. **If `create_board` fails or times out, do not call it again straight away** - the board may have been created. Call `search` with `searchType: "BOARD"` and `searchTerm: ""` first, and only retry if it does not exist. Re-sending creates duplicate boards. ### Step 5: Check the result, fill gaps, and show the board `creationPrompt` gets most of the board right but not all. Call `get_board_info`, `get_board_items_page` (`includeColumns: true`), and `list_automations`, and compare with what you proposed: -- **Group order** - if a later or terminal group (e.g. "Done") is on top, new items land there. Move the first workflow stage to the top with `all_monday_api`: `update_group(board_id, group_id, group_attribute: relative_position_before, new_value: "") { id }`. +- **Group order** - if a later or terminal group (e.g. "Done") is on top, new items land there. Move the first workflow stage to the top with `all_monday_api`: `update_group(board_id, group_id, group_attribute: relative_position_before, new_value: "") { id }` (if a GraphQL mutation is rejected, check the live schema with `get_graphql_schema` / `get_type_details` if available). - **Columns** - if a key field is missing or has the wrong type (e.g. a website as `text` instead of `link`), add it with `create_column`. Do not rebuild the board. - **Items** - if starter items are missing, create them in one `create_items` call; if values you asked for are blank, fill them in one `update_items` call. Follow the monday-task-management column formats. Assign items to the current user only if they agreed. -- **Unrequested automations** - `create_board` can add automations nobody asked for (e.g. monday AI "categorize" rules that use AI credits). Mention them in one line and offer to turn them off. +- **Unrequested automations** - `create_board` can add automations nobody asked for (e.g. monday AI "categorize" rules that use AI credits). Mention them in one line and offer to turn them off (`manage_automations`, `action: "deactivate"`, with the id from `list_automations`; if one cannot be changed there, point the user to the board's Automations panel). If a write tool fails after a successful read, follow the monday-task-management rule: retry once, then stop and ask the user to reconnect the connector. Do not keep rebuilding. -**Show the board right away.** As soon as the columns and starter items are in place, call `show-table` with the new board's `boardId` so the user sees their board as an interactive table in the chat. Do not pass `filters`; show the whole board. Add one short line, e.g. "Here's your board - adding a starter automation next." Do not wait for the automation step. If `show-table` is unavailable or fails, share the board URL from the tool response instead and continue. +**Show the board right away.** As soon as the columns and starter items are in place, show it. If `show-table` is in your tool list, call it with the new board's `boardId` (as a string) so the user sees their board as an interactive table in the chat; do not pass `filters`. Otherwise, or if `show-table` fails, share the board URL from the `create_board` response with a concise Markdown list of the starter items (item name, group, status, due date). Add one short line, e.g. "Here's your board - adding a starter automation next." Do not wait for the automation step. ### Step 6: Add the starter automation @@ -98,18 +97,16 @@ Ask before creating it (it can be part of the Step 3 confirmation). ### Step 7: Hand over with a first win -The board is already on screen from Step 5 - do not call `show-table` again here. - -1. **Summarize in a few lines:** what was built, the automation (if created), and the board URL from the tool response. Do not repeat the items as a text list - the table already shows them. (If `show-table` failed in Step 5, list the starter items here instead.) +1. **Summarize in a few lines:** what was built, the automation (if created), and the board URL from the `create_board` response. Do not call `show-table` again here or repeat the items if Step 5 already showed them. 2. **Give one concrete thing to try right now,** phrased as something they can just say, using one of their own items: - "Try it: say **mark Finalize messaging as done**." - When they do, make the change (monday-task-management skill), then call `show-table` again so they see the board update. + When they do, make the change (`monday-task-management` skill), then call `show-table` again if you have it so they see the board update; otherwise re-read with `get_board_items_page` and confirm the new state in a short Markdown summary. Then offer, briefly, the habits that bring people back: - "Any time, ask me **what's overdue** or **give me a status update** on this board." -- "Want me to invite your teammates so they can work on this with you?" (only if they said it is for a team) +- "You can share the board link above with your teammates so they can collaborate on it with you." (only if they said it is for a team) Stop there. Do not chain further setup unless the user asks. @@ -128,16 +125,18 @@ Pick the one that fits the board, using its real column, label, and group names: ## Tools Used -- `get_user_context` - account, workspace, plan and trial status, and whether the user already has boards -- `search` - board name collision check, and checking whether a failed `create_board` actually created the board +- `get_user_context` - user, plan and trial status, favorites, and recently used boards +- `list_workspaces` - pick the workspace to build the board in +- `workspace_info` - list all boards in a workspace by `workspace_id` when checking full board coverage +- `search` - board name collision check (`searchType: "BOARD"`, `searchTerm`), and checking whether a failed `create_board` actually created the board - `create_board` - build the board from a `creationPrompt` - `get_board_info` - read back the generated columns, groups, and labels -- `get_board_items_page` - check the starter items' values +- `get_board_items_page` - check starter items and confirm updates after the user's first change - `all_monday_api` - reorder groups (`update_group`) when the first stage is not on top - `update_items` - fill starter-item values the generated board left blank - `create_column` - add a key column the generated board is missing - `create_items` - add the starter items if the generated board does not have them - `create_automation` - create the starter automation - `list_automations` - verify the automation's trigger and conditions -- `manage_automations` - deactivate an automation that was created wrong -- `show-table` - display the new board as soon as its items exist (Step 5), and again after the user's first change +- `manage_automations` - deactivate an automation that was created wrong, or one the user does not want +- `show-table` - display the new board (Step 5) and the user's first change, when the client has it diff --git a/skills/monday-project-status-report/SKILL.md b/skills/monday-project-status-report/SKILL.md index 6c0f16c..6e79b32 100644 --- a/skills/monday-project-status-report/SKILL.md +++ b/skills/monday-project-status-report/SKILL.md @@ -12,27 +12,26 @@ description: | license: MIT metadata: author: monday.com - version: "0.1.4" + version: "0.1.5" --- - # Project Status Report Generate a structured status report from one or more monday.com boards. monday.com is a customizable AI work platform with dedicated products for work management, CRM, dev, service, and campaigns - boards are the central unit of organization. This skill combines board metadata, item data, aggregated insights, and recent activity into a single actionable summary. ## Output Behavior -Present the report in plain language with clean formatting. Don't narrate which API tools were called or show raw JSON - summarize what the data means. Highlight what needs attention (blockers, overdue items, unassigned work) rather than echoing raw numbers. Always include each board's URL so the user can navigate directly. +Present the report in plain language with clean Markdown formatting. Don't narrate which API tools were called or show raw JSON - summarize what the data means. Highlight what needs attention (blockers, overdue items, unassigned work) rather than echoing raw numbers. Always include each board's URL so the user can navigate directly. -## Use MCP UI widgets for visual sections +## Visual sections: widgets when available, Markdown otherwise -This skill is one of the strongest fits for monday's MCP UI widgets. Use them as follows: +When `show-chart`, `show-battery` and `show-table` are in your tool list, use them for the visual sections. When they are not, render the same section in clean Markdown and include the board URL: -- **Status distribution**: call `show-chart` (the result is more scannable than a markdown table) -- **Project completion**: call `show-battery` to render a progress indicator -- **Overdue items**: call `show-table` so the user can sort, filter, and click through -- **Workload by person**: call `show-chart` if comparing across owners +- **Status distribution**: `show-chart` with `type: "pie"` or `"bar"` and `data: [{"name": "