Skill Update

Updates installed skills safely: preview every change, back up before applying, migrate data only on approval, roll back on failure. Mode: act-as — it executes the update directly, never advises from the sideline. Backups, the update log, and config live under ~/Clawic/data/skill-update/. If you have data at an old location (~/skill-update/ or ~/clawic/skill-update/), move it to ~/Clawic/data/skill-update/.

When To Use

• User asks to update, upgrade, or version-check an installed skill.
• A skill misbehaves, stops triggering, or loses data right after an update — diagnose and roll back.
• A major bump is pending: preview breaking changes and migrate saved data before applying.
• The installed copy was hand-edited, so a straight update would overwrite the user's changes.
• Bringing everything current: update --all, or the same skill installed across several agents.
• User mentions a skill that has a newer published version — flag it once, proactively.
• Not for: publishing or versioning a skill you own (owner-side act → skill-publish); discovering or installing skills you don't have yet (→ skill-finder).

How updates break things (each maps to a preview check):

• Renamed/moved files → user data and references orphaned.
• Removed or rewritten instruction sections → the agent silently stops doing something the user relies on.
• New setup requirements (binary, env var, account) → skill half-works until configured.
• Changed data formats → previously saved state unreadable.
• Overwritten local edits → the user's customizations vanish without an error anywhere.

Quick Reference

Depth on demand: preview.md diff procedure, impact classes, security screen, recommend/defer call · migrate.md data migration patterns, script template, failure handling · rollback.md post-update breakage diagnosis and restore · local-changes.md detecting and preserving user edits · batch.md multi-skill updates and mid-batch failure · multi-agent.md version skew across agent installs.

Check installed against published:

npx clawic list              # installed skills + versions
npx clawic show        # latest published version

Catalog page mirrors the same version info: https://clawic.com/skills/.

Version delta sets the default stance (semver semantics):

Core Rules

1. A skill is behavior-as-text: every text diff is a behavior diff. Never apply one the user hasn't seen and approved.
2. The update order is load-bearing — check → detect local edits → preview → explain → confirm → backup → update → verify (→ Update Flow). Back up before applying; verify before deleting anything.
3. Explicit "yes" only. Silence, "hmm", or a topic change is not consent. Approval for skill A is never approval for update --all.
4. Diff even patch bumps. Semver is the publisher's claim, not a guarantee: a "patch" that rewrites an instruction section is a behavior change wearing a small number.
5. Verify with one real task run against the updated skill, not a file listing. Files present ≠ skill works.
6. Back up before ANY update. Retention: keep ≥backup_retention_days AND until the user confirms the new version works — whichever is later. Breakage surfaces on next real use, not at install.
7. A migration that fails mid-way stops, reports, and restores — never leave partial state.
8. Any breaking-change signal leads the summary and requires explicit approval (signals → Preview Before Update).
9. The diff is ground truth; the changelog is the publisher's summary. Read the changelog to set expectations, never to skip the diff.

Update Flow

Order is load-bearing: backup before apply, verify before deleting anything.

1. Check — compare installed vs published version; inventory every install location (multi-agent.md if more than one).
2. Detect local edits — installed copy vs its published original; edits found → local-changes.md before anything else.
3. Preview — full diff, classified by impact, security-screened (preview.md).
4. Explain — breaking changes first, in the user's workflow terms.
5. Confirm — explicit yes (Core Rule 3).
6. Backup — copy current state before touching anything (→ Backup & Update Log).
7. Update — apply the new version to every inventoried copy.
8. Verify — run one real task with the updated skill.

Preview Before Update

Never apply without showing impact. For each changed file answer: what changed, does the user's workflow touch it, is migration needed. Procedure, impact classes, and the security screen of the diff: preview.md.

Breaking-change signals — any one present means it leads the summary and requires explicit approval:

• File or folder renamed, moved, or deleted.
• Instruction section removed or rewritten (breaking even with zero structural change).
• New required setup step.
• Format change in anything the skill saves.
• Local edits on the installed copy that the update would overwrite.

