Syncing into Gatana

Introduction

Skills are often written where they are used: in the skills folder of an agent, while working on a task. gatana skills push sends such a skill to Gatana, so it reaches the rest of the organization at their next session start. It works for a skill Gatana installed and you edited, and for a new folder you wrote yourself.

Pushing

gatana skills push                                    # everything that changed in the default folders
gatana skills push ~/.claude/skills/release-checklist # one skill folder
gatana skills push ./team-skills                      # a directory of skill folders
gatana skills push ./team-skills/deploy/SKILL.md      # one SKILL.md

Without a path, the push looks in the Claude Code and ~/.agents folders and sends every skill that changed since it was installed or last pushed. With a path, it sends that SKILL.md, that skill folder, or every skill folder in that directory.

A skill that does not exist in Gatana is created. A skill that exists is updated. The name comes from the name in the frontmatter of SKILL.md, and it must follow the name rule: lowercase letters, digits and single dashes, at most 64 characters. A folder named differently from its skill is reported, but pushed. The description in the frontmatter becomes the description in Gatana.

A skill Gatana installed carries its collection in the gatana-collection metadata of the frontmatter, so it stays in its collection when pushed. A file naming no collection is created at the root level, and an existing skill keeps its place. --collection overrides both.

Options

Conflicts

Two cases are reported as a conflict and left alone:

• The skill also changed in Gatana after your copy was installed.
• A skill with the same name exists in Gatana, but your file was never installed from it, so there is no baseline to compare against. This happens when you write a new folder by hand under a name that is already taken.

Run gatana skills install (or gatana skills sync) first to get the server version, apply your change again, and push. Push with --force to replace the server version with yours. One conflict does not stop the push: the other skills in the same run still go through, and the command exits with an error code so a script can notice.

Who can push

Creating a skill needs the right to create skills in the organization. Updating one needs Can maintain on that skill, which the creator, the people it is shared with at that level, and the organization owners have. See Permissions. A skill you cannot maintain is reported and skipped; the others in the same push still go through.