From f5c76fc94759a208d6bb95f33da0285b9020b62c Mon Sep 17 00:00:00 2001 From: Avner Harrari Date: Tue, 10 Nov 2026 15:29:34 +0200 Subject: [PATCH 1/5] feat: monday.com plugin for Gemini Agent (1.0.0) Packages the monday.com MCP server and four skills from mondaycom/skills in the layout Google's Partner Plugin guide requires. The sync script adds the monday- prefix Gemini requires (CRIT-26a) at sync time, so mondaycom/skills keeps the names its other consumers install by. check-skills.js checks the guide's offline rules on every sync. Co-Authored-By: Claude Opus 5.5 --- .gemini-plugin/plugin.json | 22 ++ .mcp.json | 8 + CHANGELOG.md | 8 + CONTRIBUTING.md | 13 + scripts/check-skills.js | 154 +++++++++ scripts/sync-skills.sh | 67 ++++ skills.json | 6 + skills/monday-docs-collaborator/SKILL.md | 312 ++++++++++++++++++ .../references/block-operations-matrix.md | 221 +++++++++++++ .../references/create-modes.md | 31 ++ .../references/delta-format-cheatsheet.md | 300 +++++++++++++++++ .../references/errors.md | 16 + .../references/read-rendering.md | 9 + .../references/rich-content.md | 76 +++++ skills/monday-forms-builder/SKILL.md | 227 +++++++++++++ skills/monday-onboard-to-monday/SKILL.md | 143 ++++++++ skills/monday-task-management/SKILL.md | 263 +++++++++++++++ .../references/column-value-formats.md | 283 ++++++++++++++++ 18 files changed, 2159 insertions(+) create mode 100644 .gemini-plugin/plugin.json create mode 100644 .mcp.json create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md create mode 100644 scripts/check-skills.js create mode 100755 scripts/sync-skills.sh create mode 100644 skills.json create mode 100644 skills/monday-docs-collaborator/SKILL.md create mode 100644 skills/monday-docs-collaborator/references/block-operations-matrix.md create mode 100644 skills/monday-docs-collaborator/references/create-modes.md create mode 100644 skills/monday-docs-collaborator/references/delta-format-cheatsheet.md create mode 100644 skills/monday-docs-collaborator/references/errors.md create mode 100644 skills/monday-docs-collaborator/references/read-rendering.md create mode 100644 skills/monday-docs-collaborator/references/rich-content.md create mode 100644 skills/monday-forms-builder/SKILL.md create mode 100644 skills/monday-onboard-to-monday/SKILL.md create mode 100644 skills/monday-task-management/SKILL.md create mode 100644 skills/monday-task-management/references/column-value-formats.md diff --git a/.gemini-plugin/plugin.json b/.gemini-plugin/plugin.json new file mode 100644 index 0000000..68bedc5 --- /dev/null +++ b/.gemini-plugin/plugin.json @@ -0,0 +1,22 @@ +{ + "name": "monday-work-management", + "displayName": "monday.com", + "version": "1.0.0", + "description": "Plan and track work in monday.com from Gemini: create, update and assign items, write docs, and build forms that turn requests into items.", + "author": { + "name": "monday.com", + "email": "support@monday.com", + "url": "https://monday.com" + }, + "repository": "https://github.com/mondaycom/gemini-plugin", + "homepage": "https://monday.com/w/mcp", + "license": "MIT", + "keywords": ["monday", "project-management", "work-management", "tasks", "boards", "docs", "forms"], + "skills": [ + "./skills/monday-task-management/SKILL.md", + "./skills/monday-docs-collaborator/SKILL.md", + "./skills/monday-forms-builder/SKILL.md", + "./skills/monday-onboard-to-monday/SKILL.md" + ], + "mcpServers": "./.mcp.json" +} diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 0000000..6af31e0 --- /dev/null +++ b/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "monday": { + "type": "http", + "url": "https://mcp.monday.com/mcp" + } + } +} diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..988a5f5 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,8 @@ +# Changelog + +All notable changes to this plugin are documented here. Versions follow [Semantic Versioning](https://semver.org). + +## 1.0.0 + +- First release for Gemini Agent: the monday.com MCP server (`https://mcp.monday.com/mcp`) and four skills, + `monday-task-management`, `monday-docs-collaborator`, `monday-forms-builder` and `monday-onboard-to-monday`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..58bcbe2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,13 @@ +# Contributing + +This repository is the monday.com plugin for Gemini Agent. + +- **Skills** (`skills/`) are copied from [mondaycom/skills](https://github.com/mondaycom/skills) and must not be + edited here. `scripts/sync-skills.sh` adds the `prefix` from `skills.json` to each skill's folder and `name`, + because Gemini requires skill names to start with the partner brand. To change a skill, open a pull request in + mondaycom/skills. Once it is merged, bump `ref` in `skills.json` (and `skills`, to add or remove one), run + `scripts/sync-skills.sh` and open a pull request here with the result. +- **Everything else** (manifest, README, MCP configuration) is edited directly here through a pull request. Bump + `version` in `.gemini-plugin/plugin.json` and add a `CHANGELOG.md` entry with every release, then tag it + `v`. +- **Product support:** [support.monday.com](https://support.monday.com). diff --git a/scripts/check-skills.js b/scripts/check-skills.js new file mode 100644 index 0000000..e6a5478 --- /dev/null +++ b/scripts/check-skills.js @@ -0,0 +1,154 @@ +#!/usr/bin/env node +// Checks the plugin against the rules in Google's "Partner Plugin & Skill Best Practices Guide" that can be +// checked offline. Errors are the guide's hard limits and blocking security checks; warnings are its +// authoring standards. Exits 1 on any error. +// +// Usage: node scripts/check-skills.js [plugin-root] +"use strict"; +const fs = require("fs"); +const path = require("path"); + +const root = path.resolve(process.argv[2] || path.join(__dirname, "..")); +const errors = []; +const warnings = []; +const err = (where, msg) => errors.push(`${where}: ${msg}`); +const warn = (where, msg) => warnings.push(`${where}: ${msg}`); + +const GOOGLE_1P = ["bigquery", "gemini", "vertex-ai", "looker", "gdrive"]; +const INSTALL = /\b(brew install|npm (i|install)\b|npx |pip3? install|curl [^\n]*\|\s*(ba|z)?sh|wget [^\n]*\|\s*(ba|z)?sh)/i; +const INVISIBLE = /[\u200B-\u200F\u202A-\u202E\u2060-\u2064\uFEFF]/; +const HIDDEN_DIRECTIVE = /<\/?(IMPORTANT|SYSTEM)>/; + +function readJson(rel) { + try { + return JSON.parse(fs.readFileSync(path.join(root, rel), "utf8")); + } catch (e) { + err(rel, `cannot read: ${e.message}`); + return null; + } +} + +// Minimal frontmatter reader for the two keys we check: plain scalars and folded/literal blocks. +function frontmatter(text) { + const m = text.match(/^---\n([\s\S]*?)\n---\n?/); + if (!m) return null; + const out = {}; + const lines = m[1].split("\n"); + for (let i = 0; i < lines.length; i++) { + const kv = lines[i].match(/^([A-Za-z0-9_-]+):\s*(.*)$/); + if (!kv) continue; + let value = kv[2]; + if (/^[>|][-+]?$/.test(value)) { + const block = []; + while (i + 1 < lines.length && (/^\s/.test(lines[i + 1]) || lines[i + 1] === "")) block.push(lines[++i].trim()); + value = block.join(value.startsWith(">") ? " " : "\n").trim(); + } else { + value = value.replace(/^(["'])(.*)\1$/, "$2"); + } + out[kv[1]] = value; + } + return { data: out, body: text.slice(m[0].length) }; +} + +const manifest = readJson(".gemini-plugin/plugin.json"); +const skillsConfig = readJson("skills.json"); +const prefix = (skillsConfig && skillsConfig.prefix) || ""; + +if (manifest) { + for (const key of ["name", "displayName", "version", "description", "author", "skills", "mcpServers"]) { + if (manifest[key] === undefined) err("plugin.json", `missing "${key}"`); + } + if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(manifest.name || "")) err("plugin.json", "name must be kebab-case"); + if (prefix && !(manifest.name || "").startsWith(prefix)) err("plugin.json", `name must start with "${prefix}" (CRIT-26a)`); + if (!/^\d+\.\d+\.\d+$/.test(manifest.version || "")) err("plugin.json", "version must be MAJOR.MINOR.PATCH"); + for (const f of ["README.md", "CHANGELOG.md", "LICENSE"]) { + if (!fs.existsSync(path.join(root, f))) err(f, "missing"); + } + const changelog = fs.existsSync(path.join(root, "CHANGELOG.md")) ? fs.readFileSync(path.join(root, "CHANGELOG.md"), "utf8") : ""; + if (manifest.version && !changelog.includes(`## ${manifest.version}`)) err("CHANGELOG.md", `no entry for ${manifest.version}`); + + let authorHost = ""; + try { + authorHost = new URL(manifest.author.url).hostname.replace(/^www\./, ""); + } catch { + err("plugin.json", "author.url must be a URL"); + } + const mcp = readJson(String(manifest.mcpServers || ".mcp.json").replace(/^\.\//, "")); + for (const [id, server] of Object.entries((mcp && mcp.mcpServers) || {})) { + let url; + try { + url = new URL(server.url); + } catch { + err(".mcp.json", `${id}: url is not a URL`); + continue; + } + if (url.protocol !== "https:") err(".mcp.json", `${id}: url must use https (CRIT-23)`); + if (authorHost && !(url.hostname === authorHost || url.hostname.endsWith(`.${authorHost}`))) { + err(".mcp.json", `${id}: ${url.hostname} does not match author.url domain ${authorHost} (CRIT-26b)`); + } + } + + const listed = new Set(); + for (const rel of manifest.skills || []) { + const where = rel; + const file = path.join(root, rel); + if (!fs.existsSync(file)) { + err(where, "listed in plugin.json but missing"); + continue; + } + const dir = path.basename(path.dirname(file)); + listed.add(dir); + const text = fs.readFileSync(file, "utf8"); + const fm = frontmatter(text); + if (!fm) { + err(where, "no YAML frontmatter"); + continue; + } + const { name = "", description = "" } = fm.data; + if (name !== dir) err(where, `frontmatter name "${name}" does not match folder "${dir}"`); + if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(name) || name.length > 64) err(where, "name must be kebab-case, <= 64 chars"); + if (prefix && !name.startsWith(prefix)) err(where, `name must start with "${prefix}" (CRIT-26a)`); + if (GOOGLE_1P.includes(name)) err(where, "name is a Google 1P name (CRIT-26a)"); + if (!description) err(where, "description is empty"); + if (description.length > 1024) err(where, `description is ${description.length} chars, max 1024`); + if (!/"[^"]+"/.test(description)) warn(where, "description has no quoted trigger phrases"); + if (!/\b(don'?t|do not) use\b/i.test(description)) warn(where, `description has no "Don't use for..." boundary`); + + const lines = text.split("\n").length; + const words = fm.body.split(/\s+/).filter(Boolean).length; + if (lines > 500) err(where, `${lines} lines, max 500`); + else if (lines > 300) warn(where, `${lines} lines, target 150-300`); + if (words >= 3000) err(where, `${words} words in the body, max 3,000`); + + const skillDir = path.dirname(file); + for (const f of walk(skillDir)) { + const rel2 = path.relative(root, f); + const content = fs.readFileSync(f, "utf8"); + if (INSTALL.test(content)) err(rel2, "contains a local install command"); + if (INVISIBLE.test(content)) err(rel2, "contains invisible Unicode characters (CRIT-12-16)"); + if (HIDDEN_DIRECTIVE.test(content)) err(rel2, "contains a hidden / directive (CRIT-22)"); + } + } + const skillsDir = path.join(root, "skills"); + if (fs.existsSync(skillsDir)) { + for (const d of fs.readdirSync(skillsDir)) { + if (!listed.has(d)) err(`skills/${d}`, "not listed in plugin.json skills"); + } + } +} + +function walk(dir) { + return fs.readdirSync(dir, { withFileTypes: true }).flatMap((e) => { + const p = path.join(dir, e.name); + if (e.isSymbolicLink()) { + err(path.relative(root, p), "symlinks are not allowed (CRIT-01-20)"); + return []; + } + return e.isDirectory() ? walk(p) : [p]; + }); +} + +for (const w of warnings) console.log(`warning ${w}`); +for (const e of errors) console.log(`error ${e}`); +console.log(`${errors.length} error(s), ${warnings.length} warning(s)`); +process.exit(errors.length ? 1 : 0); diff --git a/scripts/sync-skills.sh b/scripts/sync-skills.sh new file mode 100755 index 0000000..dea9deb --- /dev/null +++ b/scripts/sync-skills.sh @@ -0,0 +1,67 @@ +#!/usr/bin/env bash +# Syncs skills/ from the repo and commit pinned in skills.json, then checks them against Gemini's skill rules. +# +# mondaycom/skills is the single source of truth for skill content. Never edit skills/ by hand: +# change the skill in mondaycom/skills, bump "ref" (and "skills" if needed) in skills.json, run this +# script and commit the result. +# +# Gemini requires every skill name to start with the partner brand, while mondaycom/skills keeps the +# unprefixed names its other consumers install by. So each skill is copied to skills//, +# and its frontmatter name and any mention of another synced skill get the same prefix. +# +# Usage: scripts/sync-skills.sh +# Env overrides (for testing an unmerged skills branch): +# SKILLS_REPO git URL or local path to use instead of skills.json "repo" +# SKILLS_REF commit or branch to use instead of skills.json "ref" +set -euo pipefail + +ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" + +case "${1:-}" in + -h|--help) sed -n '2,16p' "$0"; exit 0 ;; + "") ;; + *) echo "Unknown argument: $1" >&2; exit 1 ;; +esac + +for cmd in git node perl; do + command -v "$cmd" >/dev/null || { echo "Missing required command: $cmd" >&2; exit 1; } +done + +config() { + node -e ' + const c = require(process.argv[1]); const v = c[process.argv[2]]; + if (v === undefined || (Array.isArray(v) && v.length === 0)) { console.error(`skills.json: "${process.argv[2]}" is missing or empty`); process.exit(1); } + console.log(Array.isArray(v) ? v.join("\n") : v); + ' "$ROOT/skills.json" "$1" +} +SKILLS_REPO="${SKILLS_REPO:-$(config repo)}" +SKILLS_REF="${SKILLS_REF:-$(config ref)}" +PREFIX="$(config prefix)" +SKILLS="$(config skills)" + +[[ "$PREFIX" =~ ^[a-z0-9]+-$ ]] || { echo "Invalid prefix in skills.json: '$PREFIX'" >&2; exit 1; } + +WORK_DIR="$(mktemp -d "${TMPDIR:-/tmp}/monday-skills.XXXXXX")" +trap 'rm -rf "$WORK_DIR"' EXIT + +echo "Fetching skills from $SKILLS_REPO @ $SKILLS_REF" +git clone --quiet --no-checkout "$SKILLS_REPO" "$WORK_DIR/src" +git -C "$WORK_DIR/src" checkout --quiet "$SKILLS_REF" + +while IFS= read -r skill; do + [[ "$skill" =~ ^[a-z0-9-]+$ ]] || { echo "Invalid skill name in skills.json: '$skill'" >&2; exit 1; } + [ -f "$WORK_DIR/src/skills/$skill/SKILL.md" ] || { echo "Skill not found at $SKILLS_REF: $skill" >&2; exit 1; } +done <<< "$SKILLS" + +rm -rf "$ROOT/skills" +mkdir -p "$ROOT/skills" +NAMES_ALT="$(echo "$SKILLS" | paste -sd '|' -)" +while IFS= read -r skill; do + dest="$ROOT/skills/$PREFIX$skill" + cp -R "$WORK_DIR/src/skills/$skill" "$dest" + find "$dest" -type f -name '*.md' -print0 | xargs -0 perl -pi -e \ + "s/(?]` to check whether the cell is already populated. If populated, do NOT attempt the create - it will fail with `CellLimitExceededException`. Fall back to **creating a workspace-level doc and adding a bi-directional DOC mention cross-link** between the new doc and the existing attached doc. Never auto-detach the existing doc. + +If the user does not name a workspace, fall back to the user's primary workspace via `get_user_context`. Ask once if it's still ambiguous; do not guess across multiple workspaces. + +### Step 2: Plan-tier guard before creating a 4th doc + +**Free and Basic plans cap at 3 docs per account.** Before calling `create_doc` on a Free / Basic account, check whether this would be the 4th doc. There is no direct doc-count tool, so the practical guard is: if the user has hit this limit before or asks "can I create more than 3 docs?", warn them - upgrade to Standard+ removes the cap. Treat plan-tier as an open question rather than blocking the create call; the platform itself will reject if the cap is hit. + +### Step 3: Compose the body - shapes are examples, not boundaries + +`create_doc` takes a `markdown` parameter that is parsed into blocks on import. Keep it to a few sections; append long bodies with `add_markdown_content` (see `references/errors.md`). Reach for one of these common shapes as a starting point when the user names a use case, then extend freely: + +- **Meeting notes:** title, date, attendees (with `@mentions`), agenda bullets, decisions, action items table, follow-ups. +- **Weekly update:** highlights, key metrics, risks, next-week plan. +- **RFC:** problem, proposed solution, alternatives considered, open questions, decision log. +- **Runbook:** trigger, prerequisites, numbered procedure, rollback steps, escalation path. +- **Postmortem:** incident summary, timeline, root cause, what went well, what did not, action items. + +When the user invents a shape ("partner enablement page", "AI readiness snapshot", "Q3 onboarding context"), compose with judgment - sections, tables, notice boxes, embeds - rather than forcing a named template. The differentiators apply to any shape. + +**Passive vs active mode.** By default, scaffold with visible slot markers (`_[embed: ...]_`, `_[mention: ...]_`) where embeds and mentions belong. Switch to active mode - wiring real embeds and mentions - when the user refers to items, boards or people by name; resolve names to IDs yourself (if a name is ambiguous, ask once with the top 3 candidates) and state what you picked. Read `references/create-modes.md` before wiring anything: it has the marker formats, escalation triggers, name-to-ID resolution chain and the communication contract. + +Markdown notes that matter: + +- 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 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. + +### Step 4: Call `create_doc` + +``` +create_doc({ + doc_name: "", + location: "workspace", + workspace_id: <id>, + doc_kind: "public" | "private" | "share", // optional + folder_id: <id>, // optional + markdown: "<full markdown body>" +}) +``` + +For item-attached (after preflight): + +``` +create_doc({ + doc_name: "<title>", + location: "item", + item_id: <id>, + column_id: "<doc_column_id>", // optional + markdown: "<full markdown body>" +}) +``` + +Capture the returned `doc_id`, `object_id`, and `doc_url`. The user wants the URL to share or open; the `doc_id` is the primary key for every subsequent edit. + +### Step 5: Layer in the rich-content extras + +Mentions, live column-value embeds, notice boxes, layouts, and asset images all need a follow-up `update_doc` call. In active mode, wire them now using the resolved IDs from Step 3. In passive mode, leave the slot markers in place - the user fills slots later by naming items. See "Common patterns" in `references/delta-format-cheatsheet.md`. + +### Step 6: Confirm and suggest next steps + +Plain-language confirmation: name, workspace, doc URL. State the mode used (passive scaffold or active). Then 2-3 follow-ups appropriate to the shape: + +- "Want me to tag the attendees with @mentions?" +- "Want me to embed live status from the project board?" +- "Should I add a notice box at the top with the meeting outcome?" +- "Want me to share the doc URL in a Slack channel?" + +## Workflow: Read a doc + +### Step 1: Resolve the doc identifier + +Three ways the user might point at a doc: + +- **doc_id** (e.g., `41302579`) - the API's primary key, returned 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. + +`read_docs` is forgiving: if you call it with `type: "ids"` and the value is actually an `object_id`, it auto-retries as `object_ids`. Lean on this rather than guessing. + +### Step 2: Decide what to read + +Two modes: + +- **content** (default) - returns the doc's blocks and / or markdown projection. + - `include_blocks: true` is **mandatory** if any edit will follow. Do not omit it. + - `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). + +### Step 3: Render with resolved mentions and embeds, not placeholders + +The API's `blocks_as_markdown` projection renders mentions as `@{USER-XXX}` placeholders and live column-value embeds as empty space. **This is not the right rendering for a "show me what's in this doc" prompt** - the user sees pills and live chips when they open the doc; the textual rendering should mirror that. + +For "show me / what's in / read this doc" prompts: resolve every mention to a display name, resolve embeds to their current values when cheap, and add an enumeration table of inline non-text elements with their IDs. Read `references/read-rendering.md` for the exact rules. + +Do not use `show-table` for doc content - the doc itself is the UI. Render in chat with markdown. + +## Workflow: Edit a doc + +### Step 1: Read first + +`read_docs` with `include_blocks: true`. This is the closed-loop precondition. Capture every block's `id`, `type`, and position. + +### Step 2: Pick the right operation + +Reach for the simplest one that does the job: + +- **Add new content at the end:** `add_markdown_content` (no block IDs needed; supports text, lists, tables, code). +- **Add asset-based images:** `create_block` with `block_type: "image"` and `asset_id` (markdown does not support asset images). +- **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. +- **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. +- **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`. + +The full type-to-operation routing lives in `references/block-operations-matrix.md`. + +### Step 3: Compose the delta_format (for text / code / list_item) + +`update_block` and `create_block` for content blocks take a `delta_format` array of insert ops. Three rules govern every delta: + +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). +3. Two non-text inserts unlock the differentiators: + - Mention: `{insert: {mention: {id: <numeric-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: <id>, column_id: "<column_id>"}}}`. Renders the current value of that column on that item, live, every time the doc is opened. + +Worked examples and the full attribute table live in `references/delta-format-cheatsheet.md`. + +### Step 4: Batch operations carefully + +`update_doc` accepts up to 25 operations in one call, executed in order, stopping at the first failure. Four gotchas: + +- **Notice box nesting requires two calls.** A notice_box created in the same call cannot be referenced by `parent_block_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: [<update_id>, ...]` 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. + +### Step 5: Verify and confirm + +After a non-trivial edit, re-read with `include_blocks: true` to confirm the blocks landed as intended. Plain-language confirmation: what changed, the doc URL. Do not narrate the API calls. + +## Rich content: tables, notice boxes, layouts, mentions, live embeds, comments + +Live column-value embeds are the differentiator: they keep a doc in sync with real board data. Before adding any of these elements, read `references/rich-content.md`. It covers table constraints, notice-box nesting, layouts, mention types, live column-value embeds and comments. + +## Smart defaults + +When the user does not specify all values: + +- **Workspace**: the user's primary workspace via `get_user_context`. State the default. Ask once if multiple workspaces are plausible. +- **doc_kind**: `public` (the platform default). +- **Folder**: none (root of the workspace). +- **Doc shape**: if the user names a use case ("meeting notes", "RFC", "weekly update"), scaffold the matching shape as a starting point and extend per the user's specific asks. If the user invents a shape, compose with judgment - no template needed. +- **Mode**: passive scaffold (slot markers) by default. Escalate to active mode (real embeds / mentions / cross-links) only when name-based intent signals are present. +- **Embeds and mentions in active mode**: state the resolved choices and reasoning before wiring. Offer override. + +State every default in the response so the user can override. + +## Validate preconditions before writing + +- **Doc exists:** `read_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. +- **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. +- **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. + +## Duplicate detection before writing + +**Before any `create_block`, `add_markdown_content`, `add_comment`, or content-replacing `update_block`, compare the proposed content against existing blocks in the doc.** Default to skip + report on match; surface options to the user; never silently duplicate. + +Match heuristics by block type: + +| Block type | Match heuristic | +|---|---| +| text / heading / quote / code | exact delta text + same subtype | +| list_item | exact text + same list type + adjacency (multi-bullet sections matched as a group) | +| notice_box | same theme + same child text | +| table | same dimensions + same cell content | +| mention | same user_id at same block position | +| column_value embed | same item_id + column_id at same block position | +| comment | same body text + same anchor (excluded by default - see below) | + +Skill behavior on match found: + +1. **Default: skip + report.** "X already exists at <position>. Skipping to avoid duplicate." +2. **Surface options** (do not silently pick): + - **(a) skip** - keep existing, do nothing + - **(b) duplicate** - proceed as requested, accept redundancy + - **(c) replace** - delete existing, create fresh + - **(d) move** - offered only when the new request has explicit positional intent ("at the top / at the bottom / after X") that conflicts with the existing match's position + +Exclusions where duplication is normal and detection should NOT trigger: + +- **Comments are excluded** except for a short stutter window. Same comment body submitted to the same scope (doc or block) within 60 seconds is almost certainly a double-submit / network retry; beyond that, treat as legitimate (legitimate re-review, sentiment echo). +- Adjacent same-style blocks in a list - intended structure, not duplication. +- Repeating section names in different parents (e.g. two "Action Items" H3s under different H2s). + +Apply this duplicate-detection rule to every write path in the skill. + +## Surface errors with remediation + +When a call fails, tell the user what went wrong and how to fix it. The catalog of common failures and their remediation (malformed or stale block IDs, schema mismatches, nesting in one call, cell limits, blank embeds, plan limits, unsupported block types, orphan comment anchors) is in `references/errors.md`. + +## Be conservative on destructive operations + +Require explicit confirmation for: + +- Deleting 3+ blocks in one call. +- Deleting a block that is the only content in its parent (deletes the parent's only content; the parent stays as an empty shell). +- Deleting a notice_box, table, or layout - children are NOT auto-deleted; they become orphaned. Either delete children first or accept the orphan state. +- Bulk replace_block operations (each replace is a delete + create; non-reversible). +- Renaming a doc that has live external references (Slack messages, other docs, item updates). + +Single block edits, single block creates, and single comments need no extra confirmation - the user already asked. + +## When to use MCP UI widgets + +The doc is the UI. Do not render `show-table` or `show-chart` to display doc content. Plain-text confirmations and markdown summaries are the right output. + +## Plain language over raw JSON + +Never tell the user "I called `read_docs` then `update_doc` with an `update_block` operation." Tell them what changed in human terms: "Updated the second paragraph of your runbook with the new escalation contact." Always include the doc URL. + +## Tools used + +- `get_user_context` - resolve the user's primary workspace +- `list_workspaces` - find a workspace by name when not provided +- `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` +- `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 + +## Additional resources + +- **`references/block-operations-matrix.md`** - per-block-type allowed operations, gotchas, and example payloads. +- **`references/create-modes.md`** - passive-scaffold slot markers, active-mode triggers, name-to-ID resolution and the communication contract. +- **`references/rich-content.md`** - tables, notice boxes, layouts, mentions, live column-value embeds and comments. +- **`references/read-rendering.md`** - how to render mentions, embeds and inline elements when reading a doc. +- **`references/errors.md`** - common failures and how to remediate them. +- **`references/delta-format-cheatsheet.md`** - delta_format insert ops, attributes, mentions, column_value embeds, the terminator rule, common patterns, and the passive-mode slot marker format. diff --git a/skills/monday-docs-collaborator/references/block-operations-matrix.md b/skills/monday-docs-collaborator/references/block-operations-matrix.md new file mode 100644 index 0000000..7dc1792 --- /dev/null +++ b/skills/monday-docs-collaborator/references/block-operations-matrix.md @@ -0,0 +1,221 @@ +# Block operations matrix + +Per-block-type guide to which `update_doc` operation to use. Picking the wrong operation is the most common cause of silent doc corruption. + +## How to use this file + +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". + +## Type naming - input vs output + +monday's API uses two different naming conventions for block types: + +- **Input** (when you call `update_doc` with `create_block` or `replace_block`): UPPER_SNAKE_CASE, e.g. `LARGE_TITLE`, `BULLETED_LIST`, `INFO`. +- **Output** (when you read blocks from `read_docs`): lowercase with spaces, e.g. `large title`, `bulleted list`, `notice box`. + +When matching a read block to a row in this table, normalize on the lowercase output form. + +## Routing matrix + +| 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 | + +## update_block - the in-place edit path + +Use for content edits on text, code, and list_item blocks where the subtype is staying the same. + +```json +{ + "operation_type": "update_block", + "block_id": "<id from read_docs>", + "content": { + "block_content_type": "text", + "delta_format": [ + { "insert": { "text": "New paragraph content. " } }, + { "insert": { "text": "\n" } } + ] + } +} +``` + +Variants: + +- `block_content_type: "code"` - pass `language` to change the highlight (`"python"`, `"javascript"`, etc). +- `block_content_type: "list_item"` - pass `indentation` (0 to N) for nesting; pass `checked` (bool) for CHECK_LIST items. + +`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 + +Use when: + +- The block has no mutable properties (`divider`, `page break`). +- The block is structurally immutable (table, image source, video source, notice_box theme, layout). +- The user wants to change a text block's subtype (paragraph -> H1) or list variant (bulleted -> numbered). + +```json +{ + "operation_type": "replace_block", + "block_id": "<id of block to remove>", + "block": { + "block_type": "text", + "text_block_type": "MEDIUM_TITLE", + "delta_format": [ + { "insert": { "text": "New H2 content" } }, + { "insert": { "text": "\n" } } + ] + } +} +``` + +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. + +## create_block - insert anywhere + +Use to add a new block at a precise position. + +- `after_block_id`: the block this new block follows. Omit to append at the end of the doc. +- `parent_block_id`: only works for nesting inside a `notice_box`. Cannot be used for table cells or layout cells. + +```json +{ + "operation_type": "create_block", + "after_block_id": "<id of preceding block>", + "block": { + "block_type": "notice_box", + "theme": "WARNING" + } +} +``` + +Then in a SEPARATE call: + +```json +{ + "operation_type": "create_block", + "parent_block_id": "<notice_box id from previous call>", + "block": { + "block_type": "text", + "text_block_type": "NORMAL_TEXT", + "delta_format": [ + { "insert": { "text": "Watch out for X." } }, + { "insert": { "text": "\n" } } + ] + } +} +``` + +## delete_block - the only path for embed types + +Works for every block type. The only available operation for `BOARD`, `WIDGET`, `DOC` embed, and `GIPHY` blocks. + +```json +{ + "operation_type": "delete_block", + "block_id": "<id>" +} +``` + +Deleting a parent block (notice_box, table, layout) does NOT delete its children. Delete children first if you want a clean removal. + +## Tables + +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). + +If the user asks to "edit cell B2 of my table", explain the constraint and offer: + +- Rewrite the entire table via markdown (best for small tables). +- Direct the user to edit in the monday UI (best for large tables). + +## Notice boxes + +A notice_box must be created in two `update_doc` calls when it has children. The first call creates the container; the second references its ID via `parent_block_id`. + +``` +Call 1: create_block notice_box { theme: "INFO" } + -> returns block ID X + +Call 2: create_block { parent_block_id: X, block: { block_type: "text", ... } } +``` + +A notice_box created in the same call as its child cannot be referenced - the API rejects forward references to IDs created within the same operations array. + +To change a notice_box's theme: + +- `replace_block` with the new theme. Children are NOT carried over - they become orphaned. +- Recreate children after the replace, in a separate later call (the new notice_box ID is only available after the first call returns). + +## Layouts + +Layouts are multi-column shells. The API can create them empty (2-6 columns, with column widths), but **cannot populate cell content**. The `parent_block_id` field rejects layout block IDs. + +When the user asks for a layout with content: + +- Create the layout shell via `create_block`. +- Tell the user the cells must be filled from the monday UI. +- Or, fall back to a different shape: a heading + sub-headings (visually similar in many cases), or a single-column with separators. + +There is no markdown shortcut for layout cell content. + +## Block subtypes - input enums + +Text block subtypes (`text_block_type`): + +- `LARGE_TITLE` - rendered as H1 +- `MEDIUM_TITLE` - rendered as H2 +- `SMALL_TITLE` - rendered as H3 +- `NORMAL_TEXT` - paragraph +- `QUOTE` - blockquote + +List block subtypes (`list_block_type`): + +- `BULLETED_LIST` - default +- `NUMBERED_LIST` - auto-numbered +- `CHECK_LIST` - supports `checked: true | false` per item + +Notice box themes (`theme`): + +- `INFO` - blue, informational +- `TIPS` - green, helpful hint +- `WARNING` - red / orange, watch-out +- `GENERAL` - neutral + +## Quick reference - common edits + +| User intent | Operation | Notes | +|---|---|---| +| Append a section to the end | `add_markdown_content` (markdown body) | No block IDs needed | +| Edit one paragraph in place | `update_block` (text) | Re-read first to get block_id | +| Promote a paragraph to H2 | `replace_block` (text, MEDIUM_TITLE) | Subtype change requires replace | +| Switch a bulleted list to numbered | `replace_block` per item (list_item, NUMBERED_LIST) | One replace per item | +| Tag a user inline | `update_block` with mention insert in delta_format | See delta-format-cheatsheet.md | +| 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 | +| 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 | +| 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 new file mode 100644 index 0000000..6e91ab4 --- /dev/null +++ b/skills/monday-docs-collaborator/references/create-modes.md @@ -0,0 +1,31 @@ +# Creating docs: passive scaffold vs active mode + +Detail for Step 3 of "Workflow: Create a doc" in `SKILL.md`. + +**Default mode: passive scaffold.** Reserve visible slots for embeds and mentions in the markdown body using machine-readable markers. Skill (and downstream agents) can later detect and fill these slots when the user names the underlying items / users. + +| Slot type | Marker format | Example | +|---|---|---| +| Live column-value embed | `_[embed: <column> of <item-ref>]_` | `_[embed: status of <top-priority item>]_` | +| User mention | `_[mention: <user-ref>]_` | `_[mention: <owner>]_` | +| Doc / board mention | `_[mention-doc: <doc-name>]_` / `_[mention-board: <board-name>]_` | `_[mention-board: Project Tracker]_` | + +Italic styling on slot markers gives visual signal that the content is dynamic. The bracket-keyword format is grep-able for downstream automation. + +**Active mode: escalate when intent signals are present.** Switch from passive scaffold to wiring real embeds / mentions / cross-links when the user's prompt signals intent through name-based references. Never on item IDs - users speak in names. + +Triggers that escalate to active mode: + +- Item names ("the Q3 plan", "the launch milestone", "the blocker we discussed") +- Board names ("from the project tracker", "in the bug board") +- Owner names ("Daniel's tasks", "my items", "the design team's") +- Positional refs ("the top 3 priorities", "the most recent stuck items") +- Imperative wiring ("embed live status from", "show current status of", "pull from <board>", "wire up the embeds", "tag me as owner") + +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` +- 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 + +**Active mode communication contract.** When the skill picks items / users in active mode, always state the choice and the reasoning: "Picked items X, Y, Z because <reason>. Override by naming different items." diff --git a/skills/monday-docs-collaborator/references/delta-format-cheatsheet.md b/skills/monday-docs-collaborator/references/delta-format-cheatsheet.md new file mode 100644 index 0000000..80217cd --- /dev/null +++ b/skills/monday-docs-collaborator/references/delta-format-cheatsheet.md @@ -0,0 +1,300 @@ +# Delta format cheatsheet + +`delta_format` is the array of insert operations that defines a text, code, or list_item block's content. It is required by `update_block`, `create_block` (for content blocks), and `replace_block` (for content blocks). + +## 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. +3. **Three insert types:** + - `{insert: {text: "..."}}` - plain or styled text. + - `{insert: {mention: {id, type}}}` - inline mention of a user, doc, or board. + - `{insert: {column_value: {item_id, column_id}}}` - live embed of a board column's current value. + +## Text inserts and attributes + +```json +{ "insert": { "text": "Hello world" } } +``` + +Add formatting via `attributes`: + +```json +{ "insert": { "text": "bold text" }, "attributes": { "bold": true } } +``` + +Supported attributes (all optional, all apply to text inserts only): + +| Attribute | Type | Notes | +|---|---|---| +| `bold` | bool | - | +| `italic` | bool | - | +| `underline` | bool | - | +| `strike` | bool | strikethrough | +| `code` | bool | inline code style (not a code block) | +| `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. | + +Combine attributes: + +```json +{ + "insert": { "text": "important link" }, + "attributes": { "bold": true, "link": "https://example.com" } +} +``` + +## Mentions + +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" } } } +``` + +Three mention types: + +| `type` | What `id` means | How to resolve | +|---|---|---| +| `USER` | numeric user ID | `list_users_and_teams` with `name: "<display 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 | + +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": + +```json +[ + { "insert": { "text": "Hey " } }, + { "insert": { "mention": { "id": 48202303, "type": "USER" } } }, + { "insert": { "text": ", the " } }, + { "insert": { "mention": { "id": 18234567890, "type": "DOC" } } }, + { "insert": { "text": " doc is ready." } }, + { "insert": { "text": "\n" } } +] +``` + +## Live column-value embeds - the differentiator + +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" } } } +``` + +`item_id` accepts string or number. `column_id` is a string (e.g. `"status"`, `"date4"`, `"color_mm2x25ey"`). + +Resolution rules: + +- Validate `item_id` exists via `get_board_items_page` or `get_full_board_data`. +- 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: + +```json +[ + { "insert": { "text": "Q3 plan is currently " } }, + { "insert": { "column_value": { "item_id": 11890636850, "column_id": "color_mm2x25ey" } } }, + { "insert": { "text": ", owned by " } }, + { "insert": { "column_value": { "item_id": 11890636850, "column_id": "multiple_person_mm2x4gzh" } } }, + { "insert": { "text": ", due " } }, + { "insert": { "column_value": { "item_id": 11890636850, "column_id": "date_mm2x10qd" } } }, + { "insert": { "text": "." } }, + { "insert": { "text": "\n" } } +] +``` + +When the doc is opened, the embeds render as the live values. When the item's status changes, the doc reflects it without an edit. + +## Internal storage note + +When you read a doc back, column_value embeds appear in storage as `macro` blots: + +```json +{ + "insert": { + "macro": { + "type": "COLUMN_VALUE", + "macroId": "...", + "macroData": { "itemId": 11890636850, "columnId": "color_mm2x25ey" } + } + } +} +``` + +This is the on-disk representation. Use the input form (`{insert: {column_value: ...}}`) when writing - the API normalizes it. When reading, expect the macro form in the blocks array. The `blocks_as_markdown` projection does NOT render column_value embeds (they appear as empty space in the markdown view); inspect the blocks array directly to find them. + +## Code blocks + +Code blocks use `block_content_type: "code"` and accept a `language` field (top-level on the content object, not inside the delta). + +```json +{ + "operation_type": "update_block", + "block_id": "<id>", + "content": { + "block_content_type": "code", + "language": "python", + "delta_format": [ + { "insert": { "text": "def hello():\n print(\"hi\")" } }, + { "insert": { "text": "\n" } } + ] + } +} +``` + +Code block content does not parse mention or column_value inserts as embeds - they render as literal text. Keep code blocks plain. + +## List items + +List items use `block_content_type: "list_item"` with optional `indentation` (0 to N) and, for CHECK_LIST items, `checked` (bool). + +```json +{ + "operation_type": "update_block", + "block_id": "<id>", + "content": { + "block_content_type": "list_item", + "indentation": 1, + "delta_format": [ + { "insert": { "text": "Nested bullet content" } }, + { "insert": { "text": "\n" } } + ] + } +} +``` + +To toggle a checkbox: + +```json +{ + "operation_type": "update_block", + "block_id": "<id>", + "content": { + "block_content_type": "list_item", + "checked": true, + "delta_format": [ + { "insert": { "text": "Done item" } }, + { "insert": { "text": "\n" } } + ] + } +} +``` + +## Common patterns + +### Plain paragraph + +```json +[ + { "insert": { "text": "Plain text content." } }, + { "insert": { "text": "\n" } } +] +``` + +### Bold word in a sentence + +```json +[ + { "insert": { "text": "This is " } }, + { "insert": { "text": "important" }, "attributes": { "bold": true } }, + { "insert": { "text": " context." } }, + { "insert": { "text": "\n" } } +] +``` + +### Inline link + +```json +[ + { "insert": { "text": "See the " } }, + { "insert": { "text": "design doc" }, "attributes": { "link": "https://monday.monday.com/docs/123456" } }, + { "insert": { "text": " for details." } }, + { "insert": { "text": "\n" } } +] +``` + +### Mention + live status in one line + +```json +[ + { "insert": { "mention": { "id": 38288909, "type": "USER" } } }, + { "insert": { "text": " is owning, current status: " } }, + { "insert": { "column_value": { "item_id": 11890636850, "column_id": "color_mm2x25ey" } } }, + { "insert": { "text": "\n" } } +] +``` + +### Highlighted phrase with strike-through + +```json +[ + { "insert": { "text": "Old plan: " } }, + { "insert": { "text": "ship Q2" }, "attributes": { "strike": true } }, + { "insert": { "text": ". New plan: ship Q3." } }, + { "insert": { "text": "\n" } } +] +``` + +### Color-coded callout phrase + +```json +[ + { "insert": { "text": "Status: " } }, + { "insert": { "text": "BLOCKED" }, "attributes": { "bold": true, "color": "#d83a52", "background": "#ffe0e6" } }, + { "insert": { "text": "\n" } } +] +``` + +## Passive-mode slot markers - the scaffold contract + +When the skill creates a doc in **passive scaffold mode** (the default, before user names specific items / users), reserve visible slots for embeds and mentions using italic placeholder markers in the markdown body. Slots telegraph platform shape without inserting broken embeds. + +| Slot type | Marker format | Example use in a delta | +|---|---|---| +| Live column-value embed | `_[embed: <column> of <item-ref>]_` | `_[embed: status of <top priority item>]_` | +| User mention | `_[mention: <user-ref>]_` | `_[mention: <owner>]_` | +| Doc mention | `_[mention-doc: <doc-name>]_` | `_[mention-doc: <related RFC>]_` | +| Board mention | `_[mention-board: <board-name>]_` | `_[mention-board: <project tracker>]_` | + +**Rules:** + +- Wrap the entire marker in italic via the surrounding markdown (`_..._`) or via `attributes: {italic: true}` on the text insert. +- Use angle brackets `< >` around the user-supplied reference name, keep `[embed:` / `[mention:` / `[mention-doc:` / `[mention-board:` as the literal prefix. +- One marker per slot. Multiple slots per block are fine (e.g. `_[mention: <owner>] - _[embed: status of <item>]_`). + +**Worked example - passive scaffold for a weekly update header line:** + +```json +[ + { "insert": { "text": "Overall status: " }, "attributes": { "italic": true, "bold": true } }, + { "insert": { "text": "[embed: status of <milestone item>]" }, "attributes": { "italic": true } }, + { "insert": { "text": "\n" } } +] +``` + +**Worked example - passive scaffold for a partner-contact line (mention slot):** + +```json +[ + { "insert": { "text": "Owner: " }, "attributes": { "bold": true } }, + { "insert": { "text": "[mention: <owner>]" }, "attributes": { "italic": true } }, + { "insert": { "text": "\n" } } +] +``` + +**Active mode replaces slot markers with real inserts.** Once the user names the underlying item / user, the skill targets the slot block via `update_block` and replaces the delta with the actual mention / column_value insert. The slot marker format is grep-able, so a downstream agent reading the doc can detect unfilled slots and prompt the user to complete them. + +## Anti-patterns - things that look reasonable but fail + +- **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. +- **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. diff --git a/skills/monday-docs-collaborator/references/errors.md b/skills/monday-docs-collaborator/references/errors.md new file mode 100644 index 0000000..42b9059 --- /dev/null +++ b/skills/monday-docs-collaborator/references/errors.md @@ -0,0 +1,16 @@ +# Errors and remediation + +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. +- **"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`. +- **"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"). +- **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. +- **"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: [<update_id>]` 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. diff --git a/skills/monday-docs-collaborator/references/read-rendering.md b/skills/monday-docs-collaborator/references/read-rendering.md new file mode 100644 index 0000000..f575690 --- /dev/null +++ b/skills/monday-docs-collaborator/references/read-rendering.md @@ -0,0 +1,9 @@ +# Rendering a doc for read requests + +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}`. +- **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 new file mode 100644 index 0000000..0a5e6fe --- /dev/null +++ b/skills/monday-docs-collaborator/references/rich-content.md @@ -0,0 +1,76 @@ +# Rich content in monday docs + +Detail for the rich-content section of `SKILL.md`. + +## Tables + +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. + +When the user asks to "edit cell B2", explain the constraint and offer the closest workaround: rewrite the whole table via markdown. + +## Notice boxes + +A notice_box is a styled callout container. Creating one with content takes two `update_doc` calls: + +1. **Call 1:** `create_block` with `block_type: "notice_box"` and `theme: "INFO" | "TIPS" | "WARNING" | "GENERAL"`. Capture the returned block ID. +2. **Call 2:** `create_block` with `parent_block_id: "<notice_box_id>"` and the child block content (typically text). + +Theme cannot be changed after creation - use `replace_block` to swap themes, but child content does not transfer; recreate the children inside the new notice_box. + +## Layouts + +The `layout` block type creates a multi-column layout (2-6 columns). **Cell content cannot be populated via the API at all.** No markdown shortcut, no `parent_block_id` support. Layouts created via the API are empty shells the user fills from the monday UI. + +If the user asks for "a two-column section with a summary on the left and metrics on the right", call this out: build the layout shell via `create_block`, then ask the user to fill the cells in the UI, or fall back to a different shape (heading + sub-headings, or a single-column with a separator). + +## Mentions + +`{insert: {mention: {id, type}}}` tags a user, doc, or board inline. Three types: + +- `USER` (most common). `id` is the numeric user ID from `list_users_and_teams`. +- `DOC`. `id` is the doc's `object_id`. +- `BOARD`. `id` is the board ID. + +Resolution rules: + +- The user gives a name ("tag Daniel"): call `list_users_and_teams` with `name: "Daniel"` to get the ID. Confirm the match if multiple results. +- The user gives an email: search by the local-part as a name (e.g. `daniel.h` for `daniel.h@example.com`); fall back to asking for the display name. +- **Never call `list_users_and_teams` without a `name` or `userIds` parameter.** The unfiltered call returns the entire account user list (hundreds of KB on real tenants) and breaks token limits. + +Mention blots ignore `attributes`. Do not try to bold or color a mention. + +## Live column-value embeds - the differentiator + +`{insert: {column_value: {item_id, column_id}}}` embeds the current value of a column on a specific board item, rendered live every time the doc is opened. This is the capability ecosystem builders should reach for - it turns a static doc into a living dashboard fragment. + +Use cases worth scaffolding: + +- **Weekly update:** embed the status, owner, and due date of the top 5 priorities. +- **RFC:** embed the linked tracking item's status so reviewers see whether the work has shipped. +- **Runbook:** embed the on-call rotation column and the current incident's status. +- **Project tracker summary:** at the top of a project doc, embed key milestones' due dates and statuses. + +Resolution rules: + +- Validate `item_id` exists via `get_board_items_page` or `get_full_board_data` 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. +- Be careful with private boards: embedded column values respect board permissions, so a viewer without access to the source board sees nothing. + +## Comments + +`add_comment` operates at three scopes: + +- **Doc-level**: omit `block_id`. The comment is attached to the doc as a whole. +- **Block-level**: pass `block_id` (or an array of block IDs to highlight several at once). Only works on text, code, list_item, title, and quote blocks - not on divider, table, layout, notice_box, image, video, or giphy blocks. +- **Text-selection**: pass a single `block_id` plus `selection_from` (0-indexed start) and `selection_length`. Only valid on text / code / list_item. + +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`. + +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. diff --git a/skills/monday-forms-builder/SKILL.md b/skills/monday-forms-builder/SKILL.md new file mode 100644 index 0000000..a82f0bb --- /dev/null +++ b/skills/monday-forms-builder/SKILL.md @@ -0,0 +1,227 @@ +--- +name: monday-forms-builder +description: | + Creates and edits monday.com WorkForms - public intake forms that capture + responses as new items on a backing board. Useful for request intake, bug + reports, lead capture, event signups, internal submissions, and any flow + that turns a user-submitted form into a tracked work item. + Use when user asks to "create a form", "build an intake form", "make a + WorkForm", "add a question to my form", "edit form questions", "publish + a form", "share a form link", "set up a request form", "add a form to a + board", "remove the monday branding from my form", or "deactivate the + form". +license: MIT +metadata: + author: monday.com + version: "0.1.1" +--- + +# 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. + +## Core constraint - read this first + +**WorkForms only create new items. They cannot update existing items.** This is a hard platform constraint, not a skill limitation. If a user asks for a form that "lets people update their tickets" or "edit existing entries", redirect them: a new submission can be linked to an existing item via a connected-boards question, but submitting the form will always create a new row on the form's board. For status-update style flows, suggest a different approach (an item-level update field, a separate update-tracking board, or an automation that finds-and-updates by reference). + +## 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. + +## 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`. + +### Step 2: Decide the form's purpose, then call `create_form` + +The form's purpose dictates the question set. Common shapes: + +- **Bug report:** title, severity, environment, steps to reproduce, screenshot upload, reporter email. +- **Feature request:** title, description, use case, business impact, customer count, link. +- **Lead capture:** name, work email, company, role, what brought you here. +- **Event signup:** name, email, dietary needs, session preferences. +- **Internal request:** requester, request type (single-select), context, deadline, priority. + +Call `create_form` with: +- `destination_workspace_id` (required) +- `destination_name` (board name; defaults to the form title if omitted) +- `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 + +Capture the returned `formToken` - you need it for every subsequent edit. + +**`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. + +### Step 3: Build the question set + +Use `form_questions_editor` with `action: "create"` for each question. Decide question type from the field's intent: + +| Intent | Type | +|---|---| +| 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) | +| Many-of-many | `MultiSelect` | +| Numeric | `Number` | +| Money / quantity / score | `Number` | +| Date | `Date` | +| Date range | `DateRange` | +| Email | `Email` | +| Phone | `Phone` | +| Web URL | `Link` | +| Country | `Country` | +| Address / map point | `Location` | +| File upload | `File` | +| Rating (1-5) | `Rating` | +| Person / assignee | `People` | +| Static instructions | `DISPLAY_TEXT` | +| Section heading | `PAGE_BLOCK` | +| Linked existing item | `ConnectedBoards` | +| Submitter name | `Name` | +| Comment / update field | `Updates` | +| E-signature | `Signature` | + +Set `required: true` only for fields that genuinely block submission. Excess required fields cut response rate. + +For `SingleSelect` and `MultiSelect`, `options` is required. Each option needs a `label` and a stable `value`. The platform may normalize string `value`s into numeric strings (`"0"`, `"1"`, `"2"`...) on creation, so the `value` you send is best-effort - always call `get_form` after creation to read back the canonical option values before any later edit. The canonical value must not change after the form has live submissions - changing it breaks data integrity for past responses. + +### 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. + +### 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: + +``` +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. + +### 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 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. + +## 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 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.) + +### Step 2: Fetch current state + +Call `get_form` with the formToken. This returns questions, structure, appearance, and feature flags. Always read before writing - patches are merge-style and missing context leads to broken updates. + +### Step 3: Apply the change + +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"`. +- **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. + +### Step 4: Confirm + +Plain-language summary: what changed, what stayed the same, and the form URL. Do not narrate the API calls. + +## Common edits + +**Add a question to the end:** `form_questions_editor` with `action: "create"`, no `insert_after_question_id`. The question appends. + +**Insert a question between two existing ones:** call `get_form` to get the predecessor's ID, then create with `insert_after_question_id: "<predecessor_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. + +**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. + +**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. + +**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. + +**Drop the WorkForms branding (Pro+):** `update_form` with `action: "updateAppearance"` and `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: "<ISO timestamp>"`. + +**Password-protect the form:** `update_form` with `action: "setFormPassword"` and `formPassword: "<password>"`. Communicate the password separately - it does not appear in the form URL. + +## Smart defaults + +When the user does not specify all values: + +- **Form name and board name:** if the user gives the form a name, default the backing board's name to match. State the default in the response. +- **Workspace:** ask once if not provided. Do not guess. +- **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. +- **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. +- **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. + +Do not use `show-table` to confirm a single edit - the form URL plus a one-line confirmation is enough. + +## Be conservative on destructive operations + +Always confirm before: + +- Deleting a question with prior submissions (data is lost). +- Deleting a select option that has been used (past responses for that option become orphaned). +- Deactivating a public-facing form (existing links break). +- Deleting the backing board (deletes the form too). + +Single-question creates and non-destructive edits do not need extra confirmation - the user already asked. + +## Tools used + +- `list_workspaces` - locate the destination workspace if not provided +- `create_form` - create the form and its backing board (returns `formToken`) +- `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 + +## 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. +- 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 new file mode 100644 index 0000000..25ebb46 --- /dev/null +++ b/skills/monday-onboard-to-monday/SKILL.md @@ -0,0 +1,143 @@ +--- +name: monday-onboard-to-monday +description: | + First-run onboarding for people who just connected monday.com and have not + set anything up yet. Builds a ready-to-use board tailored to the user's work + in a few minutes, using what you already know about them to skip generic + questions. Use only when the user asks to "onboard me to monday", "get me + started with monday.com", "set up monday for me", "help me get started", + or sends the post-connect starter prompt. Do not use for requests about an + existing board, item, doc, or workflow - use the matching skill instead. +license: MIT +metadata: + author: monday.com + version: "0.1.0" +--- + +# 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. + +The board itself is built by `create_board` with a `creationPrompt` - monday designs the groups and columns from a free-text description. This skill decides *what* to ask for, then checks the result and fills any gaps. Use the **monday-task-management** skill for column value formats and write-failure handling. + +## Principles + +- **Propose first, ask second.** Do not open with a questionnaire. Draft a setup from what you already know, then ask one confirmation question. +- **Be transparent about what you inferred.** Say what you are basing the proposal on so the user can correct it. +- **Work context only.** Use the user's role, team, company, current projects, and tools. Never put personal or sensitive details (health, family, finances, private conversations) into the creation prompt, board names, items, or descriptions. +- **Fast.** Aim for one confirmation, one build, one first action. Use smart defaults and state them; do not ask about things that have a reasonable default. + +## Workflow + +### Step 1: Confirm this is a new user + +Call `get_user_context`. + +- Tell the user, in one line, which account and workspace they are connected to. +- **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). +- **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. + +### Step 2: Build a picture of the user's work + +Use what you already know about the user from this conversation and from earlier conversations or memory, if available: their role, team, company or industry, and what they are working on now (projects, launches, clients, hiring, events). + +- **If you know enough** to guess what they would track, go straight to Step 3. +- **If you know little or nothing,** ask at most three short questions, in one message: + 1. What kind of work do you want to manage here? (e.g. projects, clients/deals, content, requests, hiring, an event) + 2. What is one real thing you are working on right now? + 3. Is this just for you, or for a team? + +### Step 3: Propose a tailored setup + +Decide on: + +- **Board name** from their real work (e.g. "Q4 Product Launch", "Acme Client Pipeline"), not "My Board". +- **What the board tracks and how work flows** (stages, the key fields per item - owner, due date, priority, value, etc.). +- **3-5 starter items from their actual work** - real milestones, clients, or tasks you know about or that they just mentioned - never "Task 1". Spread due dates over the next two weeks. +- **One starter automation** (see "Starter automations" below). + +Present it compactly and ask one question, for example: + +> Based on what I know - you lead marketing at Acme and you are planning the Q4 launch - I would set up a **Q4 Launch Tracker** that tracks each launch task through To Do / In Progress / In Review / Done, with an owner, due date and priority, starting with: Finalize messaging, Launch landing page, Partner email, Launch day checklist - plus an automation that notifies the owner when a task gets stuck. Should I build it, or change anything first? + +If they change something, adjust and build. Do not re-confirm after small changes. + +### 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: + + > 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. + +### 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: "<current top group id>") { id }`. +- **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. + +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. + +### Step 6: Add the starter automation + +Ask before creating it (it can be part of the Step 3 confirmation). + +1. Call `create_automation` with the `boardId` and a structured description (Trigger / Conditions / Actions) in the user's terms, using the real column and group names from Step 5. If it returns `needs_clarification`, ask for the missing details and call it again. +2. **Read it back.** Call `list_automations` for the board and check that the trigger and conditions match the request - in particular that a "status changes to X" trigger does not also require the previous status to be X, and that conditions are not inverted. If it is wrong, deactivate it with `manage_automations` (`action: "deactivate"`) and recreate it. +3. If `manage_automations` returns `USER_UNAUTHORIZED` for an automation you just created, do not retry - tell the user to turn it off from the board's Automations panel. +4. If `create_automation` is rejected because of the plan or trial, skip it, mention automations are available on paid plans, and continue. Do not let this block the board. + +### 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.) +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. + +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) + +Stop there. Do not chain further setup unless the user asks. + +## Starter automations + +Pick the one that fits the board, using its real column, label, and group names: + +| Board type | Starter automation | +|---|---| +| Projects / tasks / sprints | When Status changes to Done, move the item to the Done group | +| Clients / deals / CRM | When Stage changes to Closed Won, move the item to the Closed Won group | +| Content | When the publish date arrives, notify the author | +| Requests / intake | When a new item is created, notify the assignee | +| Bugs / issues | When Severity changes to Critical, notify the assignee | +| Events / anything else | When Status changes to Stuck, notify the owner | + +## 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 +- `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 +- `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 diff --git a/skills/monday-task-management/SKILL.md b/skills/monday-task-management/SKILL.md new file mode 100644 index 0000000..3dca4f6 --- /dev/null +++ b/skills/monday-task-management/SKILL.md @@ -0,0 +1,263 @@ +--- +name: monday-task-management +description: | + Creates, updates, assigns, and manages items across monday.com boards. monday.com + is a customizable AI work platform with dedicated products for work management, + CRM, dev, service, and campaigns. Handles correct column value formatting for all column types. + Use when user asks to "create a task", "add an item", "update status", "assign to", + "change due date", "move item", "mark as done", "create a subitem", "add a comment", + or "update the priority". +license: MIT +metadata: + author: monday.com + version: "0.2.0" +--- + +# Task Management + +Create, update, assign, and manage items on monday.com boards. In monday.com, every row on a board is an "item" - it could represent a task, a deal, a bug, a content piece, or any unit of work. This skill teaches the correct column value formatting required by monday.com's API - the most common source of errors when working with the platform programmatically. + +## Critical Precondition + +**Before creating or updating any item, ALWAYS call `get_board_info` first** to retrieve the board's column definitions. You need: +- Column IDs (e.g., `status`, `date4`, `person`) +- Column types (e.g., `status`, `date`, `people`) +- Status label mappings (e.g., which index maps to "Done") +- Allowed values for dropdown columns + +Without this step, column value writes will fail silently or set incorrect values. + +## Workflow: Create an Item + +### Step 1: Find the target board + +If the user specifies a board name: +1. Call `search` with the board name to find it +2. Confirm the match with the user if multiple results + +If the user doesn't specify: +1. Call `get_user_context` to list their boards +2. Ask which board to use + +### Step 2: Get board structure + +Call `get_board_info` with the board ID. Note: +- All column IDs and their types +- Group IDs and names (to know where to place the item) +- Status label options (the exact label strings like "Working on it", "Done") + +### Step 3: Get column type details (if needed) + +If you need to understand the exact format for a column type, call `get_column_type_info` with the column type. This returns the JSON schema and validation rules. + +### Step 4: Create the item + +Call `create_item` with: +- `boardId`: the target board ID +- `groupId`: the group to place the item in (from Step 2) +- `itemName`: the item name +- `columnValues`: a JSON string with column values (see formatting guide below) + +### Step 5: Confirm and follow up + +After creation: +- Report what was done in plain language - don't narrate the API calls +- Include the item name, board name, and the direct URL returned by the MCP tool +- Suggest 2-3 logical next steps, for example: + - "Want me to assign someone to this?" + - "Should I set a due date?" + - "Want me to break this into subitems?" + - "Should I add a comment with more context?" + +## Workflow: Update an Item + +### Step 1: Locate the item + +If the user provides an item name but not an ID: +1. Call `get_board_info` to understand the board structure +2. Call `get_board_items_page` with a search query to find the item +3. **Cross-check returned names against the user's target name.** `get_board_items_page` with `searchTerm` behaves as a relevance sort, not a strict name filter - when no true match exists, it still returns items, ranked by partial overlap. Before writing, scan the returned list for an exact (case-insensitive) or near-exact name match. If none of the returned items name-match the target, treat the search as a no-match result and route to step 4, even though the response was non-empty. +4. If multiple results match, confirm the match with the user before writing +5. If no results name-match, do not silently fail and do not write to the closest-ranked but wrong-name item. Ask the user to confirm the name, suggest the closest matches you saw, or offer to list the board's items + +### Step 2: Get board structure + +Call `get_board_info` if not already done. You must know the column IDs and types before writing values. + +### Step 3: Update column values + +Call `change_item_column_values` with: +- `boardId`: the board ID +- `itemId`: the item ID +- `columnValues`: a JSON string with only the columns being changed + +### Step 4: Confirm + +Report what was changed in plain language: item name, which fields were updated, and the new values. Always include the direct URL. Don't describe which API tools were called. + +## When to use MCP UI widgets + +Default to plain text confirmations. Reach for `show-assign` when the user asks to assign work and needs to pick from a long list of teammates - the widget renders a person picker that the user can interact with. For single-person assignments where the user has already named the assignee, just look up the user ID via `list_users_and_teams` and write directly without the widget. + +Do not use `show-table` to confirm a single create or update - plain text plus the item URL is cleaner. + +## Column Value Formatting Guide + +The `columnValues` parameter for `create_item` and `change_item_column_values` is a JSON string. Each column type requires a specific format. **Getting this wrong is the #1 cause of failures.** + +For the complete formatting reference with all column types, see **`references/column-value-formats.md`**. + +Quick reference for the most common types: + +**Status** - Use `{"label": "Done"}` with the exact label string from `get_board_info`: +```json +{"status_column_id": {"label": "Done"}} +``` + +**Date** - Use `{"date": "YYYY-MM-DD"}`: +```json +{"date_column_id": {"date": "2025-06-15"}} +``` + +**People** - Use `{"personsAndTeams": [{"id": USER_ID, "kind": "person"}]}`: +```json +{"person_column_id": {"personsAndTeams": [{"id": 12345678, "kind": "person"}]}} +``` + +**Text** - Plain string value: +```json +{"text_column_id": "Some text value"} +``` + +**Numbers** - Plain string of the number: +```json +{"numbers_column_id": "42"} +``` + +**Email** - Use `{"email": "...", "text": "..."}`: +```json +{"email_column_id": {"email": "user@example.com", "text": "Contact"}} +``` + +**Phone** - Use `{"phone": "...", "countryShortName": "..."}`: +```json +{"phone_column_id": {"phone": "+15551234567", "countryShortName": "US"}} +``` + +**Dropdown** - Use `{"labels": ["Option 1", "Option 2"]}`: +```json +{"dropdown_column_id": {"labels": ["High Priority"]}} +``` + +**Timeline** - Use `{"from": "YYYY-MM-DD", "to": "YYYY-MM-DD"}`: +```json +{"timeline_column_id": {"from": "2025-06-01", "to": "2025-06-30"}} +``` + +**Link** - Use `{"url": "...", "text": "..."}`; `text` is required (repeat the URL if there is no label): +```json +{"link_column_id": {"url": "https://example.com", "text": "Example"}} +``` + +**Checkbox** - Use `{"checked": "true"}`; to uncheck, `{"checked": "false"}` or `null`. A bare `true` / `false` fails: +```json +{"checkbox_column_id": {"checked": "true"}} +``` + +Email, phone, and link fail as plain strings - always send the object. + +### Multiple columns at once + +Combine multiple column updates in a single JSON string: +```json +{ + "status": {"label": "Working on it"}, + "date4": {"date": "2025-06-15"}, + "person": {"personsAndTeams": [{"id": 12345678, "kind": "person"}]}, + "text0": "Implementation notes here" +} +``` + +## Creating Subitems + +To create a subitem, call `create_item` with the `parentItemId` parameter set to the parent item's ID. The subitem will be created on the parent item's subitem board. + +Note: Subitem boards have their own column structure. Call `get_board_info` on the subitem board to get its column definitions before setting column values. + +## Adding Comments + +To add a comment or update to an item, call `create_update` with: +- `itemId`: the item ID +- `body`: the comment text (supports basic HTML: `<b>`, `<i>`, `<a>`, `<ul>`, `<li>`) + +## Common Patterns + +**Mark as done:** Get the board's "done" status label from `get_board_info`, then call `change_item_column_values` with `{"status_column_id": {"label": "Done"}}`. After confirming the status change, check whether the board has a matching terminal group (Done, Closed, Completed, Resolved, Fixed, Won, Lost, Archived) and the item is not already in it. If so, offer it as a next step: "Want me to also move it to the Done group?" Do not auto-move - some boards intentionally keep items in their original group regardless of status, so always ask first. + +**Reassign:** Get the new person's user ID from `list_users_and_teams`, then call `change_item_column_values` with the people column format. + +**Batch creates and updates:** Use `create_items` (up to 20 items per call; each item picks its own group, parent, or template item) and `update_items` (up to 40 updates per call, can span boards). Each entry succeeds or fails on its own, so read the per-item results and retry only the failed entries. Use `create_item` / `change_item_column_values` for single items. + +**Move to group:** The MCP toolkit has no direct "move item" tool (`move_object` is for boards/folders/overviews, not items). Use `all_monday_api` with the `move_item_to_group` mutation: `mutation { move_item_to_group (item_id: <ID>, group_id: "<GROUP_ID>") { id } }`. Do not use `create_item` with `duplicateFromItemId` for moves - that creates a copy and leaves the original in place. + +**Duplicate items into another group:** `create_items` with `duplicateFromItemId` ignores `groupId` - the copy always lands in the source item's group. Duplicate first, then move each copy with `move_item_to_group`. The duplicate response reports the name as "<original> (copy)" even when your new name was applied, so read the item back before telling the user its name. + +## Smart Defaults + +When the user doesn't specify all values: +- **Status**: Default to the first non-done label (usually "Not Started" or "Working on it") - check the board's label order via `get_board_info`. State the default in your response. +- **Group**: Choose a group in this order. (1) If any group's name matches a backlog-pattern (case-insensitive: `To Do`, `Todo`, `Backlog`, `New`, `Open`, `Not Started`, `Inbox`, `Lead`, `Triage`), use that. (2) Otherwise, use the top non-terminal group. A terminal group is one whose name matches a done-pattern (case-insensitive: `Done`, `Closed`, `Completed`, `Complete`, `Verified`, `Resolved`, `Fixed`, `Won`, `Lost`, `Archived`, `Cancelled`, `Canceled`). (3) If every group is terminal, ask the user which group to use rather than guess. Some monday boards return "Done" as the first group from the API, so do not blindly use `groups[0]`. Always state which group you used so the user can override. +- **Person**: If the user is known and the board has a people column, offer to assign to them. Do not auto-assign without asking. + +## Bulk Operations + +When creating or updating 5+ items in one request: +- Batch them with `create_items` / `update_items` instead of one call per item +- Process all items, then present a count summary and a link to the board +- Don't list every individual item - say "Created 12 items on the Marketing board" with the board URL +- If any items fail, report the failure count and reasons separately + +For bulk **destructive** operations (3+ updates that could be hard to reverse), confirm with the user before executing. + +**Bulk subitems on a board with no subitems yet.** The subitems board is created lazily on the first subitem, and a batch sent before it exists fails intermittently with missing-column errors. Create the first subitem alone with `create_item` (`parentItemId`), call `get_board_info` on the subitems board to get its column IDs, then batch the rest with `create_items`. + +**Dropdown and status labels in bulk.** Reuse the exact existing label strings from `get_board_info`. Only set `createLabelsIfMissing: true` when the user wants a genuinely new label. For **dropdown** columns, a new label in a batch is created once per entry: three entries with `createLabelsIfMissing: true` and the new label "Beta" leave three "Beta" labels on the column. Create one item with the new label first, then batch the rest without `createLabelsIfMissing` (the label now exists). Status columns do not duplicate this way, but still send each new label spelled the same in every entry. + +## Error Prevention and Remediation + +1. **Always call `get_board_info` first** - never guess column IDs or status labels +2. **Use exact status label strings** - "Working on it" not "working on it" (case-sensitive) +3. **Check column type before writing** - a `status` column and a `color` column use different formats +4. **Stringify the columnValues** - the parameter expects a JSON string, not a JSON object +5. **Validate person IDs** - use `list_users_and_teams` to get valid user IDs before assigning. Always pass the `name` parameter (or `userIds` if known) to scope the query. Calling `list_users_and_teams` with no parameters returns the entire account user list and will exceed token limits on large tenants. If the user provides an email, search by the local-part as a name first (e.g. "alex.po" for `alex.po@example.com`); if no match, ask the user to provide the person's display name + +When an MCP call fails, do not pass the raw error through. Diagnose and propose a fix: + +- "Status label 'Done!' not found on this board. The board uses 'Done' (no exclamation). Should I use that?" +- "Person ID 12345 is not in your account. Want me to list available users so you can pick the right one?" +- "Permission denied on this board - it is private and you are not subscribed. Want me to ask the owner to add you, or pick a different board?" + +**Write tool fails while reads work.** If a write tool (`create_item`, `create_items`, `update_items`, `change_item_column_values`, `create_column`, `create_board`) is missing from the tool list, or returns "Resource not found", `USER_UNAUTHORIZED`, or 403 on a board you just read successfully, retry the same call once. If it fails again, stop - do not loop or try other write tools against the same board. Tell the user the connector session lost write access, ask them to disconnect and reconnect the monday.com connector, and offer to report it with `submit_bug_or_feature_request`. + +**Expected boards are missing or the workspace looks empty.** Call `get_user_context` and tell the user which account they are connected to. Users with the same email on several monday accounts are often connected to the wrong one; reconnecting and picking the right account fixes it. + +## Tools Used + +- `get_user_context` - find user's boards +- `search` - find boards by name +- `get_board_info` - board structure, column IDs, status labels (REQUIRED before writes) +- `get_column_type_info` - detailed column type schema and validation rules +- `get_board_items_page` - find items by name or filter +- `create_item` - create new items or subitems +- `create_items` - create up to 20 items or subitems in one call +- `change_item_column_values` - update column values on existing items +- `update_items` - update up to 40 items in one call, across boards +- `create_update` - add comments to items +- `all_monday_api` - for the `move_item_to_group` mutation when moving items between groups +- `list_users_and_teams` - look up user IDs for people columns +- `submit_bug_or_feature_request` - report a write tool that keeps failing after a retry +- `show-assign` (selectively) - person-picker widget when user is choosing from many teammates + +## Additional Resources + +- **`references/column-value-formats.md`** - Complete column value formatting reference for all monday.com column types diff --git a/skills/monday-task-management/references/column-value-formats.md b/skills/monday-task-management/references/column-value-formats.md new file mode 100644 index 0000000..a6e6110 --- /dev/null +++ b/skills/monday-task-management/references/column-value-formats.md @@ -0,0 +1,283 @@ +# Column Value Formats Reference + +Complete formatting reference for all monday.com column types. Use this when constructing the `columnValues` JSON string for `create_item` or `change_item_column_values`. + +The `columnValues` parameter is always a JSON string. Each key is a column ID (from `get_board_info`), and each value follows the format specific to that column's type. + +## Status + +Sets the status label. Use the exact label string from the board's status column settings (returned by `get_board_info`). + +```json +{"status_column_id": {"label": "Done"}} +``` + +Common labels: "Working on it", "Done", "Stuck", "Not Started". Labels are case-sensitive and board-specific. + +By label index instead of text: +```json +{"status_column_id": {"index": 1}} +``` + +The label must already exist on the column. To add a missing label while writing, set `createLabelsIfMissing: true` on the `create_items` / `update_items` entry. + +## Date + +Sets a date value. Format: `YYYY-MM-DD`. + +```json +{"date_column_id": {"date": "2025-06-15"}} +``` + +With time (optional): +```json +{"date_column_id": {"date": "2025-06-15", "time": "14:30:00"}} +``` + +## Timeline + +Sets a date range. Both `from` and `to` are required. + +```json +{"timeline_column_id": {"from": "2025-06-01", "to": "2025-06-30"}} +``` + +## People + +Assigns one or more people or teams. + +Single person: +```json +{"person_column_id": {"personsAndTeams": [{"id": 12345678, "kind": "person"}]}} +``` + +Multiple people: +```json +{"person_column_id": {"personsAndTeams": [ + {"id": 12345678, "kind": "person"}, + {"id": 87654321, "kind": "person"} +]}} +``` + +Team: +```json +{"person_column_id": {"personsAndTeams": [{"id": 98765, "kind": "team"}]}} +``` + +AI agent (use the agent's user id, never `kind: "person"`): +```json +{"person_column_id": {"personsAndTeams": [{"id": 55555, "kind": "agent"}]}} +``` + +Get valid user/team/agent IDs from `list_users_and_teams`. + +## Text + +Plain string value. + +```json +{"text_column_id": "Any text content here"} +``` + +## Long Text + +Rich text content. Supports basic HTML. + +```json +{"long_text_column_id": {"text": "Detailed description with <b>bold</b> and <i>italic</i>"}} +``` + +## Numbers + +String representation of the number. + +```json +{"numbers_column_id": "42.5"} +``` + +## Email + +Object with email address and display text. + +```json +{"email_column_id": {"email": "user@example.com", "text": "Contact"}} +``` + +The `text` field controls the display label and is required. If unsure, repeat the email address. **A plain string (`"user@example.com"`) or an object without `text` fails** - always send both fields. + +## Phone + +Object with phone number and country code. + +```json +{"phone_column_id": {"phone": "+15551234567", "countryShortName": "US"}} +``` + +The `phone` value is digits only with an optional leading `+` - no spaces, dashes, or parentheses. `countryShortName` is the uppercase ISO 3166-1 alpha-2 code. **Always send the object.** A plain string is not safe: a formatted one like `"+1 (212) 555-1234"` is split on the first space and saved wrong or rejected, and a digits-only one saves with no country. + +## Link + +URL and display text. Both are required. + +```json +{"link_column_id": {"url": "https://example.com", "text": "Example Site"}} +``` + +A plain URL string or `{"url": "..."}` without `text` fails. If there is no better label, repeat the URL as the `text`. + +## Dropdown + +One or more labels from the column's predefined options. + +Single option: +```json +{"dropdown_column_id": {"labels": ["High Priority"]}} +``` + +Multiple options: +```json +{"dropdown_column_id": {"labels": ["Frontend", "Backend"]}} +``` + +Use exact label strings from the column's settings (returned by `get_board_info`), or label IDs: + +```json +{"dropdown_column_id": {"ids": [1]}} +``` + +Always an array, even for one value. `{"label": "High Priority"}` (single object) is rejected. + +## Connect Boards (board relation) + +IDs of the linked items on the connected board. + +```json +{"board_relation_column_id": {"item_ids": [12345, 67890]}} +``` + +Some tool descriptions say to call `link_board_items_workflow` first. If that tool is not in your tool list, write `item_ids` directly as above. + +**Verify with `linked_item_ids`, not the write response.** The `update_items` response and the raw `text` / `value` fields show `null` for a board relation even when the link saved. Check it with `get_board_items_page` (which lists the linked items) or with `all_monday_api`: `items(ids: [<id>]) { column_values(ids: ["<col>"]) { ... on BoardRelationValue { linked_item_ids } } }`. Do not rewrite a relation because it reads back as `null`. + +## Checkbox + +The `checked` key wrapped in an object. + +```json +{"checkbox_column_id": {"checked": "true"}} +``` + +`{"checked": "true"}` and `{"checked": true}` check the box. To uncheck, send `{"checked": "false"}` or `null`. A bare `true` / `false` without the object is rejected. + +## Rating + +Integer from 1 to 5 (or the column's configured max). + +```json +{"rating_column_id": {"rating": 4}} +``` + +## Tags + +Array of tag IDs. + +```json +{"tags_column_id": {"tag_ids": [12345, 67890]}} +``` + +## Country + +Country code and name. + +```json +{"country_column_id": {"countryCode": "US", "countryName": "United States"}} +``` + +## Location + +Geographic location. + +```json +{"location_column_id": {"lat": "40.7128", "lng": "-74.0060", "address": "New York, NY"}} +``` + +`lat` and `lng` are required and must be strings. An address alone fails. + +## World Clock + +Timezone identifier. + +```json +{"world_clock_column_id": {"timezone": "America/New_York"}} +``` + +## Week + +Start and end date of a week. + +```json +{"week_column_id": {"week": {"startDate": "2025-06-09", "endDate": "2025-06-15"}}} +``` + +## Hour + +Time value. + +```json +{"hour_column_id": {"hour": 14, "minute": 30}} +``` + +## Color Picker + +Nested hex color object. + +```json +{"color_picker_column_id": {"color": {"hex": "#FF5733"}}} +``` + +## Combining Multiple Columns + +Pass all column updates in a single JSON string: + +```json +{ + "status": {"label": "Working on it"}, + "date4": {"date": "2025-06-15"}, + "person": {"personsAndTeams": [{"id": 12345678, "kind": "person"}]}, + "text0": "Design the new landing page", + "numbers6": "8", + "dropdown3": {"labels": ["High Priority"]}, + "checkbox9": {"checked": "false"} +} +``` + +## Clearing a Column Value + +To clear a column, pass an empty string or null: + +```json +{"column_id": ""} +``` + +Or for object-type columns: +```json +{"column_id": null} +``` + +## Common Mistakes + +1. **Wrong status label** - Labels are case-sensitive and board-specific. Always check `get_board_info` first. +2. **Using column name instead of ID** - The key must be the column ID (e.g., `status`, `date4`), not the display name (e.g., "Status", "Due Date"). +3. **Missing nested structure** - Status requires `{"label": "..."}`, not just `"Done"`. Date requires `{"date": "..."}`, not just `"2025-06-15"`. +4. **Invalid person ID** - Always verify user IDs with `list_users_and_teams` before assigning. +5. **Incorrect number format** - Numbers must be strings: `"42"` not `42`. +6. **Plain strings for email, phone, or link** - All three need their object form (`{"email", "text"}`, `{"phone", "countryShortName"}`, `{"url", "text"}`), and `text` is required for email and link. +7. **Bare booleans for checkbox** - `true` fails; send `{"checked": "true"}`. +8. **Double-encoded JSON** - `columnValues` is a JSON object serialized once as a string, not a JSON string of a JSON string. + +## Plan-tier note + +Most column types are universal (Free / Basic / Standard / Pro / Enterprise). Two are gated: + +- **Formula columns** (`formula`): Pro and Enterprise plans only. If the user is on Free / Basic / Standard, the create_column call will fail. Suggest a `numbers` column they update manually, or a downstream calculation in a docs/dashboards skill. +- **Mirror columns** (`mirror`): Available on most paid plans but with caveats. Verify before recommending. From a195c1960d1e491a60e08531ab487cb4f31031ca Mon Sep 17 00:00:00 2001 From: Avner Harrari <avnerha@monday.com> Date: Tue, 10 Nov 2026 16:08:43 +0200 Subject: [PATCH 2/5] chore: sync skills from mondaycom/skills@85e3a7e Picks up mondaycom/skills#7: "Don't use for..." boundaries on every skill and docs-collaborator cut to 2,906 body words. check-skills.js now reports 0 errors, 0 warnings. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- skills.json | 9 ++- skills/monday-docs-collaborator/SKILL.md | 73 +++---------------- .../references/block-operations-matrix.md | 2 + .../references/create-modes.md | 17 +++++ .../references/duplicate-detection.md | 34 +++++++++ skills/monday-forms-builder/SKILL.md | 3 +- skills/monday-task-management/SKILL.md | 3 +- 7 files changed, 76 insertions(+), 65 deletions(-) create mode 100644 skills/monday-docs-collaborator/references/duplicate-detection.md diff --git a/skills.json b/skills.json index 898d4b1..92a4d09 100644 --- a/skills.json +++ b/skills.json @@ -1,6 +1,11 @@ { "repo": "https://github.com/mondaycom/skills.git", - "ref": "706a214f26d93f5567d49f89b2f525780e9f756e", + "ref": "85e3a7ec45ec07d0618f796c1609952e4edc15e7", "prefix": "monday-", - "skills": ["task-management", "docs-collaborator", "forms-builder", "onboard-to-monday"] + "skills": [ + "task-management", + "docs-collaborator", + "forms-builder", + "onboard-to-monday" + ] } diff --git a/skills/monday-docs-collaborator/SKILL.md b/skills/monday-docs-collaborator/SKILL.md index 3961f07..63d6a21 100644 --- a/skills/monday-docs-collaborator/SKILL.md +++ b/skills/monday-docs-collaborator/SKILL.md @@ -12,10 +12,11 @@ description: | 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 project-status-report), or building forms (use monday-forms-builder). license: MIT metadata: author: monday.com - version: "0.2.1" + version: "0.2.2" --- # Docs Collaborator @@ -34,24 +35,13 @@ The platform-native value over a raw markdown editor lives in three things most ## Block operation routing - the non-obvious part -Each block type has a different set of allowed mutations. Picking the wrong operation is the #1 cause of "the call succeeded but the doc looks wrong" bugs. +Each block type has a different set of allowed mutations. Picking the wrong operation is the #1 cause of "the call succeeded but the doc looks wrong" bugs. The short rule: -| Target block type | Use this operation | Why | -|---|---|---| -| text (any subtype: NORMAL_TEXT, LARGE_TITLE, MEDIUM_TITLE, SMALL_TITLE, QUOTE) | `update_block` for content edits; `replace_block` to change the subtype (e.g. promote a paragraph to H2) | Subtype is set on creation; `update_block` cannot change it | -| code | `update_block` | Content and language editable in place | -| list_item (BULLETED_LIST, NUMBERED_LIST, CHECK_LIST) | `update_block` for content edits; `replace_block` to switch between bulleted / numbered / check | List variant is set on creation | -| divider | `replace_block` only | No mutable properties | -| table | `replace_block` only | Row / column count and column widths immutable; table cell content not addressable via API after creation - see "Tables" in `references/rich-content.md` | -| image | `replace_block` to swap source | URL / asset_id immutable after creation | -| video | `replace_block` to swap source | raw_url immutable after creation | -| notice_box | `replace_block` to change theme | theme immutable; content lives in child blocks (see "Notice boxes" in `references/rich-content.md`) | -| layout | `replace_block` only | Cell content cannot be populated via API at all - see "Layouts" in `references/rich-content.md` | -| BOARD embed, WIDGET embed, DOC embed, GIPHY | `delete_block` only | No public API to create or modify these block types | +- **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. -**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. - -Full per-block-type detail with worked examples lives in `references/block-operations-matrix.md`. Read it before authoring any non-trivial structural edit. +Read `references/block-operations-matrix.md` before any structural edit: it has the full routing matrix, a list_item rendering quirk, and example payloads. ## Workflow: Create a doc @@ -72,24 +62,13 @@ If the user does not name a workspace, fall back to the user's primary workspace ### Step 3: Compose the body - shapes are examples, not boundaries -`create_doc` takes a `markdown` parameter that is parsed into blocks on import. Keep it to a few sections; append long bodies with `add_markdown_content` (see `references/errors.md`). Reach for one of these common shapes as a starting point when the user names a use case, then extend freely: - -- **Meeting notes:** title, date, attendees (with `@mentions`), agenda bullets, decisions, action items table, follow-ups. -- **Weekly update:** highlights, key metrics, risks, next-week plan. -- **RFC:** problem, proposed solution, alternatives considered, open questions, decision log. -- **Runbook:** trigger, prerequisites, numbered procedure, rollback steps, escalation path. -- **Postmortem:** incident summary, timeline, root cause, what went well, what did not, action items. +`create_doc` takes a `markdown` parameter that is parsed into blocks on import. Keep it to a few sections; append long bodies with `add_markdown_content` (see `references/errors.md`). When the user names a use case (meeting notes, weekly update, RFC, runbook, postmortem), start from its common shape in `references/create-modes.md`, then extend freely. When the user invents a shape ("partner enablement page", "AI readiness snapshot", "Q3 onboarding context"), compose with judgment - sections, tables, notice boxes, embeds - rather than forcing a named template. The differentiators apply to any shape. **Passive vs active mode.** By default, scaffold with visible slot markers (`_[embed: ...]_`, `_[mention: ...]_`) where embeds and mentions belong. Switch to active mode - wiring real embeds and mentions - when the user refers to items, boards or people by name; resolve names to IDs yourself (if a name is ambiguous, ask once with the top 3 candidates) and state what you picked. Read `references/create-modes.md` before wiring anything: it has the marker formats, escalation triggers, name-to-ID resolution chain and the communication contract. -Markdown notes that matter: - -- 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 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. +**Put table content in the markdown.** A markdown table is the only way to get pre-filled table cells; cells cannot be populated after creation. Markdown has no syntax for notice boxes, layouts, embeds, mentions, live column values or asset images: add those with `update_doc` after the doc is created. Details in "Markdown notes" in `references/create-modes.md`. ### Step 4: Call `create_doc` @@ -235,36 +214,7 @@ State every default in the response so the user can override. ## Duplicate detection before writing -**Before any `create_block`, `add_markdown_content`, `add_comment`, or content-replacing `update_block`, compare the proposed content against existing blocks in the doc.** Default to skip + report on match; surface options to the user; never silently duplicate. - -Match heuristics by block type: - -| Block type | Match heuristic | -|---|---| -| text / heading / quote / code | exact delta text + same subtype | -| list_item | exact text + same list type + adjacency (multi-bullet sections matched as a group) | -| notice_box | same theme + same child text | -| table | same dimensions + same cell content | -| mention | same user_id at same block position | -| column_value embed | same item_id + column_id at same block position | -| comment | same body text + same anchor (excluded by default - see below) | - -Skill behavior on match found: - -1. **Default: skip + report.** "X already exists at <position>. Skipping to avoid duplicate." -2. **Surface options** (do not silently pick): - - **(a) skip** - keep existing, do nothing - - **(b) duplicate** - proceed as requested, accept redundancy - - **(c) replace** - delete existing, create fresh - - **(d) move** - offered only when the new request has explicit positional intent ("at the top / at the bottom / after X") that conflicts with the existing match's position - -Exclusions where duplication is normal and detection should NOT trigger: - -- **Comments are excluded** except for a short stutter window. Same comment body submitted to the same scope (doc or block) within 60 seconds is almost certainly a double-submit / network retry; beyond that, treat as legitimate (legitimate re-review, sentiment echo). -- Adjacent same-style blocks in a list - intended structure, not duplication. -- Repeating section names in different parents (e.g. two "Action Items" H3s under different H2s). - -Apply this duplicate-detection rule to every write path in the skill. +**Before any `create_block`, `add_markdown_content`, `add_comment`, or content-replacing `update_block`, compare the proposed content against existing blocks in the doc.** On a match, skip and report it, then offer the user: skip, duplicate, replace, or move (move only when the request names a position). Never silently duplicate. Comments are excluded except for a repeat within 60 seconds. Read `references/duplicate-detection.md` for the match heuristic per block type and the full exclusions. ## Surface errors with remediation @@ -305,7 +255,8 @@ Never tell the user "I called `read_docs` then `update_doc` with an `update_bloc ## Additional resources - **`references/block-operations-matrix.md`** - per-block-type allowed operations, gotchas, and example payloads. -- **`references/create-modes.md`** - passive-scaffold slot markers, active-mode triggers, name-to-ID resolution and the communication contract. +- **`references/create-modes.md`** - passive-scaffold slot markers, active-mode triggers, name-to-ID resolution, the communication contract, common doc shapes and markdown notes. +- **`references/duplicate-detection.md`** - match heuristics per block type, what to offer on a match, and when duplication is normal. - **`references/rich-content.md`** - tables, notice boxes, layouts, mentions, live column-value embeds and comments. - **`references/read-rendering.md`** - how to render mentions, embeds and inline elements when reading a doc. - **`references/errors.md`** - common failures and how to remediate them. diff --git a/skills/monday-docs-collaborator/references/block-operations-matrix.md b/skills/monday-docs-collaborator/references/block-operations-matrix.md index 7dc1792..a0eb9ba 100644 --- a/skills/monday-docs-collaborator/references/block-operations-matrix.md +++ b/skills/monday-docs-collaborator/references/block-operations-matrix.md @@ -38,6 +38,8 @@ When matching a read block to a row in this table, normalize on the lowercase ou | `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 | +**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. + ## update_block - the in-place edit path Use for content edits on text, code, and list_item blocks where the subtype is staying the same. diff --git a/skills/monday-docs-collaborator/references/create-modes.md b/skills/monday-docs-collaborator/references/create-modes.md index 6e91ab4..5d329d9 100644 --- a/skills/monday-docs-collaborator/references/create-modes.md +++ b/skills/monday-docs-collaborator/references/create-modes.md @@ -29,3 +29,20 @@ Resolution chain (name -> ID, never ask the user for IDs): - Ambiguous match -> ask once with the top 3 candidates; do not silently pick **Active mode communication contract.** When the skill picks items / users in active mode, always state the choice and the reasoning: "Picked items X, Y, Z because <reason>. Override by naming different items." + +## Common doc shapes + +Starting points when the user names a use case. Extend freely; they are examples, not boundaries. + +- **Meeting notes:** title, date, attendees (with `@mentions`), agenda bullets, decisions, action items table, follow-ups. +- **Weekly update:** highlights, key metrics, risks, next-week plan. +- **RFC:** problem, proposed solution, alternatives considered, open questions, decision log. +- **Runbook:** trigger, prerequisites, numbered procedure, rollback steps, escalation path. +- **Postmortem:** incident summary, timeline, root cause, what went well, what did not, action items. + +## Markdown notes + +- 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 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/duplicate-detection.md b/skills/monday-docs-collaborator/references/duplicate-detection.md new file mode 100644 index 0000000..88f37ec --- /dev/null +++ b/skills/monday-docs-collaborator/references/duplicate-detection.md @@ -0,0 +1,34 @@ +# Duplicate detection before writing + +Detail for "Duplicate detection before writing" in `SKILL.md`. + +**Before any `create_block`, `add_markdown_content`, `add_comment`, or content-replacing `update_block`, compare the proposed content against existing blocks in the doc.** Default to skip + report on match; surface options to the user; never silently duplicate. + +Match heuristics by block type: + +| Block type | Match heuristic | +|---|---| +| text / heading / quote / code | exact delta text + same subtype | +| list_item | exact text + same list type + adjacency (multi-bullet sections matched as a group) | +| notice_box | same theme + same child text | +| table | same dimensions + same cell content | +| mention | same user_id at same block position | +| column_value embed | same item_id + column_id at same block position | +| comment | same body text + same anchor (excluded by default - see below) | + +Skill behavior on match found: + +1. **Default: skip + report.** "X already exists at <position>. Skipping to avoid duplicate." +2. **Surface options** (do not silently pick): + - **(a) skip** - keep existing, do nothing + - **(b) duplicate** - proceed as requested, accept redundancy + - **(c) replace** - delete existing, create fresh + - **(d) move** - offered only when the new request has explicit positional intent ("at the top / at the bottom / after X") that conflicts with the existing match's position + +Exclusions where duplication is normal and detection should NOT trigger: + +- **Comments are excluded** except for a short stutter window. Same comment body submitted to the same scope (doc or block) within 60 seconds is almost certainly a double-submit / network retry; beyond that, treat as legitimate (legitimate re-review, sentiment echo). +- Adjacent same-style blocks in a list - intended structure, not duplication. +- Repeating section names in different parents (e.g. two "Action Items" H3s under different H2s). + +Apply this duplicate-detection rule to every write path in the skill. diff --git a/skills/monday-forms-builder/SKILL.md b/skills/monday-forms-builder/SKILL.md index a82f0bb..f064ccd 100644 --- a/skills/monday-forms-builder/SKILL.md +++ b/skills/monday-forms-builder/SKILL.md @@ -10,10 +10,11 @@ description: | a form", "share a form link", "set up a request form", "add a form to a board", "remove the monday branding from my form", or "deactivate the form". + Don't use for editing the items a form creates (use monday-task-management) or for monday docs (use monday-docs-collaborator). license: MIT metadata: author: monday.com - version: "0.1.1" + version: "0.1.2" --- # Forms Builder diff --git a/skills/monday-task-management/SKILL.md b/skills/monday-task-management/SKILL.md index 3dca4f6..1329c86 100644 --- a/skills/monday-task-management/SKILL.md +++ b/skills/monday-task-management/SKILL.md @@ -7,10 +7,11 @@ description: | Use when user asks to "create a task", "add an item", "update status", "assign to", "change due date", "move item", "mark as done", "create a subitem", "add a comment", or "update the priority". + Don't use for creating a new board (use board-setup), writing or editing monday docs (use monday-docs-collaborator), or building forms (use monday-forms-builder). license: MIT metadata: author: monday.com - version: "0.2.0" + version: "0.2.1" --- # Task Management From a15e9ee9acc9c5e4f15e91d1639d96bb390fc436 Mon Sep 17 00:00:00 2001 From: Avner Harrari <avnerha@monday.com> Date: Tue, 10 Nov 2026 16:11:52 +0200 Subject: [PATCH 3/5] feat: add board-setup and project-status-report skills The boundaries synced from mondaycom/skills#7 send board creation to board-setup and status reports to project-status-report. Without them in the plugin those references point at skills Gemini cannot load. Both pass check-skills.js; the plugin now ships six skills. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- .gemini-plugin/plugin.json | 19 +- CHANGELOG.md | 5 +- README.md | 4 +- skills.json | 6 +- skills/monday-board-setup/SKILL.md | 299 ++++++++++++++++++ .../references/column-types-guide.md | 240 ++++++++++++++ skills/monday-docs-collaborator/SKILL.md | 2 +- skills/monday-project-status-report/SKILL.md | 198 ++++++++++++ skills/monday-task-management/SKILL.md | 2 +- 9 files changed, 764 insertions(+), 11 deletions(-) create mode 100644 skills/monday-board-setup/SKILL.md create mode 100644 skills/monday-board-setup/references/column-types-guide.md create mode 100644 skills/monday-project-status-report/SKILL.md diff --git a/.gemini-plugin/plugin.json b/.gemini-plugin/plugin.json index 68bedc5..b015655 100644 --- a/.gemini-plugin/plugin.json +++ b/.gemini-plugin/plugin.json @@ -2,7 +2,7 @@ "name": "monday-work-management", "displayName": "monday.com", "version": "1.0.0", - "description": "Plan and track work in monday.com from Gemini: create, update and assign items, write docs, and build forms that turn requests into items.", + "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", "email": "support@monday.com", @@ -11,12 +11,23 @@ "repository": "https://github.com/mondaycom/gemini-plugin", "homepage": "https://monday.com/w/mcp", "license": "MIT", - "keywords": ["monday", "project-management", "work-management", "tasks", "boards", "docs", "forms"], + "keywords": [ + "monday", + "project-management", + "work-management", + "tasks", + "boards", + "status-report", + "docs", + "forms" + ], "skills": [ + "./skills/monday-onboard-to-monday/SKILL.md", "./skills/monday-task-management/SKILL.md", + "./skills/monday-board-setup/SKILL.md", + "./skills/monday-project-status-report/SKILL.md", "./skills/monday-docs-collaborator/SKILL.md", - "./skills/monday-forms-builder/SKILL.md", - "./skills/monday-onboard-to-monday/SKILL.md" + "./skills/monday-forms-builder/SKILL.md" ], "mcpServers": "./.mcp.json" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 988a5f5..9b2115d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,5 +4,6 @@ All notable changes to this plugin are documented here. Versions follow [Semanti ## 1.0.0 -- First release for Gemini Agent: the monday.com MCP server (`https://mcp.monday.com/mcp`) and four skills, - `monday-task-management`, `monday-docs-collaborator`, `monday-forms-builder` and `monday-onboard-to-monday`. +- First release for Gemini Agent: the monday.com MCP server (`https://mcp.monday.com/mcp`) and six skills, + `monday-onboard-to-monday`, `monday-board-setup`, `monday-task-management`, `monday-project-status-report`, + `monday-docs-collaborator` and `monday-forms-builder`. diff --git a/README.md b/README.md index c390786..31e5506 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # monday.com for Gemini -Bring monday.com into Gemini. Create, update and assign items, write docs and set up forms from a conversation. +Bring monday.com into Gemini. Set up boards, create, update and assign items, get status reports, write docs and set up forms from a conversation. ## What you get @@ -8,7 +8,9 @@ Bring monday.com into Gemini. Create, update and assign items, write docs and se OAuth), with tools for boards, items, columns, docs, forms, dashboards, workspaces and more. - **Skills** - `monday-onboard-to-monday`: first-run setup. Builds a board tailored to your work, with starter items and an automation. + - `monday-board-setup`: create a board with the right groups, columns and starter items. - `monday-task-management`: create, update, assign and move items, with correct column-value formats. + - `monday-project-status-report`: status reports across boards: overdue items, blockers, workload and recent activity. - `monday-docs-collaborator`: create, read, edit and comment on monday docs, including live column embeds and mentions. - `monday-forms-builder`: create, edit and publish monday WorkForms. diff --git a/skills.json b/skills.json index 92a4d09..a3551a2 100644 --- a/skills.json +++ b/skills.json @@ -3,9 +3,11 @@ "ref": "85e3a7ec45ec07d0618f796c1609952e4edc15e7", "prefix": "monday-", "skills": [ + "onboard-to-monday", "task-management", + "board-setup", + "project-status-report", "docs-collaborator", - "forms-builder", - "onboard-to-monday" + "forms-builder" ] } diff --git a/skills/monday-board-setup/SKILL.md b/skills/monday-board-setup/SKILL.md new file mode 100644 index 0000000..5629d69 --- /dev/null +++ b/skills/monday-board-setup/SKILL.md @@ -0,0 +1,299 @@ +--- +name: monday-board-setup +description: | + Creates and configures monday.com boards with proper structure including groups, + columns, and initial items. monday.com boards are flexible enough to manage any + workflow - project trackers, CRM pipelines, bug trackers, content calendars, + and more. Use when user asks to "create a board", "set up a project", "new board + for", "build a tracker", "organize my project", "create a board for tracking", + or "set up a workflow". + Don't use for adding or editing items on an existing board (use monday-task-management). +license: MIT +metadata: + author: monday.com + version: "0.2.1" +--- + +# 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. + +## Workflow + +### Step 1: Understand requirements + +Before creating anything, clarify with the user: + +1. **What are you tracking?** (tasks, projects, bugs, leads, requests, events, etc.) +2. **What stages does work go through?** (e.g., To Do > In Progress > Review > Done) +3. **What information do you need per item?** (owner, deadline, priority, status, budget, etc.) +4. **How many people will use this board?** + +If the user gives a brief request like "create a project board", use reasonable defaults based on the use case and confirm the structure before creating. + +### Step 2: Design the board structure + +Based on requirements, plan: + +- **Board name** - clear and descriptive +- **Groups** - represent workflow stages, categories, or time periods +- **Columns** - the data fields for each item (see Column Type Selection below) + +### Step 3: Create the board + +**Strongly recommended: build the board in one call with `creationPrompt`.** `create_board` accepts a free-text `creationPrompt`, and monday designs the groups, columns, and labels from it. This is faster and more reliable than building the structure call by call, and avoids the partial boards and duplicate columns that long build sequences leave behind when a call fails midway. Use it for every new board unless the user needs an exact structure the prompt cannot express. + +Call `create_board` with: +- `boardName`: descriptive name +- `boardKind`: `"public"` (visible to all team members) or `"private"` (visible only to subscribers) +- `workspaceId` (and `folderId` if the user named one) +- `creationPrompt`: the design from Step 2 in plain language - what the board tracks, the workflow stages, the fields each item needs (with label sets for Priority, Stage, etc.), and any starter items. **Leave automations out of the prompt** - they are not created from it. Add each one afterwards with `create_automation` and verify it with `list_automations`. For example: + + > A bug tracker for a mobile team. Bugs move through New, Triaged, In Progress, Fixed, Verified. Each bug needs an assignee, a severity (Low, Medium, High, Critical), a due date, steps to reproduce, and the affected platform (iOS, Android, Web). Starter items: Login button unresponsive on Android, Crash when uploading a photo. + +**After it returns, verify the board against the design - `creationPrompt` gets most of it right but not all.** Call `get_board_info`, `get_board_items_page` (with `includeColumns: true`), and `list_automations`, then check: + +1. **Group order and `top_group`.** Groups can come back out of order, with a terminal group such as "Done" on top - and new items land in `top_group`. Reorder with `update_group` (`relative_position_before`, see Step 4) so the first workflow stage is on top. +2. **Column types.** A field can come back as a different type (e.g. a website as `text` instead of `link`). Add a column of the right type with `create_column`, copy any values over, and tell the user the old column can be deleted. +3. **Labels.** Fix a wrong or missing label set (see "Changing labels on an existing status column"). +4. **Starter items.** Check every value you asked for - some can be left blank. Fill the gaps in one `update_items` call. +5. **Unrequested automations.** `create_board` can add automations nobody asked for, such as monday AI "categorize" rules on a dropdown, which run on every new item and use AI credits. Tell the user what was added and offer to turn each one off; workflows can be deactivated with `manage_automations`, but some cannot be changed through the API - point the user to the board's Automations panel for those. +6. **The Name column title** - rename it if the design calls for "Deal", "Account", etc. + +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. + +Without `creationPrompt` you get an empty board; build it with Steps 4-6. + +### Step 4: Create groups + +Skip this step if `creationPrompt` already created the groups you need. + +Call `create_group` for each workflow stage or category. + +**Position the new groups above the default group.** A new monday board ships with a default empty group named "Group Title" (id `topics`). To put your workflow groups in the right order at the top of the board, pass `positionRelativeMethod: "before_at"` and `relativeTo: "topics"` on each `create_group` call. Create groups in workflow order (the first group you create becomes the first group on the board, and `top_group` - which is where new items will land by default). + +**Clean up the default group at the end.** Once your workflow groups exist, the default `topics` group is a leftover empty group that confuses users. Delete it by calling `all_monday_api` with the `delete_group` mutation: `mutation { delete_group(board_id: <id>, group_id: "topics") { id } }`. Skipping this leaves the board with a dangling empty group below the workflow. + +**Rename or reorder groups** with the `update_group` mutation through `all_monday_api` (there is no `change_group_title` mutation, and `update_group` needs a selection set or it fails): + +- Rename: `mutation { update_group(board_id: <id>, group_id: "<group_id>", group_attribute: title, new_value: "New name") { id title } }` +- Move above another group: `group_attribute: relative_position_before, new_value: "<other_group_id>"` (or `relative_position_after`), selecting `{ id position }`. + +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. + +Common group patterns: + +**By workflow stage** (most common): +- "To Do", "In Progress", "In Review", "Done" + +**By priority:** +- "Critical", "High Priority", "Medium", "Low Priority" + +**By time period:** +- "This Week", "Next Week", "Backlog" + +**By team/department:** +- "Engineering", "Design", "Product", "QA" + +**By category:** +- "Bugs", "Features", "Improvements", "Technical Debt" + +### Step 5: Add columns + +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 +- `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) + +**Add columns in this order** (left to right on the board): +1. Status column (workflow state) +2. Person column (owner/assignee) +3. Date or Timeline column (deadline/duration) +4. Priority column (if needed) +5. Additional data columns (text, numbers, links, etc.) + +**Renaming the Name (first) column.** `update_column` rejects title changes on the `name` column ("Name columns can only be updated with the width parameter"). Use `all_monday_api` instead: `mutation { change_column_title(board_id: <id>, column_id: "name", title: "Task") { id title } }`. This is how to label it "Deal", "Bug", "Request", etc. to match the template. + +#### Custom labels for status columns + +`status` columns created without `columnSettings` always get the default monday labels: "Working on it" (orange), "Done" (green), "Stuck" (red). That is fine for the primary workflow Status column, but it is wrong for any other status column the template needs - Priority, Severity, Stage, and Risk all end up with confusing default labels unless you pass custom ones at creation time. + +Pass `columnSettings` as a JSON string with the shape: + +```json +{"labels": [{"label": "<name>", "color": "<color_token>", "index": <0..n>}, ...]} +``` + +Each entry needs `label`, `color`, and `index` (other fields are optional). The `color` token is a string from monday's StatusColumnColors enum. Useful tokens by category: + +- Calm / low: `sky`, `bright_blue`, `aquamarine`, `saladish` +- Mid / progress: `working_orange`, `egg_yolk`, `purple` +- High / warning: `dark_orange`, `sunset`, `lipstick` +- Critical / blocked: `stuck_red`, `dark_red`, `bright_green` (only for "approved") +- Done / success: `done_green`, `grass_green` + +**Reference label sets to use in the templates below:** + +- **Priority:** `[{"label":"Low","color":"sky","index":0},{"label":"Medium","color":"working_orange","index":1},{"label":"High","color":"dark_orange","index":2},{"label":"Critical","color":"stuck_red","index":3}]` +- **Severity:** same as Priority. +- **Pipeline stage (CRM):** label set should match the named groups (Lead, Qualified, Proposal, Negotiation, Closed Won, Closed Lost) so item-status and group can stay in sync. +- **Risk:** `[{"label":"Low","color":"saladish","index":0},{"label":"Medium","color":"egg_yolk","index":1},{"label":"High","color":"dark_orange","index":2}]` + +If the user requests a status column whose meaning is not workflow ("Priority", "Severity", "Risk", "Stage", "Health", "Confidence", etc.), default to a Low/Medium/High/Critical scale unless they tell you the labels they want. State the defaults you used so they can override. + +For the primary workflow Status column, leave `columnSettings` off - the defaults match what most users expect. + +**Shape and colors.** Send the flat `{"labels": [...]}` object. `get_column_type_info` shows the schema wrapped in a `settings` key - do not copy that wrapper: `create_column` tolerates it, `update_column` rejects it. `color` must be a token from the list above (or its numeric value); hex codes like `#00c875` are rejected. + +**If `create_column` with custom labels returns INTERNAL_SERVER_ERROR,** do not resend the same payload. Create the column without `columnSettings`, then set the labels with `update_column` (below). + +#### Changing labels on an existing status column + +`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.** +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. + +### Step 6: Seed initial items (optional) + +If the user provides initial items and the board does not have them yet, create them in one `create_items` call (up to 20 per call) rather than one `create_item` per item. Follow the column value formatting rules from the monday-task-management skill. + +### Step 7: Present the result + +Report what was built in plain language - don't narrate the API calls. Include the direct URL returned by the MCP tool. + +Summarize what was created: + +**Board Created: [Board Name]** +- URL: [board URL] +- Type: [public/private] + +**Groups:** +1. To Do +2. In Progress +3. In Review +4. Done + +**Columns:** +| Column | Type | Purpose | +|--------|------|---------| +| Status | Status | Workflow state | +| Owner | People | Item assignee | +| Due Date | Date | Deadline | +| Priority | Status | Importance level | +| Notes | Text | Additional context | + +Then suggest 2-3 logical next steps: +- "Want me to add some initial items to get started?" +- "Should I invite team members to this board?" +- "Want me to create a dashboard to track this project?" +- "Should I set up a form for intake requests?" + +## Column Type Selection + +Choosing the right column type is critical. Using a text column where you need a status column means losing filtering, grouping, and automation capabilities. + +For the complete column type reference, see **`references/column-types-guide.md`**. + +Quick selection guide for the most common needs: + +| What you need | Column type | Why not text? | +|--------------|-------------|---------------| +| Workflow state (To Do, In Progress, Done) | `status` | Enables color-coding, filtering by status, automations | +| Who's responsible | `people` | Links to monday.com users, enables workload views | +| Deadline | `date` | Enables calendar view, timeline view, overdue detection | +| Date range (start-to-end) | `timeline` | Shows duration bars in timeline view | +| Importance level | `status` (labeled "Priority") | Color-coded, filterable, sortable | +| Effort estimate | `numbers` | Enables sum, average, and formula calculations | +| Category tags | `dropdown` | Multi-select from predefined options | +| Yes/no flag | `checkbox` | Visual toggle, filterable | +| Free-form notes | `text` | Simple text input | +| Long description | `long_text` | Rich text with formatting | +| File attachments | `file` | Upload and preview files inline | +| Web link | `link` | Clickable URL with display text | +| Email address | `email` | Clickable mailto link | +| Phone number | `phone` | Clickable tel link | +| Budget/cost | `numbers` | Supports currency formatting and formulas | +| Rating | `rating` | 1-5 star visual rating | +| Progress | `progress` | Visual progress bar based on subitems or linked column | + +## Plan-tier awareness + +Most column types work on every monday plan. Two are gated and the skill should handle this gracefully: + +- **Formula column** - Pro and Enterprise plans only. If the user is on Free / Basic / Standard and asks for a formula column (e.g., "I want a column that calculates total cost from quantity and price"), explain the gating and suggest one of: + - A `numbers` column the user updates manually + - A `text` column with a calculated value the user pastes from elsewhere + - Adding the formula calculation to a docs/dashboards skill output instead +- **AI / Automation features at the board level** - some are tier-gated. Create automations with `create_automation`, one trigger per call, and read each back with `list_automations` to confirm the trigger and conditions match the request. If the call is rejected because of the plan or trial, say automations need a paid plan and point the user to the board's Automations panel. + +If the user is unsure of their plan, just create the board with standard columns first and offer to add formula columns later if their plan supports it. + +## 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) + +## 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. +- 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", "<date>"]` is rejected in views, even though `get_column_type_info` guidelines list it - those guidelines are for `get_board_items_page` filters. + +## Tools Used + +- `search` - preflight check for board name collisions before `create_board`, and checking whether a failed `create_board` created the board anyway +- `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_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` +- `update_items` - fill starter-item values the generated board left blank +- `create_automation` - add each requested automation after the board exists +- `list_automations` - verify new automations and spot unrequested ones `create_board` added +- `manage_automations` - deactivate an unrequested or wrong automation +- `all_monday_api` - delete the default `topics` group, rename or reorder groups (`update_group`), and rename the Name column (`change_column_title`) + +## Additional Resources + +- **`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/column-types-guide.md b/skills/monday-board-setup/references/column-types-guide.md new file mode 100644 index 0000000..d8d5cdf --- /dev/null +++ b/skills/monday-board-setup/references/column-types-guide.md @@ -0,0 +1,240 @@ +# Column Types Guide + +Complete reference for all monday.com column types. Use this when deciding which column type to add to a board via `create_column`. + +## Core Column Types + +### status + +Visual color-coded labels representing workflow states. The most important column type in monday.com. + +**Use for:** Workflow state, priority, approval status, risk level - anything with a fixed set of states. + +**Default labels:** "Working on it" (orange), "Done" (green), "Stuck" (red). These ship by default if you do not pass `columnSettings`. Fine for the primary workflow Status column, wrong for Priority / Severity / Stage / Risk. + +**Why use status over dropdown:** Status columns power automations, provide color-coded visual indicators, and are the primary driver of monday.com's workflow engine. Dropdown is for categorization; status is for workflow state. + +**Custom labels at creation time.** Pass `columnSettings` as a JSON-stringified object: + +```json +{"labels": [{"label": "Low", "color": "sky", "index": 0}, {"label": "Medium", "color": "working_orange", "index": 1}, {"label": "High", "color": "dark_orange", "index": 2}, {"label": "Critical", "color": "stuck_red", "index": 3}]} +``` + +`label`, `color`, `index` are required for each entry. The `color` token is a string from monday's StatusColumnColors enum; useful tokens by category: `sky` / `bright_blue` / `aquamarine` (low/calm), `working_orange` / `egg_yolk` / `purple` (mid), `dark_orange` / `sunset` / `lipstick` (high), `stuck_red` / `dark_red` (critical), `done_green` / `grass_green` / `bright_green` (success). The platform assigns each label a permanent numeric `id` that may not match `index` - use `index` to control display order. Never invent an `id`: leave it off new labels, and on `update_column` send each existing label's `id` from `get_board_info` (labels you leave out are deleted - see "Changing labels on an existing status column" in `SKILL.md`). Hex colors are rejected; use the tokens. + +**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). + +### people + +Links to monday.com user accounts. + +**Use for:** Item owner, assignee, reviewer, requester - anyone responsible for or related to the item. + +**Supports:** Multiple people per cell, teams (not just individuals). + +**Why use people over text:** People columns enable workload views, @mentions, notification routing, and "my items" filtering. A text column with someone's name is just a string. + +### date + +Single date value with optional time. + +**Use for:** Deadline, due date, start date, event date - any single point in time. + +**Supports:** Date picker UI, calendar view integration, overdue highlighting. + +### timeline + +Date range with start and end dates. + +**Use for:** Project duration, sprint dates, event period, campaign window - anything with a start and end. + +**Supports:** Gantt chart view, duration calculations, dependency visualization. + +**When to use timeline vs date:** Use `date` for a single deadline. Use `timeline` when you need to show duration (e.g., "June 1-15"). + +### numbers + +Numeric values with optional units. + +**Use for:** Budget, cost, hours, story points, quantity, score - any numeric measurement. + +**Supports:** Sum, average, median, min, max calculations at group and board level. Supports unit prefixes/suffixes (e.g., $, hrs). + +### text + +Short plain text input. + +**Use for:** Brief notes, reference IDs, short descriptions - any free-form text under ~100 characters. + +### long_text + +Rich text with formatting support. + +**Use for:** Detailed descriptions, meeting notes, specifications, instructions - longer content that benefits from formatting. + +**Supports:** Bold, italic, lists, links, code blocks. + +### dropdown + +Multi-select from predefined options. + +**Use for:** Categories, tags, departments, tools, regions - any categorization with a known set of options. + +**Why use dropdown over status:** Use `status` for workflow state (one active state at a time). Use `dropdown` for categorization (can select multiple labels simultaneously). + +### checkbox + +Boolean toggle. + +**Use for:** Approval flags, completion markers, yes/no questions, feature flags. + +### file + +File upload column. + +**Use for:** Attachments, design files, documents, screenshots, deliverables. + +**Supports:** Preview for images and common file types, download links. + +## Communication Columns + +### email + +Email address with mailto link. + +**Use for:** Contact email, customer email, vendor email. + +### phone + +Phone number with tel link. + +**Use for:** Contact phone, support number, vendor phone. + +### link + +URL with display text. + +**Use for:** External references, documentation links, PR links, design file URLs. + +## Advanced Column Types + +### rating + +1-5 star rating. + +**Use for:** Quality scores, satisfaction ratings, effort estimates on a simple scale. + +### progress + +Visual progress bar. + +**Use for:** Completion percentage. Can be configured to auto-calculate based on subitems or linked columns. + +### tags + +Shareable tags across boards. + +**Use for:** Cross-board categorization. Unlike dropdown (board-specific), tags are shared across the account. + +### country + +Country selector with flag icons. + +**Use for:** Geographic location, market region, office location. + +### location + +Geographic coordinates with map integration. + +**Use for:** Addresses, event venues, office locations. + +### world_clock + +Timezone display. + +**Use for:** Team member timezones, meeting time references, global team coordination. + +### week + +Week date range selector. + +**Use for:** Sprint weeks, weekly planning, week-based scheduling. + +### hour + +Time of day value. + +**Use for:** Meeting times, shift start/end, deadline times. + +### color_picker + +Hex color value. + +**Use for:** Brand colors, category colors, design specifications. + +### formula + +Calculated values based on other columns. + +**Use for:** Derived metrics, cost calculations, score computations. Configured in the board UI after creation. + +**Plan tier:** Pro and Enterprise only. If the user is on Free / Basic / Standard, recommend a `numbers` column updated manually or an external calculation. + +### auto_number + +Auto-incrementing ID. + +**Use for:** Sequential numbering, ticket IDs, order numbers. + +### dependency + +Links between items showing dependencies. + +**Use for:** Task dependencies in project management, prerequisite tracking. + +### mirror + +Reflects data from linked items on other boards. + +**Use for:** Cross-board data visibility without duplication. + +### connect_boards + +Links items across different boards. + +**Use for:** Relating items across boards (e.g., linking a task to a client record). + +## Column Selection Decision Tree + +1. **Is it a workflow state?** -> `status` +2. **Is it a person?** -> `people` +3. **Is it a date?** + - Single date -> `date` + - Date range -> `timeline` +4. **Is it a number?** -> `numbers` +5. **Is it a choice from a list?** + - Workflow state -> `status` + - Category/tag (single board) -> `dropdown` + - Category/tag (cross-board) -> `tags` +6. **Is it yes/no?** -> `checkbox` +7. **Is it a file?** -> `file` +8. **Is it a URL?** -> `link` +9. **Is it contact info?** + - Email -> `email` + - Phone -> `phone` +10. **Is it text?** + - Short (<100 chars) -> `text` + - Long (rich text) -> `long_text` +11. **Is it a calculated value?** -> `formula` (Pro+ only) + +## Recommended Starter Columns + +For most boards, start with these 5 columns and add more as needed: + +1. **Status** (`status`) - Every board needs a workflow state +2. **Owner** (`people`) - Who's responsible +3. **Due Date** (`date`) - When it's due +4. **Priority** (`status`, titled "Priority") - How important +5. **Notes** (`text`) - Additional context diff --git a/skills/monday-docs-collaborator/SKILL.md b/skills/monday-docs-collaborator/SKILL.md index 63d6a21..6a25fc6 100644 --- a/skills/monday-docs-collaborator/SKILL.md +++ b/skills/monday-docs-collaborator/SKILL.md @@ -12,7 +12,7 @@ description: | 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 project-status-report), or building forms (use monday-forms-builder). + 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 diff --git a/skills/monday-project-status-report/SKILL.md b/skills/monday-project-status-report/SKILL.md new file mode 100644 index 0000000..a87a2eb --- /dev/null +++ b/skills/monday-project-status-report/SKILL.md @@ -0,0 +1,198 @@ +--- +name: monday-project-status-report +description: | + Generates structured project status reports from monday.com - a customizable AI work + platform with dedicated products for work management, CRM, dev, service, and campaigns. + Surfaces overdue items, blockers, + workload distribution, and recent activity across one or more boards. + Use when user asks for "project status", "board summary", "what's overdue", + "status report", "how's the project going", "weekly update", "board overview", + "progress update", or "team workload". + Don't use for writing or editing a monday doc (use monday-docs-collaborator). +license: MIT +metadata: + author: monday.com + version: "0.1.3" +--- + +# 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. + +## Use MCP UI widgets for visual sections + +This skill is one of the strongest fits for monday's MCP UI widgets. Use them as follows: + +- **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 + +For short summary lines (totals, counts), use plain text. Do not duplicate widget content as a markdown table afterwards - pick one or the other. + +### show-table filter fallback (required) + +When you call `show-table` with a `filters` array (for example, to scope to overdue items or to exclude Done), always print a short plain-text list of the filtered rows directly below the widget. Some clients surface a filter chip but do NOT auto-apply the filter, so Done items remain visible in the table. The plain-text list is the authoritative view; the widget is the interactive surface. + +Format the fallback as a tight bulleted list of at most 10 rows, each showing item name, owner, due date, and status. If more than 10 rows match, print the first 10 and add a "(+N more)" line. Skip the fallback only when no `filters` array is sent (an unfiltered show-table renders correctly). + +## Precondition + +Before starting, always call `get_board_info` for every board included in the report. This retrieves column IDs, column types, status label mappings, and group structure - all required to correctly interpret item data. + +## Workflow + +### Step 1: Identify the target boards + +If the user specifies a board by name or ID, use it directly. Otherwise: + +1. Call `get_user_context` to retrieve the user's boards, workspaces, and recent activity +2. If ambiguous, ask the user which board(s) to report on +3. For multi-board reports, collect all board IDs + +### Step 2: Fetch board structure + +For each board, call `get_board_info` with the board ID. Extract: + +- **Column definitions** - IDs, types, and allowed values (especially status label mappings) +- **Groups** - group IDs and names (these represent workflow stages like "To Do", "In Progress", "Done") +- **Owners** - board owners and subscribers + +Identify which columns represent: +- **Status** - the primary workflow state (usually a `status` type column) +- **Date/Timeline** - deadlines or date ranges (columns of type `date` or `timeline`) +- **Person** - assignment (columns of type `people`) +- **Priority** - importance level (usually a `status` or `color` type column labeled "Priority") + +### Step 3: Retrieve items + +Call `get_board_items_page` with: +- `boardId`: the target board +- `includeColumns`: `true` +- Use filtering/sorting as needed to focus on active items + +Parse each item's column values using the column definitions from Step 2. + +### Step 4: Identify overdue items + +An item is **overdue** when ALL of these are true: +1. It has a date or timeline column with a value in the past (before today, using the user's timezone context) +2. Its status column is NOT set to a "done" label + +**Determining "done" labels.** Each label in the board's status column has an `is_done` flag. In practice this flag is often unset on user-created or default boards (observed: false on every label including "Done" on real test boards). Treat `is_done: true` as the primary signal when set; otherwise fall back to label-name matching against the conventional set: `Done`, `Completed`, `Closed`, `Resolved`, `Verified`, `Fixed`, `Won`, `Approved`. If neither signal applies, ask the user which label means "complete" on this board. + +Also flag items due within 24 hours as "due soon" to give the user advance warning. + +Collect overdue items with: item name, owner, due date, current status, and group name. + +### Step 5: Identify blockers + +An item is **blocked** when ANY of these are true: +1. Its status is "Stuck", "Blocked", or a similar label (check the board's status labels) +2. It has recent updates/comments flagging a blocker + +For items with "Stuck" status, call `get_updates` on those items to fetch the latest comments explaining why they are stuck. + +**Fallback when no updates exist.** If `get_updates` returns empty for a stuck item, surface context from the item's text columns instead - in priority order: any column titled `Notes`, `Description`, or `Steps to Reproduce`, then any other `text` or `long_text` column with non-empty content. Many teams record blockers in a Notes column rather than as updates. Do not present a blocked item as having "no detail" if a text column has the explanation. + +### Step 6: Get aggregated insights + +Call `board_insights` to get: +- Status distribution (count of items per status label) +- Group distribution (count of items per group) +- Assignment distribution (items per person) + +This provides the high-level numbers without re-processing all items. + +**Use the board-specific status column ID from Step 2.** Pass the actual column ID extracted via `get_board_info` (e.g. `color_mm2xbcrm`, `status_1`, `color_mm30e66p`), never the generic literal `"status"`. The literal `"status"` does not exist on most real boards - it surfaces as a 403 INTERNAL_SERVER_ERROR from `board_insights` even though the underlying cause is "column not found." If a 403 fires here, re-read `get_board_info`, locate the column whose `type` is `status`, and retry with that exact ID. The same rule applies to Priority / Severity / Workflow status columns on dev / CRM / service boards. + +### Step 7: Get recent activity + +Call `get_board_activity` with an explicit time range. The MCP tool's own default is 30 days, but this skill's default is 7 days - so you MUST pass `fromDate` (and optionally `toDate`) to enforce the 7-day window unless the user asks for a different period. This surfaces: +- Items created, updated, or moved +- Status changes +- Assignment changes + +### Step 8: Format the report + +Present the report in this structure: + +--- + +**Project Status: [Board Name]** +*Report generated: [today's date] | Period: [time range]* +*Board URL: [board URL]* + +**Summary** +- Total items: [count] +- Completed: [count] ([percentage]%) +- In progress: [count] +- Overdue: [count] +- Blocked: [count] + +**Status Distribution** -> render via `show-chart` + +**Project Completion** -> render via `show-battery` (e.g., 60%) + +**Overdue Items** -> render via `show-table` with columns: Item, Owner, Due Date, Status, Group + +**Blockers** + +- **[Item name]** (Owner: @name) - [latest comment or reason] +- **[Item name]** (Owner: @name) - [latest comment or reason] + +**Recent Activity (Last 7 Days)** +- [count] items completed +- [count] items created +- [count] status changes +- Notable: [highlight any significant moves or updates] + +--- + +End with 2-3 logical next steps: +- "Want me to follow up with the owners of overdue items?" +- "Should I draft a status update to share with stakeholders?" +- "Want me to dig into why [specific item] is blocked?" + +## Multi-Board Reports + +When the user asks for a report across multiple boards or a workspace: + +1. Call `get_user_context` to list all boards in scope +2. Run Steps 2-7 for each board +3. Present a combined summary at the top, followed by per-board sections +4. Highlight cross-board patterns (e.g., "3 of 5 boards have overdue items") + +**Plan-tier note:** Multi-board aggregation works best on Standard and above. On Free / Basic, monday's cross-board surfaces are more limited - the report still works but may feel single-board. AI Portfolio Risk insights (the "automatic risk identification" feature in `board_insights`) are Enterprise-only. If the user is on a lower tier and asks for AI risk analysis specifically, explain what is available on their plan and offer the manual blocker analysis instead. + +## Output Customization + +Adjust the report based on user requests: +- **"Just the blockers"** - Skip to Step 5, show only blockers section +- **"Overdue items only"** - Skip to Step 4, show only overdue table (use `show-table`) +- **"Last 30 days"** - Adjust the time range in Step 7 +- **"For my team"** - Filter items by person assignment in Step 3 + +## Error Prevention and Remediation + +- If `get_board_info` fails (e.g., board not found, no permission), report which board failed and suggest an alternative: "I cannot access the Q3 Marketing board. Want me to use a board you have access to, or should I ask the owner to share it?" +- If `board_insights` returns empty, fall back to manual aggregation from `get_board_items_page` rather than reporting empty distributions. Items with no status set surface as an empty-string label in `board_insights`; render these as "No status" in the chart, not as a blank segment. +- If the board has no status column, note this and report based on group distribution instead. +- **Empty board.** If `get_board_items_page` returns 0 items, do not run Steps 4-7 or render any widgets. Reply: "<board name> has no items yet." Then suggest creating items (links to the `monday-task-management` skill) or reviewing the board's setup. +- **Multi-board partial failure.** If one board in a multi-board request is inaccessible (private, deleted, or 403), do not abort the whole report. Run the full flow for accessible boards, then add a brief "Could not access: <board name(s)>" note at the top of the combined summary with a suggested next step ("ask the owner to share", "remove from request", "pick a different board"). + +## Tools Used + +- `get_user_context` - identify boards and workspaces +- `get_board_info` - board structure, column definitions, status labels +- `get_board_items_page` - item data with column values +- `board_insights` - aggregated counts and distributions +- `get_board_activity` - recent changes and timeline +- `get_updates` - comments on blocked/flagged items +- `show-chart` - status / workload distribution widget +- `show-battery` - completion percentage widget +- `show-table` - overdue items widget diff --git a/skills/monday-task-management/SKILL.md b/skills/monday-task-management/SKILL.md index 1329c86..5bc44d3 100644 --- a/skills/monday-task-management/SKILL.md +++ b/skills/monday-task-management/SKILL.md @@ -7,7 +7,7 @@ description: | Use when user asks to "create a task", "add an item", "update status", "assign to", "change due date", "move item", "mark as done", "create a subitem", "add a comment", or "update the priority". - Don't use for creating a new board (use board-setup), writing or editing monday docs (use monday-docs-collaborator), or building forms (use monday-forms-builder). + Don't use for creating a new board (use monday-board-setup), writing or editing monday docs (use monday-docs-collaborator), or building forms (use monday-forms-builder). license: MIT metadata: author: monday.com From d749b27f319d3656014ad329b3abc7191490a944 Mon Sep 17 00:00:00 2001 From: Avner Harrari <avnerha@monday.com> Date: Tue, 10 Nov 2026 16:27:03 +0200 Subject: [PATCH 4/5] ci: re-sync and check the plugin on every PR Review follow-ups: - check-skills.js ran only inside the sync and the repo had no CI, so a hand edit to skills/ or plugin.json went in unchecked. The new workflow re-runs the sync (which runs the checker) and fails if skills/ differs from the pinned ref. - HIDDEN_DIRECTIVE was case-sensitive, so <System> got through. Add the i flag. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- .github/workflows/check.yml | 31 +++++++++++++++++++++++++++++++ scripts/check-skills.js | 2 +- 2 files changed, 32 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/check.yml diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml new file mode 100644 index 0000000..88b2743 --- /dev/null +++ b/.github/workflows/check.yml @@ -0,0 +1,31 @@ +name: Check plugin + +# skills/ must be exactly what scripts/sync-skills.sh produces from the ref pinned in skills.json, and +# the plugin must pass scripts/check-skills.js (Google's offline plugin rules). Re-running the sync +# checks both: it runs the checker, and any hand edit to skills/ shows up as a diff. + +on: + pull_request: + push: + branches: [main] + +permissions: + contents: read + +jobs: + check: + name: Skills in sync and plugin rules + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Re-sync skills and check the plugin + run: scripts/sync-skills.sh + + - name: Fail if skills/ differs from the pinned ref + run: | + if [ -n "$(git status --porcelain -- skills)" ]; then + git status --short -- skills + echo "::error::skills/ does not match mondaycom/skills at the ref in skills.json. Change the skill in mondaycom/skills, bump the ref and run scripts/sync-skills.sh." + exit 1 + fi diff --git a/scripts/check-skills.js b/scripts/check-skills.js index e6a5478..7548ed2 100644 --- a/scripts/check-skills.js +++ b/scripts/check-skills.js @@ -17,7 +17,7 @@ const warn = (where, msg) => warnings.push(`${where}: ${msg}`); const GOOGLE_1P = ["bigquery", "gemini", "vertex-ai", "looker", "gdrive"]; const INSTALL = /\b(brew install|npm (i|install)\b|npx |pip3? install|curl [^\n]*\|\s*(ba|z)?sh|wget [^\n]*\|\s*(ba|z)?sh)/i; const INVISIBLE = /[\u200B-\u200F\u202A-\u202E\u2060-\u2064\uFEFF]/; -const HIDDEN_DIRECTIVE = /<\/?(IMPORTANT|SYSTEM)>/; +const HIDDEN_DIRECTIVE = /<\/?(IMPORTANT|SYSTEM)>/i; function readJson(rel) { try { From e7d6fc8d06ba4ccdd78a2029909e6fb8722cc851 Mon Sep 17 00:00:00 2001 From: Avner Harrari <avnerha@monday.com> Date: Tue, 10 Nov 2026 17:08:17 +0200 Subject: [PATCH 5/5] chore: sync skills from mondaycom/skills@b41be7f Picks up mondaycom/skills#8: board-setup excludes first-run onboarding, and project-status-report builds a report-as-doc without widgets, then hands it to docs-collaborator. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- skills.json | 2 +- skills/monday-board-setup/SKILL.md | 4 ++-- skills/monday-project-status-report/SKILL.md | 5 +++-- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/skills.json b/skills.json index a3551a2..57089aa 100644 --- a/skills.json +++ b/skills.json @@ -1,6 +1,6 @@ { "repo": "https://github.com/mondaycom/skills.git", - "ref": "85e3a7ec45ec07d0618f796c1609952e4edc15e7", + "ref": "b41be7f7b84134d0b074968482c70fc9e8e53418", "prefix": "monday-", "skills": [ "onboard-to-monday", diff --git a/skills/monday-board-setup/SKILL.md b/skills/monday-board-setup/SKILL.md index 5629d69..434cb2c 100644 --- a/skills/monday-board-setup/SKILL.md +++ b/skills/monday-board-setup/SKILL.md @@ -7,11 +7,11 @@ description: | and more. Use when user asks to "create a board", "set up a project", "new board for", "build a tracker", "organize my project", "create a board for tracking", or "set up a workflow". - Don't use for adding or editing items on an existing board (use monday-task-management). + Don't use for first-run onboarding of someone new to monday (use monday-onboard-to-monday) or adding or editing items on an existing board (use monday-task-management). license: MIT metadata: author: monday.com - version: "0.2.1" + version: "0.2.2" --- # Board Setup diff --git a/skills/monday-project-status-report/SKILL.md b/skills/monday-project-status-report/SKILL.md index a87a2eb..6c0f16c 100644 --- a/skills/monday-project-status-report/SKILL.md +++ b/skills/monday-project-status-report/SKILL.md @@ -8,11 +8,11 @@ description: | Use when user asks for "project status", "board summary", "what's overdue", "status report", "how's the project going", "weekly update", "board overview", "progress update", or "team workload". - Don't use for writing or editing a monday doc (use monday-docs-collaborator). + Don't use for writing or editing a monday doc (use monday-docs-collaborator); when the user wants the report as a doc, build it here, then write it with monday-docs-collaborator. license: MIT metadata: author: monday.com - version: "0.1.3" + version: "0.1.4" --- # Project Status Report @@ -176,6 +176,7 @@ Adjust the report based on user requests: - **"Overdue items only"** - Skip to Step 4, show only overdue table (use `show-table`) - **"Last 30 days"** - Adjust the time range in Step 7 - **"For my team"** - Filter items by person assignment in Step 3 +- **"As a doc"** - Widgets cannot go into a doc, so build every section as plain text and markdown tables (no `show-chart`, `show-battery` or `show-table`), then hand the result to the `monday-docs-collaborator` skill to write ## Error Prevention and Remediation