update_skill
Destructive
Save edits to an editable skill as a new version without publishing, using targeted find/replace, whole-file updates, or file deletions.
Instructions
Save changes to one of the user's editable skills as a new version (no publish step).
Use when the user asks to change a skill they own or share through a project (as its owner, an
admin or an editor; a project viewer can use a skill but not change it). Three ways to
change files, combinable in one version; file_edits sends only the changed text, so it suits
small changes.
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 and nothing is written. A longer, unique `find`
targets one place; `count` replaces several occurrences.
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 (get_skill lists files by these prefixes):
- reference/* documents (style guides, pipelines, specs).
- data/* assets the skill carries, including runnable scripts such as a
data/verify_row.py checker.
Built-in and Unilytics skills are read-only and an update to one is rejected;
create_skill(extends=<skill_id>) makes an editable copy.
Size: the whole SKILL.md loads on every run of the skill. In a well-kept skill a correction or a
new step is one line in SKILL.md at the step it changes, and its detail (examples, edge cases,
the why) sits in that phase's reference/ file, which keeps SKILL.md under 500 lines.
The result's `lint` lists authoring findings on the saved version, as lint-v1 rule ids with a
message and a fix: body.too_long (the body's line count and its largest sections),
references.unlinked, description.no_trigger, and the frontmatter or description problems an
Agent Skills export refuses. Findings don't stop the save. The save is refused (skill_md_invalid,
nothing written) when the change introduces a SKILL.md frontmatter break, or makes the description
longer than 1,024 characters or a description already over that longer; a problem already there
that the change leaves untouched is allowed.
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: The version the change was made on (get_skill returns it). Required for a
project skill, which collaborators share, and optional for the user's own. The save fails with
version_conflict (naming who saved the newer version and when) unless the skill is still at it.
verbatim_source: When porting or restructuring existing content, its original text. The
store returns a fidelity report on the resulting files: FAIL means content was condensed
or dropped; splitting and intentional edits pass.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"skill_id": "<skill_id>"
},
"name": "update_skill"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| skill_id | Yes | ||
| file_edits | No | ||
| delete_files | No | ||
| file_changes | No | ||
| change_summary | No | ||
| verbatim_source | No | ||
| expected_version | No |