Publish, update, and roll back

Prepare Skill content

A repository can contain multiple Skills:

repository/
├── .skills-platform.yaml
└── skills/
    ├── sql-query/
    │   ├── SKILL.md
    │   └── references/guide.md
    └── code-review/
        └── SKILL.md

Example SKILL.md:

---
name: sql-query
description: Analyze database schemas and write read-only queries.
---

Read the [query guidelines](references/guide.md) before querying.

Commit SKILL.md together with referenced files. Skiva does not follow symbolic links or recursively fetch submodules.

Update an existing Skill

1. Change content in Git, commit, and push to the configured ref.
2. A webhook triggers synchronization; you can also synchronize manually. The worker checks periodically every minute.
3. Inspect pipeline diagnostics, the Registry version, and file differences.
4. Create a complete snapshot with the updated Skill and unchanged versions of other Skills.
5. Promote Canary and verify test-client files and Agent behavior.
6. Promote the same snapshot to Stable and record the reason.

Configuration or validator changes may revalidate the same commit. Unchanged content does not necessarily create a new content version.

Review before publishing

• Did the complete set accidentally omit another Skill?
• Are all relative references present?
• Have security warnings been reviewed? Blockers must be fixed; acknowledgement cannot bypass them.
• Are affected Profiles expected?
• Do pinned clients need a repin between tasks?

Roll back a channel

Choose a snapshot previously used by that channel, enter a reason, and confirm. Rollback creates a new history record and generation; it does not rebuild Git.

Dynamic clients follow the rolled-back channel. Pinned clients retain their snapshot until explicitly repinned between tasks. Content already loaded into an Agent's context does not disappear automatically.

Confirm delivery

Check the client's latest heartbeat and snapshot ID in the console or run status. Use refresh for an explicit refresh. SSE provides hints and polling is the fallback; instantaneous switching of every endpoint is not guaranteed.

skills-mount status
skills-mount refresh
# Pinned: run only between tasks
skills-mount refresh --repin

If you use a custom --cache, pass the same cache path to these commands.