Imported from oduit/oduit (skills/oduit/SKILL.md). Install upstream with npx skills add oduit/oduit --skill oduit. Copyright stays with the author.

oduit

When to use this skill

Use this skill in Odoo repositories when a task needs addon, manifest, dependency, runtime, or database context and oduit is available or can be run with uvx oduit.

Good fits:

• inspect an addon, manifest, dependency tree, install order, or duplicate addon names
• locate model or field source files before editing an addon
• inspect live model, field, XMLID, view, table, constraint, or Many2many metadata
• plan or verify an addon change with structured JSON output
• run Odoo module tests through a normalized agent payload
• replace ad-hoc odoo-bin shell, direct psql, or custom runtime snippets with first-class inspection commands

Do not use oduit for unrelated Python tests, static linting, or plain file search. Use normal repo tooling for those.

For any task that asks to create, update, review, refresh, or diff addon architecture documentation, switch to the oduit-technical-documentation skill.

First checks

1. Prefer the repository's existing oduit command.

   oduit --help

2. If oduit is not installed, use:

   uvx oduit --help

3. Start with diagnostics:

   oduit doctor
   oduit agent context
   oduit agent resolve-config

If context, resolve-config, doctor, or list-duplicates reports blockers, handle those before runtime mutation.

Preferred agent surface

For coding agents, prefer oduit agent ... over human-oriented commands and over the Python API. Agent commands emit one JSON object with a stable envelope.

Stable top-level fields include:

• schema_version
• type
• success
• read_only
• safety_level
• warnings
• errors
• remediation
• data
• meta

Read command-specific information from payload["data"]. Do not depend on raw human text output. Pass oduit agent --show-command ... only when you need data.command for debugging.

Read-only discovery commands

Use read-only commands first.

Environment and addon inventory:

oduit agent context
oduit agent doctor
oduit agent resolve-config
oduit agent list-addons
oduit agent list-installed-addons
oduit agent list-duplicates
oduit agent inspect-addon my_addon
oduit agent addon-info my_addon
oduit agent addon-doc my_addon
oduit agent get-addon-files my_addon

Dependency and update planning:

oduit agent dependency-graph --modules sale,purchase
oduit agent explain-install-order --modules sale
oduit agent plan-update my_addon
oduit agent preflight-addon-change my_addon --model res.partner --field email3
oduit agent prepare-addon-change my_addon --model res.partner --field email3 --types form,tree

Source location and test discovery:

oduit agent locate-model res.partner --module my_addon
oduit agent locate-field res.partner email3 --module my_addon
oduit agent list-addon-tests my_addon --model res.partner --field email3
oduit agent recommend-tests --module my_addon --paths models/res_partner.py,views/res_partner_views.xml
oduit agent list-addon-models my_addon
oduit agent find-model-extensions res.partner --summary
oduit agent get-model-views res.partner --types form,tree --summary

Runtime and database inspection:

oduit agent inspect-ref base.action_partner_form
oduit agent inspect-cron base.ir_cron_autovacuum
oduit agent inspect-modules --state installed --names-only
oduit agent inspect-model res.partner
oduit agent inspect-field res.partner email --with-db
oduit agent db-table res_partner
oduit agent db-column res_partner email
oduit agent db-constraints sale_order
oduit agent db-m2m res.partner category_id
oduit agent performance-table-scans
oduit agent performance-slow-queries --limit 10
oduit agent manifest-check sale
oduit agent manifest-show sale

Safe runtime reads:

oduit agent query-model res.partner --fields name,email --limit 5
oduit agent read-record res.partner 1 --fields name,email
oduit agent search-count res.partner
oduit agent get-model-fields res.partner --attributes string,type,required

Prefer these wrappers over exec, exec-file, inspect recordset, odoo-bin shell, or direct SQL.

Typical addon-change loop

For a change such as adding email3 to res.partner in my_addon:

