update_skill
Apply surgical edits, create or replace files, or delete files to update an editable skill and save a new version instantly without a publish step.
Instructions
Save changes to an editable skill — writes a new version (no publish step).
Three composable ways to change files in ONE version. Prefer file_edits for
small changes — it sends only the changed text, not the whole file.
file_edits — surgical find/replace on an EXISTING file. Maps path ->
list of edits, e.g.
{"reference/style-guide.md": [{"find": "—", "replace": "-", "count": 5}]}
Each `find` must match exactly `count` times (default 1); a 0-match or a
count mismatch is rejected so you fix the string rather than write blind.
Use a longer, unique `find` for a single edit, or set `count` to replace
all occurrences. THIS IS THE CHEAP PATH for fixing a few characters.
file_changes — create a new file or whole-file replace. Maps path ->
full markdown, e.g. {"SKILL.md": "...", "reference/new.md": "..."}.
Use for new files or large rewrites.
delete_files — remove files, e.g. ["reference/old.md"]. SKILL.md can't be
deleted (it is the contract).
FILE LAYOUT (where files go — get_skill surfaces them by these prefixes):
- reference/* docs the agent READS (style guides, pipelines, specs).
- data/* assets the skill CARRIES, incl. runnable scripts. Put a
checker like data/verify_row.py HERE (not reference/) so it
travels with the skill and get_skill lists it as runnable —
the agent then read_skill_file()s it and EXECUTES it as a gate.
Built-in skills are read-only — update is rejected; create_skill(extends=...)
first, then update that copy.
Args:
skill_id: The editable skill id (user/... or project/...).
file_changes: {path: markdown} — create/replace whole files.
file_edits: {path: [{find, replace, count?}]} — surgical edits to existing files.
delete_files: [path, ...] — files to remove.
change_summary: Short note on what changed (for version history).
expected_version: If set, the save fails with a conflict unless the
skill is still at this version (safe concurrent editing).
verbatim_source: When PORTING/refactoring existing content, pass the
original text. The store returns a fidelity report on the resulting
files — a FAIL means content was silently condensed (re-port the
missing segments; don't claim done). Splitting + intentional edits OK.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| config | No | ||
| skill_id | Yes | ||
| file_edits | No | ||
| delete_files | No | ||
| file_changes | No | ||
| change_summary | No | ||
| verbatim_source | No | ||
| expected_version | No |