Present changes in a digestible summary, breaking items first:

"Skill X has v2.0.0 available. Changes:

⚠️ Breaking: Config now in config.md (was in SKILL.md) Added: New templates/ folder with examples Removed: Old legacy.md no longer needed

Migration needed: Your saved preferences need to move. I can help migrate. Proceed?"

Each skill with a pending major gets its own preview.

Applying the Update

npx clawic update    # update one skill
npx clawic update --all    # update every installed skill with a newer version

update is the consumer-side pull — it fetches what the owner already published; publishing a new version is the owner's act, a different operation entirely (→ skill-publish). Reach for --all only when the user asked for all AND no pending update is a major (majors go one by one; sequencing and mid-batch failure → batch.md).

Proactive notification: when the user mentions a skill that has a newer version, say so once (unless proactive_notify is off or the skill is in pinned_skills). Don't re-raise it in the same session.

Backup & Update Log

Before ANY update:

1. Copy the current skill folder to ~/Clawic/data/skill-update/backups/--/.
2. If the skill being updated declares a data folder (~/Clawic/data//), back that up under the same timestamped folder — the update itself never touches it, but a migration might.
3. State the backup path in your response.
4. Append one line to ~/Clawic/data/skill-update/update-log.md: date · slug · old→new version · backup path · agents updated. The log is what lets you answer "what version was I on last week?" after the session that updated it is long gone.
5. If the update fails → offer restore immediately.

Handling Migrations

When a data format changes:

1. Read the user's actual current data first — never map from an assumed format.
2. Explain what moves and what defaults get added.
3. Execute only with approval.
4. Verify migrated data works.

Patterns (rename, structure change, folder move, learned data), script template, and failure handling: migrate.md.

Rollback

Restore = copy the backup folder back over the installed skill — and its data folder from the same timestamp if a migration ran. Offer it unprompted the moment the user reports the skill misbehaving after an update:

"Something's not working? I have a backup from before the update.
Want me to restore skill X to v1.2.3?"

Diagnosis first when the cause is unclear (symptom→cause chains, restore verification, what to do when no backup exists): rollback.md.

Output Gates

Before applying any update, verify:

• Explicit yes from the user for THIS skill, in this session?
• Diff actually read — not just the changelog or the version number?
• Local edits checked (installed copy vs its published original)?
• Backup of the skill folder AND its data folder exists, path stated to the user?
• Every install location inventoried, not just the first one found?

Before reporting success: one real task run against the updated skill?

Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in ~/Clawic/data/skill-update/config.yaml.

Preference areas — customizable dimensions; a stated preference gets recorded in config.yaml and applied:

• Tooling: where skills live (project vs global installs, which agents) — affects the Check step's inventory and multi-agent.md
• Safety posture: how majors are sequenced and how much confirmation ceremony — never below Core Rule 3's explicit-yes floor; affects Update Flow and batch.md
• Cadence: when version sweeps happen (only on request vs at session start) — affects Check and proactive notification
• Conventions: how previews and batch reports are worded (terse vs annotated) — affects Preview Before Update and batch.md reporting

Traps

Where Experts Disagree

• Update promptly vs pin and batch. Prompt updates minimize drift from published fixes; pinning batches the review cost into scheduled sweeps. The boundary is criticality, not taste: skills inside daily load-bearing workflows get pinned (pinned_skills) and reviewed deliberately; peripheral skills update as bumps appear.

Related Skills

More Clawic skills, get them at https://clawic.com/skills/skill-update (install if the user confirms):

• skill-finder - Find, compare, and install skills you don't have yet, before there is anything to update.
• skill-publish - The owner-side act update pulls from: sanitize, version, and publish a skill you own.
• skill-manager - Broader install/remove/list lifecycle and unused-skill cleanup beyond one update.

Part of Clawic, the verified skill library. Get this skill: https://clawic.com/skills/skill-update.