# Skills

A skill is a folder with instructions and optional scripts or reference files. A bot reads the skill when it uses it. Use a skill to teach a bot a repeatable job, such as how to read a PDF or how your team writes a report.

A skill is an object of the organization. One skill can serve many bots. Skills run in the [workspace](/workspace) of the bot, so a bot needs a workspace to use them.

## Create a skill

Owners, Admins, and Builders open Skills in the Console and choose New skill. There are two ways:

- **Write a skill.** Enter a name, tags, a description, and the instructions. The instructions are the body of `SKILL.md`, in Markdown. The bot reads it when it uses the skill. Optionally add files next to it. The whole skill can be at most 20 MB.
- **Import a zip.** Upload a zip that contains one `SKILL.md`. Name and tags are optional. Name and description are taken from `SKILL.md` when empty, but the skill needs a description from one of the two, or bots would not load it. GEKI adds a missing `name` or `description` to the `SKILL.md` frontmatter when it saves the skill. The zip can be at most 20 MB.

A name uses lowercase letters, digits, and hyphens.

## Needs hosts and Needs credentials

A skill can say what it needs in the workspace.

- **Needs hosts.** The host names the skill calls, such as `api.github.com`.
- **Needs credentials.** The names of the environment variables the skill reads, such as `GITHUB_TOKEN`.

These fields are optional. They matter when the bot has restricted internet access. GEKI adds the hosts of every skill the bot uses to the allowed list. The bot editor warns when a needed credential is missing from the vaults of the bot, or when a host cannot be reached because the bot has no internet access. The warnings show in the editor and next to Publish. They never block Publish. See [Workspace](/workspace) and [Tools and MCP connectors](/tools).

## Versions

A skill has numbered versions, starting at 1. When you change a skill, you choose:

- **Save as new version.** Existing bots stay on the version they use.
- **Overwrite.** The current version changes for every bot that pins it. The Console lists those bots before you confirm.

The skill page shows the versions, the current one, the needs, and which bots use it.

## Use a skill in a bot

In the bot editor, open Capabilities, Skills. Choose **Add skill** for each skill the bot uses and pick a version. A badge says "New version available" when a newer version exists. Publishing the bot copies the pinned versions into the live bot.

On the [Personal bot](/personal-bot), you also pick the mode for each skill: Always, On by default, or Off by default.