Skills

Write down how work is done in your organization once, and let every agent find and follow it

Introduction

A skill is a Markdown document that tells an agent how a job is done in your organization: how to deploy a service, how to review a pull request, how to investigate an error. Gatana stores your skills in one place and writes them into the folders your agents read, and can install hooks to keep them always in-sync.

Quick Start

Create your skills in Gatana
On each machine you want the skills: gatana skills install
They are automatically kept up-to-date.

Collections

A collection is a named group of skills. You can install a whole collection with the CLI, and share it as one unit. Deleting a collection does not delete the skills, they would simply move into root level.

Installing Skills To Your Machine

npm install -g gatana
gatana config login {organization}
gatana skills install # install all skills and the hook
gatana skills install my-collection # install all skills in collection and the hook
gatana skills install skill-123 # install specific skill and the hook

Gatana installs the skills into skills folders for Claude Code (~/.claude/skills), and Codex, Cursor, Gemini CLI, OpenCode, Copilot, Amp (~/.agents/skills), and Hermes (~/.hermes/skills). You may also provide a specific path in the CLI.

The Hook

gatana skills install will install a hook (use --no-hooks to skip) to keep the skills in-sync with Gatana. This hook is triggered on the SessionStart event of the harness (e.g. Codex or Claude Code). It runs gatana skills sync --quiet, which refreshes what each folder follows and changes nothing else. You can run gatana skills sync yourself at any time.

You may inspect the hook content:

gatana skills hook {agent} prints the block to merge by hand:

$ gatana skills hook claude
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "gatana skills sync --quiet"
          }
        ]
      }
    ]
  }
}

Push from local to Gatana

Edit an installed SKILL.md, or write a new folder, and push:

gatana skills push                                    # everything that changed here
gatana skills push ~/.claude/skills/release-checklist # one skill
gatana skills push ./team-skills                      # a directory of skill folders

A skill that also changed on the server is reported as a conflict and left alone: install first, or push with --force.

Permissions

You set the base level access of a skill:

Access	Who can read the skill
Organization	Every member (default)
Private	The creator and the people and teams it is shared with

When a skill has Private access, you can share the skill with individual accounts or teams. Each share has a level:

Level	What it gives
Can read	Read the skill, and agents acting for that person read it
Can maintain	Edit, share, change access, add and remove maintainers, delete

A skill in a collection inherits the collection's permissions.

Skills Over MCP

Agents without a folder to install into can reach the same skills over MCP, through the built-in Skills server. Its tools carry the server slug as a prefix:

Tool	What it does
`skills_list_skills`	Lists readable skills, grouped by collection. Takes a query or a collection
`skills_get_skill`	Returns one skill as a `SKILL.md` document
`skills_create_skill`	Saves a new skill, optionally private to teams or in a collection
`skills_update_skill`	Changes description or instructions, or renames

To make agents check for skills first, add one line to the project's CLAUDE.md: "At the start of a task, call skills_list_skills and follow any skill that applies."