Improve a skill
Fix a field, add fields, or re-learn how a skill opens each result. It goes live only if a check run shows it is better.
mode: fix (default), add_fields, or relearn_details. feedback is required for the first two. The call answers at once; read Get an improvement until status is done or failed.
When to use each mode, how to read a run’s diagnosis, and what happens step by step are in Improve a skill.
MCP tool: improve_skill.Authorizations
API key with the vd_sk_ prefix, as Authorization: Bearer vd_sk_.... Create keys in Settings → API Keys.
Headers
Any unique string (such as your order id). Resending the same request with the same key within 24 hours returns the first answer (with Idempotent-Replayed: true) and does nothing twice; the same key with a different request is a 422 idempotency_key_reused.
1 - 255Path Parameters
Body
What to change, in plain English, the way you would coach a person doing the task.
fix: fill fields the skill misses, from a hint about where the data is (the default). add_fields: capture NEW fields described in plain English. relearn_details: rebuild how the skill clicks into each result (its per-row detail steps) — for a site that changed or detail fields that come back empty.
fix, add_fields, relearn_details fix: what the skill gets wrong and where the data really is, e.g. 'The phone is on the details page — click the place name, the panel opens, the number is next to the phone icon.' add_fields: the new fields, e.g. 'also capture the star rating and the review count'. relearn_details: an optional note, e.g. 'the details now open in a side panel'. Required (3+ characters) for fix, and for add_fields unless fields names them.
2000fix: the output fields the hint is about (e.g. ["phone"]); omit to use the fields the last run came back without, or the ones the hint names. add_fields: the new fields' names, when you know them. relearn_details: only re-learn these detail fields.
Inputs for the check run (max 5 rows) that proves the improvement. Omit to use the skill's recorded example.
The browser to learn and check on: remote (cloud browser) | extension (your Chrome). Omit to use the browser the skill normally runs on (its saved browser mode, else remote). A skill that runs in your Chrome needs the extension connected.
Response
Improvement started (or the existing one, for a repeated Idempotency-Key).
Where an improvement is: queued → working → validating → done | failed.
done with improved: true means the new recipe version is live; done with
improved: false means the attempt was kept as a candidate version (not live) and
outcome says why. failed means the engine could not run (error). result
says the same in one word.
fix, add_fields, relearn_details Who asked: api | mcp | assistant (Igris) | web | brain (workflow Brain) | imported (from the old Refine history)
running | improved (new version live) | kept_old (not better — the old version stays, the attempt is candidate_version) | no_change (nothing to learn or nothing changed) | failed (could not run) | applied (imported: applied without a check run)
running, improved, kept_old, no_change, failed, applied An entry imported from the old Refine / Re-learn history
The id of the account that asked for it
What the engine made of the words: for add_fields, the request diffed against the skill's contract (genuinely new fields, re-worded duplicates merged into an existing field, ones it could not place, asked back as a question); and what the learn pass did.
fields (re-learn where the fields live) | rerecord (re-do the steps)
The diagnosis the improvement started from
The check run's diagnosis, when it still came back short
Target fields, before → after
The live recipe version once done
Set when the attempt was kept as a candidate, not made live