1. Resolve environment and addon context.

   oduit agent context
   oduit agent inspect-addon my_addon
   oduit agent addon-doc my_addon

2. Inspect runtime model metadata and source locations.

   oduit agent get-model-fields res.partner --attributes string,type,required
   oduit agent get-model-views res.partner --types form,tree --summary
   oduit agent locate-model res.partner --module my_addon
   oduit agent locate-field res.partner email3 --module my_addon
   oduit agent list-addon-tests my_addon --model res.partner --field email3

3. Plan before editing when the change affects install/update behavior.

   oduit agent plan-update my_addon
   oduit agent prepare-addon-change my_addon --model res.partner --field email3 --types form,tree

4. Edit the addon source with normal repo tools.

5. Ask oduit for focused verification hints.

   oduit agent recommend-tests --module my_addon --paths models/res_partner.py,views/res_partner_views.xml

6. Verify with the narrowest useful runtime command.

   oduit agent test-summary --module my_addon --test-tags /my_addon

7. If the database must be updated or the module may need installation, make mutation explicit.

   oduit agent validate-addon-change my_addon --allow-mutation --update --discover-tests
   oduit agent validate-addon-change my_addon --allow-mutation --install-if-needed --update --discover-tests

Mutation policy

Default to read-only commands.

Runtime database mutation commands:

• install-module
• update-module
• uninstall-module
• test-summary when called with --install or --update
• validate-addon-change when called with install/update options
• extension-db and create-db when creating or enabling database extensions
• inspect-cron --trigger
• extension-db targets the configured db_name; create-db --extension installs requested extensions after initialization. Both are explicit runtime DB mutations. Use --with-sudo only when intentionally running as the local PostgreSQL administrator. The PostgreSQL server extension package must already be installed, and oduit never installs it or implicitly elevates module installation. For Odoo AI/pgvector, explicitly enable vector before installing ai_azure_openai.

Source mutation commands:

• create-addon
• i18n-export
• export-lang (compatibility alias)

Runtime translation mutation commands:

• i18n-import
• i18n-loadlang

Rules:

• Pass --allow-mutation when using mutation commands.
• Use --dry-run first when available.
• uninstall-module additionally requires --allow-uninstall and allow_uninstall = true in config.
• write_protect_db = true blocks runtime DB mutation for every caller.
• agent_write_protect_db = true blocks agent runtime DB mutation.
• needs_mutation_flag = true requires --allow-mutation for human runtime DB mutation.
• agent_needs_mutation_flag = true requires --allow-mutation for agent runtime DB mutation.
• Plain test-summary without --install or --update is read-only.
• A test-summary result is valid proof only when success=true, tests_run=true, and total_tests > 0.
• module_uninstalled is a blocker, not a passing test. Do not silently install it.
• Use validate-addon-change --allow-mutation --install-if-needed ... when installation is intentionally required.
• Inspect aggregate_test_line and diagnostic_excerpts when tests fail.
• Zero-test results are non-success and distinguish module_uninstalled, no_tests_matched, tests_skipped, and no_tests_executed.
• Explicit --install or --update is performed and verified before the test process starts.

Never widen destructive behavior silently. If a task needs installation, update, uninstall, cron triggering, source generation, or translation export, call that out and use the explicit flags.

Translation notes:

• prefer oduit i18n export and oduit agent i18n-export over export-lang
• i18n export --output - is read-only; filesystem outputs are source mutations
• i18n import and i18n loadlang are runtime DB mutations
• locale values are not limited to xx_XX; examples include en, es_AR, and sr@latin
• use --dry-run first on the agent i18n commands when you need the normalized request, effective series, and chosen strategy without executing Odoo

Human CLI fallback

Use human-oriented commands when a person-readable result is enough or when no agent wrapper exists:

oduit agent i18n-export sale --language de_DE --output - --dry-run oduit agent i18n-export sale --language de_DE --output /tmp/sale-de.po --allow-mutation oduit agent i18n-import /tmp/sale-de.po --language de_DE --allow-mutation oduit agent i18n-loadlang en es_AR sr@latin --allow-mutation

