diff --git a/skills/odoo/SKILL.md b/skills/odoo/SKILL.md index 492fb72..3497f39 100644 --- a/skills/odoo/SKILL.md +++ b/skills/odoo/SKILL.md @@ -5,16 +5,19 @@ description: > involving: products, product catalog, stock levels, inventory; knowledge base articles; contacts, customers, vendors; sales orders, quotes; CRM leads and opportunities; projects and tasks; helpdesk tickets; purchase orders; - employees and departments. Triggers on: "in Odoo", "our products", "the + employees and departments; bulk record updates; archiving records; counting + records; cancelling quotations. Triggers on: "in Odoo", "our products", "the knowledge base", "find a contact", "sales order", "opportunity", "project tasks", "helpdesk ticket", "purchase order", "stock", "inventory", "employee", "what stage is", "create a task", "update the ticket", - "set icon", "article icon", "emoji icon". + "cancel quotation", "cancel quote", "archive", "mark lost", "bulk update", + "how many records", "count of", "stage id for", "resolve stage", + "search with filters", "filter by", "lost reasons". --- # Odoo MPM Skill -You have direct access to MPM's Odoo V19 instance at mpmedia.odoo.com via the `odoo-mpm` MCP server. +You have direct access to MPM's Odoo instance at mpmedia.odoo.com via the `odoo-mpm` MCP server. ## First-Time Setup (required once per Mac) @@ -58,20 +61,21 @@ One-time setup to store your personal API key in the macOS Keychain. Use `clear_ Search the product catalog, retrieve product details including pricing and descriptions, and check stock levels across warehouse locations. ### Knowledge (`search_knowledge_articles`, `get_knowledge_article`, `create_knowledge_article`, `update_knowledge_article`) -Read, search, create, and update internal Knowledge base articles. Body content is HTML. +Read, search, create, and update internal Knowledge base articles. Body content is HTML. All three tools support an `icon` field — pass a Unicode emoji (e.g. `⚙️`, `🔌`, `🖥️`) to set the article's icon in the KB tree. Browse icons at https://emojipedia.org. -**Icon support:** Both `create_knowledge_article` and `update_knowledge_article` accept an optional `icon` parameter — a single Unicode emoji string (e.g. `"⚙️"`, `"🔌"`, `"🖥️"`) that sets the article's icon in the KB tree view. `get_knowledge_article` returns the current icon. Omitting or passing an empty string leaves the existing icon unchanged. - -To browse and select emojis, use: **[Emojipedia](https://emojipedia.org)** — search by keyword, copy the emoji character, and pass it directly to the tool. +### Knowledge Templates (`search_knowledge_templates`, `get_knowledge_template`, `list_knowledge_template_categories`) +Browse built-in Odoo Knowledge article templates by name or category. Use `get_knowledge_template` to retrieve the full template body for use as a starting point when creating articles. ### Contacts (`search_contacts`, `get_contact`, `create_contact`) Search customers, vendors, and individuals. Use `is_company=true` to filter to companies. -### Sales (`search_sales_orders`, `get_sales_order`, `create_sales_order`) +### Sales (`search_sales_orders`, `get_sales_order`, `create_sales_order`, `cancel_sale_orders`, `cancel_and_archive_quotations`) Look up quotes and sales orders by name (e.g. S00901) or customer. `get_sales_order` includes line items. -### CRM (`search_crm_leads`, `get_crm_lead`, `create_crm_lead`, `update_crm_lead`, `list_crm_stages`) -Manage opportunities in the sales pipeline. Use `list_crm_stages` to get valid stage IDs before updating. +**Important:** `cancel_sale_orders` and `cancel_and_archive_quotations` ONLY operate on orders in **Quotation (draft)** or **Quotation Sent (sent)** state. Both tools will refuse and raise an error if any provided IDs are in any other state (confirmed Sale Order, Locked, Cancelled, etc.). This is an intentional safety constraint — confirmed orders cannot be cancelled via Claude. + +### CRM (`search_crm_leads`, `get_crm_lead`, `create_crm_lead`, `update_crm_lead`, `list_crm_stages`, `mark_crm_lead_lost`, `list_crm_lost_reasons`) +Manage opportunities in the sales pipeline. Use `list_crm_stages` to get valid stage IDs before updating. Use `list_crm_lost_reasons` then `mark_crm_lead_lost` to record a loss with a reason. ### Project (`list_projects`, `get_project`, `search_tasks`, `get_task`, `create_task`, `update_task`, `list_task_stages`) Browse projects, search and update tasks. Use `list_task_stages` with a project_id to get valid stage IDs. @@ -88,16 +92,26 @@ Check current stock levels and recent stock movements by product. ### Employees (`search_employees`, `get_employee`, `list_departments`) Look up employee information and department structure. -### Utilities (`odoo_search`, `odoo_get_record`) -Generic tools for any Odoo model — useful for looking up stage IDs, categories, or any other reference data. +### Utilities — Generic (`odoo_search`, `odoo_get_record`, `odoo_search_read`, `get_record_count`, `bulk_update_records`, `archive_records`, `get_stage_ids`, `call_odoo_method`) +Advanced tools for any Odoo model: +- `odoo_search_read` — preferred for efficient queries: search with domain + return only specified fields. Use this instead of `odoo_search` + `odoo_get_record` to avoid token bloat. +- `get_record_count` — count records matching a domain without fetching data. Use before bulk operations. +- `bulk_update_records` — set one or more field values on a list of record IDs in a single API call. Works for stage changes, custom Studio fields (`x_studio_*`), status flags, etc. +- `archive_records` — soft-delete records by setting `active=False`. For `sale.order`, cancel first with `cancel_sale_orders`. +- `get_stage_ids` — resolve stage names to IDs with case-insensitive exact matching. Supports `crm.stage`, `project.task.type`, and `helpdesk.stage`. +- `call_odoo_method` — escape hatch for any model method not covered by other tools (workflow transitions, report actions, custom methods). Use sparingly. +- `odoo_search` / `odoo_get_record` — legacy generic lookup tools; prefer `odoo_search_read` for new usage. --- ## Workflow Guidelines - When looking up items by number (e.g. "S00901", "P00195"), use `search_sales_orders` or `search_purchase_orders` with that as the query. -- Before updating a task or ticket stage, call `list_task_stages` or `odoo_search('helpdesk.stage', 'name', ...)` to confirm valid stage IDs. +- Before updating a task or ticket stage, call `list_task_stages` or `get_stage_ids('helpdesk.stage', ['Stage Name'])` to confirm valid stage IDs. +- Use `get_stage_ids` instead of `odoo_search` for stage lookups — it handles case-insensitive matching correctly. - Knowledge article bodies are stored as HTML — when creating or updating articles, use basic HTML formatting. -- When setting KB article icons, prompt the user for the emoji or suggest one based on context. Reference: https://emojipedia.org - IDs returned from search tools can be passed directly to `get_*` tools for full details. - When the user asks about "our products" without specifying, use `search_products` with no query and limit=20 to show a broad overview. +- Use `odoo_search_read` for any query where you only need specific fields — it is more efficient than `odoo_get_record` and avoids large responses. +- Before calling `cancel_sale_orders` or `cancel_and_archive_quotations`, use `search_sales_orders` to verify the orders are in `draft` or `sent` state. Both tools will refuse if any order is in another state. +- Before calling `mark_crm_lead_lost`, call `list_crm_lost_reasons` to show the user available reasons so they can choose one by name.