Skip to content

SKILL.md

Latest commit

 

History

History
172 lines (126 loc) · 10.4 KB

SKILL.md

File metadata and controls

172 lines (126 loc) · 10.4 KB
Raw
name odoo-dev-superskill
description Expert guide for creating, reviewing, refactoring, and migrating Odoo modules in versions 16.0, 17.0, 18.0, 19.0, and 20.0, strictly following OCA Guidelines and Odoo 20 official house rules. Use it when the user mentions: creating an Odoo module, inheriting models or views, writing security (ACL/ir.rule), migrating between Odoo versions (e.g., 16 to 18, 18 to 20), fixing tree/list view errors, reviewing Odoo code for anti-patterns, or developing e-commerce connectors (Amazon, eBay, WooCommerce, Mirakl, Temu). Also applies if the user pastes code with models.Model, _inherit, fields.Many2one, <tree>, <list>, or a __manifest__.py, without mentioning Odoo explicitly.
license MIT
version 1.2.0
compatibility
claude-code
antigravity
cursor
windsurf
codex-cli
gemini-cli

odoo-dev-superskill — Odoo Development Skill (16.0–20.0)

An expert skill enabling AI agents to generate, review, refactor, and migrate Odoo modules from version 16.0 to 20.x, adhering to OCA Guidelines and Odoo 20 official house rules.

1. Version Detection (Mandatory First Step)

Before writing a single line of code, determine the target Odoo version.

Detection Strategy

  1. Search for __manifest__.py in the module directory. Extract the MAJOR.MINOR prefix from the version key (e.g., 20.0.1.0.0 → 20.0).
  2. If there is no manifest, check requirements.txt looking for odoo>=18, odoo>=20, or similar.
  3. Run scripts/detect_odoo_version.py to automate the above steps.
  4. If there are no clues, explicitly ask the user:

    "Which Odoo version are you developing for? (16.0 / 17.0 / 18.0 / 19.0 / 20.0)"

The detected version determines:

  • The list view tag (<tree> in 16/17, <list> in 18/19/20).
  • Which ORM methods to use and which are deprecated.
  • The frontend testing framework (QUnit vs Hoot).
  • Domain syntax (odoo.fields.Domain vs legacy prefix domains).

Check references/migrations-and-versions.md for the full breakdown of differences.

2. Standard Workflow (6 Steps)

Follow these 6 steps in order for any Odoo development task:

Step Action Tool/Reference
1 Detect target Odoo version scripts/detect_odoo_version.py, section 1
2 Generate module structure templates/manifest/, templates/readme_structure/
3 Write Python model(s) templates/model_skeleton.py.tpl, references/backend-rules.md
4 Write views, security, and data references/frontend-ui-rules.md, references/backend-rules.md
5 Auto-verify with validation scripts scripts/validate_manifest.py, scripts/check_anti_patterns.py
6 Declare module maturity level references/maturity-levels.md

3. Universal Development Rules (All Versions)

These rules govern Odoo module development. They are classified by urgency level:

Mandatory (Must Follow)

  1. Never use cr.commit() outside of crons or migration scripts.
  2. Never use bare except: pass — catch specific exceptions and log with _logger.
  3. Always define ACLs (ir.model.access.csv) for every new model.
  4. Never execute raw SQL without parameterization — use cr.execute(query, params) or SQL() (17+).
  5. Prefix XML IDs with the technical module name: <module_name>.view_<model>_form.
  6. In <record> tags, place id before model (Odoo 20 house standard).

Recommended (Best Practices)

  1. Respect the attribute order in model classes (see references/backend-rules.md).
  2. One model per Python file, except for very small auxiliary models.
  3. Include tests — minimum one TransactionCase per model with basic CRUD operations.
  4. Document with OCA README — use the structure from templates/readme_structure/.
  5. Version correctly — format MAJOR.MINOR.PATCH.BUILD tied to the Odoo version (e.g. 20.0.1.0.0).
  6. Static literals for translations — use self.env._(...) with kwargs or %s, and plain ASCII punctuation.

4. Key Differences by Version

Version List View Tag Conditional UI Key ORM Change Frontend Runtime
16.0 <tree> attrs="{...}" Improvements in read_group OWL 1/2 transition Python 3.10+
17.0 <tree> invisible="..." Secure SQL() wrapper OWL 2 consolidated Python 3.10+
18.0 <list> (breaking) invisible="..." _read_group replaces read_group Hoot replaces QUnit Python 3.10+
19.0 <list> invisible="..." _search_display_name, GROUPING SETS OWL 2 continuity Python 3.11+
20.0 <list> invisible="..." odoo.fields.Domain, self.env._, SQL() OWL 2 (by feature), Hoot Python 3.11–3.13

