unclecatvn-agent-skills

https://github.com/user-attachments/assets/a6f73c3a-7253-4621-b72e-511e2e57cb3a

Agent Skills

Version-aware expertise for Odoo development.

Reference packs, a trace-first development workflow, and specialized reviewers that make AI coding assistants work from your real Odoo source instead of from memory. Odoo 16–19.

English · Tiếng Việt

Why · With vs without · Quick start · First run · How it works · Prompts · Toolkit · Versions · Contributing

Why it exists

AI assistants write plausible Odoo code. The failures that cost time are always the same kind:

• a field, method or xmlid that does not exist in the base addon (sale.order.delivery_date, sales_team.group_sale_admin);
• an xpath anchor that only another module's view adds, so the module fails to install;
• an override hooked on the public method instead of the hook that does the work;
• a stored field renamed without a migration, which silently drops the column and its data;
• a sudo() nobody can audit;
• "tests pass" when the test run ran zero tests.

This repository gives the assistant three things against that:

Part	What it does
Odoo reference packs (16.0, 17.0, 18.0, 19.0)	Version-specific guides for models, fields, views, OWL, security, controllers, reports, tests, migrations, translations and performance, plus an api-highlights.md list of what not to use in that version.
Odoo Workflow skill	A procedure the assistant follows for every Odoo change: find the runtime, trace the real source with a bundled helper, write a Context Brief where every claim has a file:line, implement the smallest change, then prove it on a throwaway database.
Agents	A code tracer and a scored code reviewer that share the same version and runtime rules.

These are instructions and a read-only helper script, not an Odoo module or an enforcement system. Results depend on the assistant, the model, and the checks you let it run.

With and without the skill: one real task

A user in an Odoo 18 project asks the following. As in most real setups, the Odoo source and odoo.conf live outside the project directory, and nothing in the prompt says where:

In module x_eval, add a stored computed integer field x_age_days on sale.order.line: days since the line's create_date.

We ran this task with the same model (Claude Opus 5.5), once with no skill and once with the odoo-workflow skill, and had a separate grader check both answers against the Odoo 18 source without knowing which was which. Both noticed that a stored compute on create_date never refreshes and added a daily cron. The difference is in what each one knew and what it would have shipped:

	Without the skill	With odoo-workflow
Odoo version	Guessed: "I assumed Odoo 18 (or 19)"	Found 18.0 in the core's odoo/release.py, through the odoo.conf in a sibling directory
Source read	3 tool calls, no file:line anywhere	26 tool calls, a Context Brief of 13 cited rows
Why create_date exists on the line	Not explained	Cited: automatic log field from odoo/models.py:288
Upgrading a database that already has order lines	Noted that -u recomputes every line in Python	Bumps the version to 1.1 and adds migrations/1.1/pre-migrate.py that fills the column in SQL, so -u does not recompute millions of rows
Tests	-u x_eval --test-tags /x_eval on an unnamed database, which runs 0 tests and still exits 0 if x_eval is not installed there	Installs on a throwaway scratch_x_eval database and requires the log line 0 failed, 0 error(s) of N tests with N > 0
Grader verdict	2 of 3 expectations	3 of 3, preferred

An excerpt of the Context Brief the skill produced:

Layer	Symbol	Source (file:line)	Change
field	create_date	odoo/models.py:288 (automatic field), set once at models.py:5137	@api.depends('create_date')
field	x_age_days	NOT FOUND on all three roots (helper exit 1): the name is free	new field
method	daily recompute	addons/membership/models/partner.py:87-91, membership/data/membership_data.xml:4-10	same core pattern
migration	new stored compute on a populated table	odoo/models.py:3474-3487 (new column → recompute every row), odoo/fields.py:1117 (existing column skips it)	version 1.1 + pre-migration

The numbers

The same comparison over the repository's anti-hallucination evals (details and every per-eval row in benchmark.md):

	Without skill	With odoo-workflow
Realistic setup, 8 evals: expectations passed	21/23	23/23
Realistic setup: evals fully passed	6/8	8/8
Environment given, 24 evals: expectations passed	70/71	71/71
Invented Odoo behaviour (32 runs)	4	2
Code or commands that would ship broken	0	0
Grader prefers (32 pairs)	6	16 (10 ties)
Cost: output tokens / tool calls	1×	~2× / ~1.7×

What this says honestly:

• A strong model that can read the source is already careful: neither side shipped broken code on these evals. The skill's gain is grounding and completeness: cited sources, the migration a stored field needs, and tests that provably ran.
• It costs about twice the tokens. For a label change that is wasted, which is why the skill has a fast path for trivial edits.
• The bundled trace helper answered 34/34 trace questions correctly on real Odoo 18 and 19 source, where the grep recipe of the previous release answered 12/34 under zsh (every lookup came back empty) and 20/34 under bash. See benchmark.md.

Quick start