oduit doctor
oduit version
oduit list-addons
oduit list-installed-addons
oduit print-manifest sale
oduit list-depends sale
oduit install-order sale,purchase
oduit impact-of-update sale
# Durable addon-local Arc42 docs: prefer the oduit-technical-documentation skill.
oduit docs technical-evidence @addons/sale --output-in-addon --source-only
oduit docs technical-report @addons/sale --output-in-addon --source-only
oduit docs technical-diff @addons/sale --include-diff

# Legacy/additional addon summary, not the Arc42 architecture workflow.
oduit docs addon sale --source-only
oduit inspect model res.partner
oduit inspect field res.partner email --with-db
oduit db table res_partner
oduit manifest check sale

Use --json with human-oriented commands only when the command supports a machine-readable shape you have verified. For automation, prefer the agent commands.

Trusted arbitrary execution

oduit exec, oduit exec-file, inspect recordset, OdooCodeExecutor, and execute_python_code() are trusted arbitrary execution surfaces. Use them only when first-class agent, inspect, db, performance, manifest, or query-model commands cannot answer the question.

When using arbitrary execution:

• keep snippets read-only unless mutation is explicitly requested
• rely on rollback-by-default behavior
• pass --commit only when mutation is intended and approved
• in Python API use, pass allow_unsafe=True explicitly where required

Operation sets

Use operation sets when a repository has repeated install/update/test plans under .oduit/sets/ or ~/.config/oduit/sets/.

Current CLI surface:

oduit set inspect base
oduit set apply base --allow-mutation --retry-missing 1
oduit set apply base --allow-mutation --one-by-one
oduit set list
oduit install-order --from-set base --save-set base_ordered
oduit list-installed-addons --save-set snapshot --set-kind install

For large or fragile install/update sets, prefer --retry-missing 1 or --one-by-one. These modes use --verify-state by default, which queries the runtime module state instead of trusting only Odoo process logs.

Operation sets are execution plans, not environment configs. Keep .oduit.toml for binaries, database, addons path, mutation policy, and runtime parameters.

Before applying a set, inspect it and confirm the target environment:

oduit doctor
oduit set inspect base
oduit agent resolve-config

If the environment requires explicit mutation confirmation, pass --allow-mutation only after reviewing the set. Install and update sets mutate the runtime database. Test sets only require mutation confirmation when they have [test].install or [test].update.

Python API

Prefer the CLI agent surface for external coding-agent workflows. Use the Python API only when writing Python integration code inside a project.

Common imports:

from oduit import ConfigLoader, ModuleManager, OdooInspector, OdooOperations, OdooQuery

Examples:

loader = ConfigLoader()
config = loader.load_config("dev")

ops = OdooOperations(config, verbose=True)
context = ops.get_environment_context()
addon = ops.inspect_addon("sale")

manager = ModuleManager(config["addons_path"])
addons = manager.find_modules()
install_order = manager.get_install_order("sale", "purchase")

inspector = OdooInspector(config)
model = inspector.inspect_model("res.partner")
table = inspector.describe_table("res_partner")

query = OdooQuery(config)
partners = query.query_model("res.partner", fields=["name", "email"], limit=5)

Do not use execute_python_code() or OdooCodeExecutor for routine agent automation.

Verification guidance

Use the narrowest verification that proves the change:

• manifest or dependency change: manifest-check, dependency-graph, explain-install-order, or plan-update
• source-only addon change: recommend-tests then targeted repo tests
• runtime model or field change: get-model-fields, inspect-model, inspect-field, and focused test-summary
• install/update behavior: validate-addon-change --allow-mutation --update or --install-if-needed --update
• database metadata question: db-table, db-column, db-constraints, or db-m2m

Report the exact command, success flag, key warnings/errors, and any unresolved blocker from the JSON payload.