Update a user skill
You were called because the user typed /update-skill <target-and-change> in the chat input. Your job for this turn is locate the right user skill and apply the requested change to its setting/skills/<id>/SKILL.md. Reuse fs_write — no other writes.
Inputs you have
- The free-text after
/update-skillin the most recent user message — usually mixes a target hint ("the warm-healing skill") with the actual change ("add a frame-spacing rule for vertical layouts"). Parse out both. - The skill catalogue in your system prompt — the authoritative list of user/merged skills with their ids and one-line descriptions.
Resolve the target
- Direct id match — if the brief contains an obvious skill id (kebab-case token matching the catalogue), use it. Done.
- Name match — otherwise scan the catalogue's
nameanddescriptionfor the best fit. If exactly one matches, use it. Done. - Multiple candidates / no match — reply with the candidates (or "no matching skill found") and stop. Do not guess.
Constraints:
- Only
user/mergedskills can be updated. If the user references a system-only skill id, reply explaining the limitation and stop. - Never create a new file in this flow. If the resolved target doesn't exist on disk, reply and stop —
/create-skillis the right command for that.
Read before you write
Always read("skills/<id>/SKILL.md") first to see the current content. Do not rely on the catalogue blurb or your memory of the file.
Pick the mode
replace_string— default. Use whenever the change can be expressed as "find this exact existing block, replace it with this new block". Safer: nothing else in the file is touched. Pick a uniqueoldString(add 1–2 lines of surrounding context if the snippet is otherwise common).overwrite— only when the change is structural (sections reorganised, more than half the file rewritten). You then submit the entire file including the frontmatter fence — anything you omit is permanently deleted.
The rationale field is ignored for updates (it's only checked when creating a new skill).
Write it
For a targeted edit:
{
"path": "skills/<id>/SKILL.md",
"mode": "replace_string",
"oldString": "## When to use\n\nUse for plot-driven stories with a clear antagonist.",
"newString": "## When to use\n\nUse for plot-driven stories with a clear antagonist, including episodic TV bibles."
}
For a structural rewrite:
{
"path": "skills/<id>/SKILL.md",
"mode": "overwrite",
"body": "---\nname: \"…\"\ndescription: \"…\"\nappliesTo: [\"ask\", \"operate\"]\n---\n\n# …\n\n## When to use\n\n…\n"
}
After writing
- Briefly confirm to the user: skill id, mode used (
replace_string/overwrite), and a one-line summary of what changed. - Do not make Space changes in the same turn.