Pick one installation route.

Claude Code plugin (recommended for Claude Code): skills and agents together

claude plugin marketplace add unclecatvn/agent-skills
claude plugin install agent-skills@unclecat-agent-skills

Add --scope project to record the installation in the current project instead of your user settings. Everything appears namespaced by the plugin: skills such as agent-skills:odoo-workflow and agent-skills:odoo-18-0, agents such as agent-skills:odoo-code-tracer and agent-skills:odoo-code-review.

To update later, refresh the marketplace, then install the plugin again:

claude plugin marketplace update unclecat-agent-skills
claude plugin install agent-skills@unclecat-agent-skills

See the marketplace manifest and the plugin reference.

Skills installer: any supported assistant

npx skills add unclecatvn/agent-skills

Choose the skills and your assistant in the installer. Install odoo-workflow plus the pack for your Odoo version (odoo-18, ...). This route installs skills only, not the standalone agents or rules. Targets and options are maintained by the upstream skills CLI.

Bundled CLI: copy one pack to a known location

# List installable packs
npx @unclecat/agent-skills-cli versions skills

# Odoo 18 pack for Cursor
npx @unclecat/agent-skills-cli init --ai cursor --skill skills --version odoo-18.0

# Workflow pack for Claude Code
npx @unclecat/agent-skills-cli init --ai claude --skill skills --version odoo-workflow

--skill skills names the repository directory and --version selects a pack inside it. Pass both: the CLI's legacy defaults do not match this layout. See installation notes.

Requirements: Node.js 18+ for the CLI routes; Python 3.8+ for the workflow's helper (standard library only; the Python in your Odoo virtualenv works); a local checkout of the Odoo source your project runs (community, plus enterprise if you use it).

First run in an Odoo project

1. Open the assistant in your project (the directory with your custom addons, or its parent).

2. Let the workflow find the runtime. On the first Odoo task it runs python3 <skill_dir>/scripts/odoo_trace.py env, which reads, in order: .claude/odoo.json, an odoo-bin configuration in .claude/launch.json, then the one *.conf whose addons_path covers your project (searched in parent directories, so ../18.0/odoo.conf is found). It prints the Odoo version, core path, conf, Python, dev database and the addons roots in the order Odoo loads them:

   version   18.0  [/path/odoo/18.0/odoo/release.py]
   odoo_root /path/odoo/18.0  [/path/project/.claude/launch.json config "odoo-dev"]
   conf      /path/odoo/18.0/odoo.conf  [same]
   python    /path/odoo/18.0/.venv/bin/python3  [same]
   dev_db    v18_dev  [same]
   addons    conf addons_path
     r1 /path/odoo/18.0/odoo/addons  [odoo/addons (always first)]
     r2 /path/odoo/18.0/addons  [addons_path]
     r3 /path/project/erp  [addons_path]
   VERDICT: Odoo 18.0, 3 roots, 652 modules, base at /path/odoo/18.0/odoo/addons/base
   

3. If it cannot find the runtime, it asks once and offers to write a gitignored .claude/odoo.json (paths are machine-local, so do not commit it):

   {"odoo_version": "18.0", "odoo_root": "/path/odoo/18.0", "conf": "/path/odoo/18.0/odoo.conf",
    "python": "/path/odoo/18.0/.venv/bin/python3", "dev_db": "v18_dev"}
   

4. Optionally add project rules. Merge the relevant parts of the project template into your CLAUDE.md or AGENTS.md (do not overwrite it): Odoo version, addons layout, "throwaway databases only", migrations for stored-field changes, _sudo naming, commit style. The template forbids Co-Authored-By and Generated with lines; to stop Claude Code from adding them, set "attribution": {"commit": "", "pr": ""} in the project or user settings.json.

You can run the helper yourself from a clone of this repository to see what the assistant sees:

cd /path/to/your/project
python3 /path/to/agent-skills/skills/odoo-workflow/scripts/odoo_trace.py env
python3 /path/to/agent-skills/skills/odoo-workflow/scripts/odoo_trace.py field sale.order access_url

How the Odoo workflow works

flowchart LR
  R[Request or traceback] --> S0[0 Runtime, version, pack]
  S0 --> S1[1 Trace the real source]
  S1 --> S2[2 Context Brief with file:line]
  S2 --> S3[3 Minimal plan]
  S3 --> S4[4 Implement]
  S4 --> S5[5 Definition of done]
  S5 --> S6[6 Review agent]

Step	What happens
0. Runtime, version, pack	The helper resolves core, conf and roots; the version comes from the core's release.py (a .claude/odoo.json or legacy .odoo-version pin must agree, or it stops and asks). The assistant loads the matching pack and its api-highlights.md.
1. Trace	Python symbols through the helper (below); views, OWL templates, JS patches, routes, ACLs and rename impact through zsh- and bash-safe greps over the same roots.