{
"markdown": "\n\n\n\n# Agent Skills\n\n**Version-aware expertise for Odoo development.**\n\nReference packs, a trace-first development workflow, and specialized reviewers that make AI coding\nassistants work from your real Odoo source instead of from memory. Odoo 16–19.\n\n[](https://www.npmjs.com/package/@unclecat/agent-skills-cli)\n[](LICENSE)\n[](https://github.com/unclecatvn/agent-skills/actions/workflows/ci.yml)\n\n**English** · [Tiếng Việt](README.vi.md)\n\n[Why](#why-it-exists) · [With vs without](#with-and-without-the-skill-one-real-task) · [Quick start](#quick-start) · [First run](#first-run-in-an-odoo-project) · [How it works](#how-the-odoo-workflow-works) · [Prompts](#everyday-prompts) · [Toolkit](#whats-in-the-toolkit) · [Versions](#odoo-versions-and-runtime) · [Contributing](#contributing)\n\n
\n\n## Why it exists\n\nAI assistants write plausible Odoo code. The failures that cost time are always the same kind:\n\n- a field, method or xmlid that does not exist in the base addon (`sale.order.delivery_date`,\n `sales_team.group_sale_admin`);\n- an xpath anchor that only another module's view adds, so the module fails to install;\n- an override hooked on the public method instead of the hook that does the work;\n- a stored field renamed without a migration, which silently drops the column and its data;\n- a `sudo()` nobody can audit;\n- \"tests pass\" when the test run ran zero tests.\n\nThis repository gives the assistant three things against that:\n\n| Part | What it does |\n| --- | --- |\n| **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. |\n| **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. |\n| **Agents** | A code tracer and a scored code reviewer that share the same version and runtime rules. |\n\nThese are instructions and a read-only helper script, not an Odoo module or an enforcement system.\nResults depend on the assistant, the model, and the checks you let it run.\n\n## With and without the skill: one real task\n\nA user in an Odoo 18 project asks the following. As in most real setups, the Odoo source and\n`odoo.conf` live outside the project directory, and nothing in the prompt says where:\n\n> In module x_eval, add a stored computed integer field `x_age_days` on `sale.order.line`: days since\n> the line's `create_date`.\n\nWe ran this task with the same model (Claude Opus 5.5), once with no skill and once with the\n`odoo-workflow` skill, and had a separate grader check both answers against the Odoo 18 source\nwithout knowing which was which. Both noticed that a stored compute on `create_date` never\nrefreshes and added a daily cron. The difference is in what each one knew and what it would have\nshipped:\n\n| | Without the skill | With `odoo-workflow` |\n| --- | --- | --- |\n| 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 |\n| Source read | 3 tool calls, no `file:line` anywhere | 26 tool calls, a Context Brief of 13 cited rows |\n| Why `create_date` exists on the line | Not explained | Cited: automatic log field from `odoo/models.py:288` |\n| 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 |\n| 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 |\n| Grader verdict | 2 of 3 expectations | 3 of 3, preferred |\n\nAn excerpt of the Context Brief the skill produced:\n\n| Layer | Symbol | Source (file:line) | Change |\n| --- | --- | --- | --- |\n| field | `create_date` | `odoo/models.py:288` (automatic field), set once at `models.py:5137` | `@api.depends('create_date')` |\n| field | `x_age_days` | NOT FOUND on all three roots (helper exit 1): the name is free | new field |\n| method | daily recompute | `addons/membership/models/partner.py:87-91`, `membership/data/membership_data.xml:4-10` | same core pattern |\n| 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 |\n\n### The numbers\n\nThe same comparison over the repository's anti-hallucination evals (details and every per-eval row in\n[benchmark.md](tests/evals/odoo-workflow/benchmark.md)):\n\n| | Without skill | With `odoo-workflow` |\n| --- | --- | --- |\n| Realistic setup, 8 evals: expectations passed | 21/23 | **23/23** |\n| Realistic setup: evals fully passed | 6/8 | **8/8** |\n| Environment given, 24 evals: expectations passed | 70/71 | **71/71** |\n| Invented Odoo behaviour (32 runs) | 4 | **2** |\n| Code or commands that would ship broken | 0 | 0 |\n| Grader prefers (32 pairs) | 6 | **16** (10 ties) |\n| Cost: output tokens / tool calls | 1× | ~2× / ~1.7× |\n\nWhat this says honestly:\n\n- A strong model that can read the source is already careful: neither side shipped broken code on\n these evals. The skill's gain is **grounding and completeness**: cited sources, the migration a\n stored field needs, and tests that provably ran.\n- It costs about **twice the tokens**. For a label change that is wasted, which is why the skill has\n a fast path for trivial edits.\n- The bundled trace helper answered **34/34** trace questions correctly on real Odoo 18 and 19\n source, where the grep recipe of the previous release answered 12/34 under zsh (every lookup came\n back empty) and 20/34 under bash. See [benchmark.md](tests/evals/odoo-workflow/benchmark.md).\n\n## Quick start\n\nPick **one** installation route.\n\n### Claude Code plugin (recommended for Claude Code): skills and agents together\n\n```bash\nclaude plugin marketplace add unclecatvn/agent-skills\nclaude plugin install agent-skills@unclecat-agent-skills\n```\n\nAdd `--scope project` to record the installation in the current project instead of your user\nsettings. Everything appears namespaced by the plugin: skills such as `agent-skills:odoo-workflow`\nand `agent-skills:odoo-18-0`, agents such as `agent-skills:odoo-code-tracer`,\n`agent-skills:odoo-code-review` and `agent-skills:planner`.\n\nTo update later, refresh the marketplace, then install the plugin again:\n\n```bash\nclaude plugin marketplace update unclecat-agent-skills\nclaude plugin install agent-skills@unclecat-agent-skills\n```\n\nSee the [marketplace manifest](.claude-plugin/marketplace.json) and the\n[plugin reference](https://code.claude.com/docs/en/plugins-reference).\n\n### Skills installer: any supported assistant\n\n```bash\nnpx skills add unclecatvn/agent-skills\n```\n\nChoose the skills and your assistant in the installer. Install `odoo-workflow` plus the pack for your\nOdoo version (`odoo-18`, ...). This route installs skills only, not the standalone agents or rules.\nTargets and options are maintained by the [upstream skills CLI](https://github.com/vercel-labs/skills#readme).\n\n### Bundled CLI: copy one pack to a known location\n\n```bash\n# List installable packs\nnpx @unclecat/agent-skills-cli versions skills\n\n# Odoo 18 pack for Cursor\nnpx @unclecat/agent-skills-cli init --ai cursor --skill skills --version odoo-18.0\n\n# Workflow pack for Claude Code\nnpx @unclecat/agent-skills-cli init --ai claude --skill skills --version odoo-workflow\n```\n\n`--skill skills` names the repository directory and `--version` selects a pack inside it. Pass both:\nthe CLI's legacy defaults do not match this layout. See [installation notes](#installation-notes).\n\n**Requirements:** Node.js 18+ for the CLI routes; Python 3.8+ for the workflow's helper (standard\nlibrary only; the Python in your Odoo virtualenv works); a local checkout of the Odoo source your\nproject runs (community, plus enterprise if you use it).\n\n## First run in an Odoo project\n\n1. **Open the assistant in your project** (the directory with your custom addons, or its parent).\n2. **Let the workflow find the runtime.** On the first Odoo task it runs\n `python3 /scripts/odoo_trace.py env`, which reads, in order:\n `.claude/odoo.json`, an `odoo-bin` configuration in `.claude/launch.json`, then the one `*.conf`\n whose `addons_path` covers your project (searched in parent directories, so `../18.0/odoo.conf`\n is found). It prints the Odoo version, core path, conf, Python, dev database and the addons roots\n in the order Odoo loads them:\n\n ```text\n version 18.0 [/path/odoo/18.0/odoo/release.py]\n odoo_root /path/odoo/18.0 [/path/project/.claude/launch.json config \"odoo-dev\"]\n conf /path/odoo/18.0/odoo.conf [same]\n python /path/odoo/18.0/.venv/bin/python3 [same]\n dev_db v18_dev [same]\n addons conf addons_path\n r1 /path/odoo/18.0/odoo/addons [odoo/addons (always first)]\n r2 /path/odoo/18.0/addons [addons_path]\n r3 /path/project/erp [addons_path]\n VERDICT: Odoo 18.0, 3 roots, 652 modules, base at /path/odoo/18.0/odoo/addons/base\n ```\n\n3. **If it cannot find the runtime**, it asks once and offers to write a gitignored\n `.claude/odoo.json` (paths are machine-local, so do not commit it):\n\n ```json\n {\"odoo_version\": \"18.0\", \"odoo_root\": \"/path/odoo/18.0\", \"conf\": \"/path/odoo/18.0/odoo.conf\",\n \"python\": \"/path/odoo/18.0/.venv/bin/python3\", \"dev_db\": \"v18_dev\"}\n ```\n\n4. **Optionally add project rules.** Merge the relevant parts of the\n [project template](skills/odoo-workflow/templates/CLAUDE.md) into your `CLAUDE.md` or `AGENTS.md`\n (do not overwrite it): Odoo version, addons layout, \"throwaway databases only\", migrations for\n stored-field changes, `_sudo` naming, commit style. The template forbids `Co-Authored-By` and\n `Generated with` lines; to stop Claude Code from adding them, set\n `\"attribution\": {\"commit\": \"\", \"pr\": \"\"}` in the project or user `settings.json`.\n\nYou can run the helper yourself from a clone of this repository to see what the assistant sees:\n\n```bash\ncd /path/to/your/project\npython3 /path/to/agent-skills/skills/odoo-workflow/scripts/odoo_trace.py env\npython3 /path/to/agent-skills/skills/odoo-workflow/scripts/odoo_trace.py field sale.order access_url\n```\n\n## How the Odoo workflow works\n\n```mermaid\nflowchart LR\n R[Request or traceback] --> S0[0 Runtime, version, pack]\n S0 --> S1[1 Trace the real source]\n S1 --> S2[2 Context Brief with file:line]\n S2 --> S3[3 Minimal plan]\n S3 --> S4[4 Implement]\n S4 --> S5[5 Definition of done]\n S5 --> S6[6 Review agent]\n```\n\n| Step | What happens |\n| --- | --- |\n| **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`. |\n| **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. |\n| **2. Context Brief** | One row per symbol the change touches, each with exactly one of `file:line`, `NOT FOUND`, `UNCERTAIN: ` or `AMBIGUOUS: `. No `file:line`, no code. Rules cover redefined fields, related paths, `depends`, override order, generated xmlids, magic fields, xpath anchors, multi-company, schema changes and `sudo()`. |\n| **3. Plan** | At most ten bullets; one commit and PR per git repository touched. |\n| **4. Implement** | The narrowest hook, `super()` plus the smallest delta, `_inherit = 'model'`, new files listed in the manifest, `_sudo` naming, translatable strings. |\n| **5. Definition of done** | [Commands checked on Odoo 18 and 19](skills/odoo-workflow/references/definition-of-done.md): install and test on `scratch_`, the test summary must count more than 0 tests, upgrade on a database copy when there is a migration, no unloaded files, ACL and company rules, `.pot`/`.po` refresh that keeps file names, the project's linter, hygiene checks per repository, then drop the scratch database. |\n| **6. Hand off** | The `odoo-code-review` agent, or its checklist if the agent is not installed. |\n\nTwo shortcuts keep it proportionate:\n\n- **Brief only:** \"where is X defined?\", \"does `sale.order` have F?\" run Steps 0–2 and answer with\n the Brief.\n- **Fast path:** a label, help text or typo in your own module, a manifest bump, or a test-only\n change gets a one-row Brief and skips tracing; the definition of done still applies.\n\n### The trace helper\n\n`skills/odoo-workflow/scripts/odoo_trace.py` parses the source with Python's `ast`, applies the\nversion's model-naming rules, follows `_inherit` mixins, `_inherits` delegation, `base` extensions and\nthe core `BaseModel`, skips files the module never imports, and prints absolute `file:line`. It only\nreads files.\n\n| Question | Command |\n| --- | --- |\n| Where does the runtime come from? | `odoo_trace env` / `odoo_trace roots` |\n| Which classes define or extend a model, its mixins, `_auto`, `_log_access`? | `odoo_trace model sale.order` |\n| Does a field exist (own, mixin, `_inherits`, magic), and where? A dotted path is checked hop by hop. | `odoo_trace field sale.order partner_id.country_id.code` |\n| Every definition of a method in `super()` order, with the hooks it calls | `odoo_trace method sale.order _action_confirm --module x_eval` |\n| What a module transitively depends on, in load order | `odoo_trace depends x_eval` |\n| Does an xmlid exist: loaded XML, CSV row, or generated at install? | `odoo_trace xmlid base.lang_vi_VN` |\n| Which files of a module never load? | `odoo_trace unlisted x_eval` |\n\nExit code 0 means found, 1 NOT FOUND (the verdict lists the closest real names), 2 a setup error. For\nexample:\n\n```text\n$ odoo_trace field sale.order delivery_date\nVERDICT: NOT FOUND: sale.order.delivery_date; closest fields: commitment_date (label 'Delivery Date'), ...\n\n$ odoo_trace field sale.order access_url\n.../addons/portal/models/portal_mixin.py:13 portal PortalMixin via=parent portal.mixin Char compute='_compute_access_url'\nVERDICT: FOUND via parent portal.mixin\n```\n\n## Everyday prompts\n\nYou do not need to name the skill; it triggers on Odoo work. Being explicit helps on the first run.\n\n- **Add a field or view change:** \"In module `sale_extra`, add a boolean `x_rush` to sale orders and\n show it after the warehouse on the form.\"\n- **Fix an install error:** paste the traceback, for example\n `Element '' cannot be located in parent view`. The\n innermost frame in your module is the first citation.\n- **Override behaviour:** \"After a sale order is confirmed and its pickings exist, post the picking\n names in the chatter.\" Expect it to trace `action_confirm` → `_action_confirm` and hook the right one.\n- **Rename or remove a stored field:** expect a version bump and a `migrations//` script.\n- **Ask about the source:** \"Which model gets this field on Odoo 19 when `_inherit` is a list?\"\n- **Review:** \"Review the diff of `sale_extra` for Odoo 18\" (uses `odoo-code-review` when installed).\n\nAsk for the evidence: the Brief, the test summary line, and which checks were skipped and why.\n\n## What's in the toolkit\n\n\n\n### Skills\n\n| Pack | Purpose |\n| --- | --- |\n| [Odoo 16.0](skills/odoo-16.0/) | Version-specific development references and API highlights. |\n| [Odoo 17.0](skills/odoo-17.0/) | Version-specific development references and API highlights. |\n| [Odoo 18.0](skills/odoo-18.0/) | Version-specific development references and API highlights. |\n| [Odoo 19.0](skills/odoo-19.0/) | Version-specific development references and API highlights. |\n| [Odoo Workflow](skills/odoo-workflow/) | Trace-first procedure for every Odoo change: runtime detection, the trace helper, a cited Context Brief, and a definition of done run on a throwaway database. |\n| [Odoo Commit](skills/odoo-commit/) | Odoo-style commit messages, explicit staging, and commit preparation. |\n| [Code Review](skills/code-review/) | Requesting reviews, handling feedback, and evidence-based verification. |\n| [DTG Base](skills/dtg-base/) | References for DTGBase utilities: dates, timezones, batches, barcodes, text, and files. |\n| [Flow Diagram](skills/flow-diagram/) | Interactive HTML/SVG architecture and flow diagrams. |\n| [Slide](skills/slide/) | Self-contained HTML/React presentation decks. |\n\nEach Odoo pack starts from its `SKILL.md` index and `references/api-highlights.md`, then one guide\nper topic: models, fields, decorators, views, OWL, security, controllers, actions, data, reports,\ntesting, performance, transactions, migrations, translations, mixins, manifests, development.\n\n### Agents\n\n| Agent | Purpose |\n| --- | --- |\n| [Odoo Code Tracer](agents/odoo-code-tracer.md) | Follows entry points, overrides, inheritance and side effects through the project source. |\n| [Odoo Code Review](agents/odoo-code-review.md) | Reviews Odoo changes for correctness, security, multi-company, performance and version-specific standards, with a scored report. |\n| [Planner](agents/planner.md) | Breaks a feature into implementation steps. |\n\n### Rules\n\n- [Coding style](rules/coding-style.md): naming, imports, and code organization.\n- [Security](rules/security.md): practices to fold into project instructions and review.\n\n## Odoo versions and runtime\n\nInstall the pack that matches your project: **16.0, 17.0, 18.0 or 19.0**. The workflow, its helper\nand this release's corrections to the 18.0 and 19.0 packs were checked against the Odoo 18 and 19\nsource; the rest of the packs, and 16.0/17.0 in particular, are maintained without a full\nre-verification against a checkout.\n\nThe helper takes the first of:\n\n1. The `--odoo-root`, `--conf` and `--addons` flags.\n2. `.claude/odoo.json` in the project or a parent directory, with the keys `odoo_version`,\n `odoo_root`, `conf`, `python`, `dev_db` and, optionally, `addons` (a list that replaces\n `addons_path`).\n3. An `odoo-bin` configuration in `.claude/launch.json` whose addons path covers the working\n directory. Relative `addons_path` entries resolve against its `cwd`, as `odoo-bin` does.\n4. The one `*.conf` whose uncommented `addons_path` covers the working directory, searched from the\n parent directory upwards (each level and its subdirectories). Two matching confs are a setup\n error: pin one in `.claude/odoo.json`.\n\nThe version is `version_info` in the core's `odoo/release.py`. An `odoo_version` in\n`.claude/odoo.json` or a `.odoo-version` file must agree with it, or the helper stops instead of\nguessing. The workflow and both agents resolve the version in this order:\n\n1. An explicit statement or invocation argument, such as `odoo_version: \"18.0\"`.\n2. The version stated in the project `CLAUDE.md` or `AGENTS.md`.\n3. The helper's `env` output.\n4. Agents only, when the helper is not available: the same files read by hand, then serie-prefixed\n manifest versions such as `18.0.1.0` or `18.0.1.0.0` (short addon versions like `'1.2'` are\n ignored).\n5. Nothing found, or sources that disagree: they ask. There is no default version.\n\nThe agents use the pack directory, roots and helper path the workflow passes, or look for an\ninstalled pack; if none is found they say `pack not found` instead of guessing.\n\n## Installation notes\n\n### Bundled CLI targets\n\nPaths are relative to the destination project. `PACK` is the selected directory, such as `odoo-18.0`.\n\n| Target | Files written by the CLI |\n| --- | --- |\n| `cursor` | `.shared/skills/PACK/` and `.cursor/commands/skills.md` |\n| `claude` | `.claude/skills/skills/PACK/` |\n| `antigravity` | `.shared/skills/PACK/` and `.agent/workflows/skills.md` |\n| `kiro` | `.shared/skills/PACK/` and `.kiro/steering/skills.md` |\n| `docs` | `docs/skills/PACK/` |\n| `all` | All five destinations above. |\n\nThe CLI copies whole pack directories, including the workflow's `scripts/` and `references/`. This\ndescribes file copies, not native skill discovery in every host: for Claude Code use the plugin, for\nother assistants the skills installer, or give the copied files to the assistant as context.\n\n- Run from the destination project, or pass `--dest /path/to/project`.\n- Existing files are kept unless you pass `--force`.\n- Cursor, Antigravity and Kiro share one entry file, `skills.md`; installing another pack keeps the\n existing entry unless forced, and forcing repoints it to the new pack.\n- `--offline` skips the CLI's update check; it does not make `npx` itself offline.\n- Preview with `--dry-run --offline`:\n\n ```bash\n npx @unclecat/agent-skills-cli init --ai cursor --skill skills --version odoo-18.0 --dry-run --offline\n ```\n\n### Limits to know\n\n- The workflow can only cite what is on disk: keep the Odoo source (and enterprise, if you use it) in\n a checkout the conf points to.\n- The definition of done needs a PostgreSQL server and permission to create `scratch_*` databases.\n The assistant is told never to install or upgrade on a named database unless you ask.\n- The trace helper models the static load order of all roots, not what is installed in a given\n database.\n- More tokens per task, as measured above. Use the fast path for trivial edits.\n\n## Contributing\n\nImprove version-specific references, add reproducible evals, refine review instructions, or report\ngaps through [issues](https://github.com/unclecatvn/agent-skills/issues).\n\nBefore opening a pull request:\n\n```bash\nnpm test\n```\n\nThis validates skill and agent structure, plugin paths, version consistency, changelog coverage,\nselected reference checks, the workflow's Step 1 greps on fixtures under bash and zsh, and the trace\nhelper on its fixture checkout (`tests/test_odoo_trace.sh`). It does not run Odoo itself. CI also runs\na baseline-aware SkillSpector scan; see the [CI workflow](.github/workflows/ci.yml).\n\nIf you change the helper, the greps or the workflow, also run the real-source checks against the\ncheckouts you have:\n\n```bash\nODOO_ROOT_18=/path/to/odoo/18.0 ODOO_ROOT_19=/path/to/odoo/19.0 bash tests/test_odoo_trace.sh\nODOO_ROOT=/path/to/odoo/18.0 bash tests/odoo-workflow-greps.sh\npython3 tests/bench_odoo_workflow.py --odoo 18.0=/path/to/odoo/18.0 --odoo 19.0=/path/to/odoo/19.0\n```\n\n- `tests/test_odoo_trace.sh`: hand-verified helper checks on each real checkout; run it under zsh too.\n- `tests/odoo-workflow-greps.sh`: the Step 1 greps on real source, once per checkout, under bash and zsh.\n- `tests/bench_odoo_workflow.py`: the mechanical benchmark; `--workspace /path/to/project` also checks\n that the resolved roots include the Odoo core.\n- `tests/evals/odoo-workflow/`: 24 anti-hallucination evals with fixture modules;\n [benchmark.md](tests/evals/odoo-workflow/benchmark.md) records the last agent runs.\n\nKeep new skills under `skills/` with a `SKILL.md` entry point, keep version-specific changes in their\npack, and include evidence (a source `file:line` or a command you ran) for behavioral claims.\n\n## Releases and license\n\nSee the [changelog](CHANGELOG.md) and the [npm package](https://www.npmjs.com/package/@unclecat/agent-skills-cli).\nMerging a version bump to `main` tags the release, publishes the GitHub release notes from the\nchangelog, and publishes the CLI to npm.\n\nReleased under the [MIT license](LICENSE). This is an independent community project, not an official\nOdoo product.\n",
"bytes": 24293,
"sha": "99de201dd022dd04afa0019a6b3a8bd0b67821a7e1a61f6255f201eaee810e47",
"repo_slug": "unclecatvn/agent-skills",
"fonte": "repo",
"truncated": false,
"api": "https://api.agentalog.com/api/listings/skl_unclecatvn_agent_skills_mcp_builder_99358f39/readme"
}