Golden Rule: Before generating any view, check this table and use <tree> or <list> according to the target version. Never assume a default.

For full details on each version, check references/migrations-and-versions.md.

Synergy with Odoo 20 Native Repo Skills

In Odoo 20, official agent skills are distributed directly in the core repository (skills/odoo-guidelines, skills/odoo-review, skills/odoo-security, skills/odoo-web-guidelines) following the agentskills.io standard. odoo-dev-superskill fully incorporates these house rules while expanding them with:

  • OCA Multi-version standards across versions 16.0 through 20.0.
  • Automated Scaffolding & Migration tooling (auto_migrate_full.py, scaffold_module.py).
  • AST quality inspection & autofixers (check_anti_patterns.py, autofix_xml.py).
  • E-commerce & marketplace connector architectures (Amazon, eBay, Mirakl, Temu).

Target Version Examples (Few-Shot Reasoning)

  • Example 1 (New Module v20.0):
    • Request: "Create a new Odoo 20.0 module with a list view."
    • Action: Generate the list view using the <list> tag instead of <tree>, place id before model in <record>, and use 20.0.1.0.0 manifest.
  • Example 2 (XML View Migration to v18.0+):
    • Request: "Migrate this view with attrs="{'invisible': [('state', '=', 'draft')]}" and <tree> to Odoo 20."
    • Action: Refactor <tree> to <list>, and conditional visibility to invisible="state == 'draft'".
  • Example 3 (Ambiguous version context):
    • Request: "Generate model logic for this addon." (No manifest exists, no version specified).
    • Action: Run detect_odoo_version.py first. If the version is still undetermined, ask: "Which Odoo version are you developing for? (16.0 / 17.0 / 18.0 / 19.0 / 20.0)".

5. Behavior templates

If the task is creating a new addon or scaffolding a module from scratch, read references/agents/scaffold-behavior.md.

If the task involves migration between Odoo versions or adaptation of deprecated syntax, read references/agents/migration-behavior.md.

If the task affects access rights, record rules, sudo usage, SQL queries, controllers, or security-sensitive logic, read references/agents/security-behavior.md.

If the task involves XML views, XPath inheritance, QWeb, OWL components, assets, or frontend behavior, read references/agents/xml-ui-behavior.md.

If the task involves APIs, marketplaces, webhooks, import/export flows, or external integrations, read references/agents/connector-behavior.md.

If the task is reviewing an existing module for quality, structure, maintainability, or OCA alignment, read references/agents/review-behavior.md.

If the task is about tests, coverage, validation flows, or QA strategy, read references/agents/testing-behavior.md.

These files are complementary to the global skill behavior. They do not replace the version matrix or general references, and they can be combined if a task touches multiple areas (e.g., a migration with XML view changes).

6. References Index

Refer to these consolidated guides for technical specifications. Avoid scanning multiple files; use these curated references directly:

Reference Description
backend-rules.md Attribute ordering, Python exceptions, raw SQL safety, caching, ACLs, record rules, and controller security
frontend-ui-rules.md tree vs list views, xpath selection, indentation, XML IDs, OWL 2 development, and POS architecture
migrations-and-versions.md Version compatibility matrix, API changelog (v16-19), and OCA migration/OpenUpgrade guidelines
testing.md Backend TransactionCase and frontend OWL 2 Hoot test patterns
ecommerce-connectors.md Integration patterns for Amazon, eBay, WooCommerce, Mirakl, and Temu
maturity-levels.md Addon readiness checklists (Alpha, Beta, Stable, Mature)
error-recipes.json Machine-readable linter remediation recipes
cheatsheet-agent.md Compact, token-efficient agent quick-reference

Note: For lists of all available boilerplates and CLI scripts, read skill-manifest.json at the repository root.

7. Advanced Agent Tooling (Optional: Codegraph & Engram)

If codegraph or engram servers are active in your MCP environment, leverage them to improve speed, precision, and context persistence:

Codegraph (Code Intelligence)

  • Code Navigation & Search: Avoid raw grep or manual file reading. Use codegraph_explore to inspect how Odoo models are inherited or extended (e.g., searching for _inherit = "res.partner").
  • Call Graph Analysis: Before refactoring or renaming ORM methods, call codegraph_callers or codegraph_impact to assess what references will break.
  • Overloaded Definition Search: For common Odoo methods like write or create, use codegraph_node (with includeCode) to view all definitions in a single call instead of browsing multiple files.

Engram (Persistent Memory)

  • Session Persistence: Proactively record architectural choices, resolved Odoo framework bugs, or custom guidelines for this repository using mem_save.
  • Search History: Use mem_search at the start of a session or when encountering an obscure ORM error to see if it was resolved previously.
  • Session Summaries: Call mem_session_summary before ending your turn to keep a record of completed and pending tasks.