---
title: Org skills registry
description: Keep your organisation's reusable agent skills in one place in Venom Cloud, add them from a GitHub repository, by upload or by writing them, turn each on or off, change several at once, approve updates from their source, and roll back to any version.
section: cloud
order: 63
audience: [user, operator, builder, agent]
sources: [services/nodejs-cloud/lib/skills/client.ts, services/nodejs-cloud/lib/skills/agents.ts, packages/harness/src/library, packages/harness/src/extensions/library.ts, services/nodejs-cloud/app/(console)/(shell)/skills, services/nodejs-cloud/lib/skills, services/nodejs-cloud/app/api/admin/v1/skills, services/nodejs-cloud/app/api/cron/skills, services/nodejs-cloud/lib/orgs/mcp-skills.ts, docs/adr/0084-org-skills-registry.md]
features: [cloud.console-skills, cloud.api-admin-skills]
---

The **Skills** page (`/skills`, in the Team group next to MCP servers) is your organisation's registry of agent skills. A skill
is a folder with a `SKILL.md` (front matter with a `name` and a one-line `description`, then the instructions) and text files
next to it: the same format Claude Code and the Agent Skills spec use. The registry stores each skill with every version and the
SHA-256 of its files, remembers where it came from, and decides who it is for.

Each skill has one switch: **on** or **off**. A skill that is on reaches the people in its scope in two places, without a release:

- **venom** (the CLI): every signed-in venom gets the org's skills that are on with its next start, and on `/library refresh`, over
  the same `GET /v1/library` it already uses for the [team library](/docs/cloud/console-library.md); see [Delivery to venom and the agents page](#delivery).
- **the agents page**: the Skills pill and the `/` list in a quick chat's box ([Quick chat](/docs/agents/quick-chat.md#skills)).

| Page | What it does | Read | Change |
|---|---|---|---|
| `/skills` | the list: search, the On / Off chips, a switch and a delete button on each row, select rows to turn on, turn off, edit, delete or download several, source, who gets it, last updated, an "Update waiting" badge | `routing:read` (owner, admin, developer, viewer) | `org:manage` (owner, admin) |
| `/skills/new` | add skills: explore a GitHub repository or URL and choose from it, upload files, or write one | | `org:manage` |
| `/skills/{id}` | the Available switch, Download .zip, files (view and edit), source and update check, the pending update with its diff, scope, versions with compare and roll back | `routing:read` | `org:manage` |

Members without the manage role see only the skills that are on, read only, with **Available to you** where their scope says so.

## On and off {#on-off}

A skill is either available or it is not. The switch on its row (and **Available** on its page) changes that at once:

- **On**: the people in its scope get it on their next sync.
- **Off**: nobody gets it. Its files, versions and scope are kept, so turning it on again brings back exactly what was there.

A new skill is on as soon as it is added. There is no draft step: to keep a skill back, turn it off. The **On** and **Off**
chips above the list filter by the switch. Skills that were drafts before this change are off.

## Select and change several {#bulk}

Tick rows, or tick the box in the list's header to select every row the search and chips show. The bar above the list then acts
on the selection:

| Button | What it does |
|---|---|
| **Turn on** / **Turn off** | switches every selected skill; one that is already in that state is left alone |
| **Edit** | sets who gets the selected skills (the whole organisation, or key groups you choose) and whether they are required. A field left at **Keep as is** is not changed |
| **Delete** | removes the selected skills with every version of each, after you confirm the list of names. This cannot be undone |
| **Download selected** | one zip with a folder per skill |

Each skill is changed and audited on its own (`skills.published`, `skills.disabled`, `skills.updated`, `skills.deleted`). If one
cannot be changed, the others still are, and the page lists the ones that failed with the reason. The trash button on a row
deletes that one skill, after the same confirmation.

## Download skills {#download}

**Download .zip** on a skill gives `<slug>.zip`: a folder named for the skill with `SKILL.md` and the files beside it, exactly as stored (the current version), so it unpacks straight into `.claude/skills/` or a venom skills directory. On the list, tick skills and choose **Download selected**, or with nothing ticked choose **Download all**: one `venom-skills.zip` with a folder per skill. A skill with no approved version has nothing to download and is left out.

Who may download is who may read: `routing:read`, and a member without `org:manage` gets only the skills that are on (owners and admins also get the ones that are off). Another organisation's skill is never found. File paths are made safe (`/` separators, no `..`) and names that would collide are numbered. A zip is at most 10 MiB, the size an upload may be: download fewer skills at a time past that. Each download is audited as `skills.exported`.

## Add skills {#add}

Open `/skills/new` and choose one of three ways. A new skill is **on** at once for whoever you scope it to.

### From GitHub or a URL {#explore}

Paste a public https URL and choose **Explore**. The cloud fetches it **once** and lists every skill it holds: each folder with a
`SKILL.md`, and each packed `.skill` file. Nothing is stored yet.

| URL | What is listed |
|---|---|
| `https://github.com/owner/repo` | every skill in the repository's default branch |
| `https://github.com/owner/repo/tree/<ref>/<folder>` | the skills under `<folder>` at `<ref>` |
| `https://github.com/owner/repo/blob/<ref>/<path>/SKILL.md` | that one skill |
| `https://example.com/pack.zip`, `.tgz` | every skill in the archive |
| `https://example.com/pack.skill` | the skill packed in that file |
| `https://example.com/SKILL.md`, a raw URL | that one skill |

Each row shows the skill's `/name`, title, description, path, file count and size. Tick the ones to add (everything that can be
added is ticked to start with) and choose **Add**. A row cannot be ticked when:

- **Already added**: your registry has a skill of that name.
- **Cannot be added**: it fails a check (see [What is accepted](#what-is-accepted)); the reason is under the row.

Every skill you add is copied into the registry with its hash. A skill from a GitHub repository keeps following **its own folder**
(or its own `.skill` file): the daily check pulls that folder, and a change waits for your approval. Skills taken from an archive
that holds several are kept as plain copies, because the archive's URL cannot name one of them; an archive that holds a single
skill is followed like any URL.

`<ref>` is one path segment: a branch whose name contains a slash cannot be named in a `/tree/` link (use a tag, a commit or an archive URL).
Only public URLs work; the cloud sends no credentials. A repository is read as its archive: at most 10 MiB, 5,000 entries and
40 MiB unpacked.

### Upload

Choose one or several files: `.skill` files (a zip of a skill folder), plain `.zip` archives, `.tgz`, or `SKILL.md` and markdown
files. The format is told by each file's bytes. An archive that holds several skills adds every one of them. With a single file
you can give a name (the `/command`) if SKILL.md has none, and a **folder** to take just one skill of an archive. When several
skills come out of an upload, the page lists each one as added or not, with the reason. An upload is at most 3 MiB in all.

### Write

Type `SKILL.md` and, if the skill needs them, other files. Leave the name empty to use the one in SKILL.md.

### What is accepted {#what-is-accepted}

Every route in is checked the same way, and a refusal says what to fix:

| Rule | Limit |
|---|---|
| Files next to `SKILL.md` | 20 |
| One file | 64 KiB |
| The whole skill | 256 KiB of text |
| File types | text only: Markdown, text, JSON, YAML, TOML, CSV, HTML, CSS and source or script files (`.py`, `.sh`, `.js`, `.ts` and so on); an image, a binary or an archive inside the skill is refused by name |
| Paths | relative, at most 4 levels, no `..`, no leading dot, no backslash |
| An uploaded or pulled archive | 10 MiB, 5,000 entries, 40 MiB unpacked; encrypted entries, links, duplicate names and entries that inflate past their declared size are refused |
| A description | required, at most 1,024 characters; without front matter the first paragraph is used and the page says so |

## Versions, hashes and approval {#versions}

Every change is a new numbered version that is never edited afterwards; its `sha256` is the hash of its files, so the same files hash
the same however they arrived.

- **Your own edit** (console, API or MCP) is a new approved version at once.
- **An update found at the source** is a **pending** version. It changes nothing for anyone. The skill page shows each changed file
  as a line diff; **Approve and apply** makes it current, **Reject** declines it, and the same change is not proposed again.
  Approval names the version you reviewed: if the source changed again in between, the approval is refused so you review the new one.
- **Check for updates** pulls the URL now. A daily cron checks the URL skills not checked for 23 hours. A failed check is recorded on the
  skill (shown as **Update check failed**) and changes nothing.
- **Apply updates without approval** is a switch on one URL skill, off by default.
- **Roll back** makes an earlier version's files the next version. At most 100 versions are kept per skill.

## Who gets it {#scope}

A skill's scope is a list of key groups and a list of members. With neither it is for the whole organisation. **Required** means
it is loaded in every session of whoever it reaches. Turning a skill **off** takes it away from everyone and keeps its history;
turning it **on** brings it back ([On and off](#on-off)).

## Skills that come with Venom {#first-party}

Every organisation starts with the skills Venom ships, owned by **Venom** in the list. Today there are two:

| Skill | What it is for |
|---|---|
| `/tech-due-diligence` | A technical due diligence of someone else's code, done safely: context from People, Granola, Notes and Tasks, a quarantine clone, a malware check from metadata before anything is read, and the reports. [More](/docs/cloud/claude-code-skills.md#due-diligence) |
| `/studio-artifact` | How an agent makes a Venom Studio deck, page or HTML page: brief, research where needed, outline in the chat, build, review, answer with sources. A quick chat with Studio in its picker offers it even when nobody picked it (turn it off here to stop that). [More](/docs/studio/agents.md#workflow) |

They are ordinary registry skills: on, for the whole organisation, not required. An owner or admin can change that:

- **Turn it off** and it is gone for everyone, and stays off.
- **Scope** it to key groups or members, or mark it required.
- **Edit** its files. From then on it is yours: Venom's later versions are not applied.
- **Delete** is undone by the next daily run, which adds it back. Turn it off instead.

An untouched one moves to the new files when a Venom release changes them, as a new approved version (the old one is kept, so
you can roll back). A slug your organisation already uses, here or in the team library, is never replaced. These changes are
in the audit log as `skills.created` and `skills.updated` by `system:venom`, with `first_party: true`. Nothing is fetched:
the files are part of the Venom Cloud release.

## Delivery to venom and the agents page {#delivery}

**In venom.** A skill that is on and whose scope takes the member (the whole org, their name, or one of their key group) is a skill
item on `GET /v1/library`, marked `origin: "registry"`. venom caches it on disk with the rest of the library, so it works offline
from the cache, and loads it as an ordinary skill: only its name and one line are in the system prompt, and the body is read when
the agent uses it or the member runs it. The skill appears in the `/` menu as `/name`, marked with the organisation's name; `/name
args` sends its instructions with your arguments (`/skill:name` works too, and `/library` lists it). A skill with the same name as one
in your own skill folders yields to yours unless the org marked it **required** (`library.hidden` in `venom.yaml` can hide the others).

Each registry skill carries its hash (`sha256`, over SKILL.md exactly as approved and the other files) and venom checks it before
writing anything: a skill whose files do not match is not installed, with a diagnostic. A skill that is **off** or out of scope is
absent from the next answer, so venom removes it from its cache at the next sync. A skill's scripts run only through venom's permission
engine like any other command.

**On the agents page.** The member's skills are the same rule applied to their account. See [Quick chat](/docs/agents/quick-chat.md#skills).

## API {#api}

With an admin credential or a signed-in org member; changes need `org:manage`, reads `routing:read`.
Another organisation's skill is always a 404.

| Method and path | What |
|---|---|
| `GET /api/admin/v1/skills` | the list |
| `POST /api/admin/v1/skills` | create from `files` (a list of `{path, content}`), `skill_md` (text) or `url` (with optional `folder`), plus `slug`, `title`, `description`, `required`, `team_ids`, `member_uids`, `auto_apply` (URL only), `enabled` (default true), `note` |
| `POST /api/admin/v1/skills/upload` | the file as the request body (at most 4 MiB); query `name` (the file name), `slug`, `folder`, `enabled`, `required`, `team_ids`, and `all=1` to add every skill of an archive that holds several (the answer then lists each) |
| `POST /api/admin/v1/skills/explore` | `{url}`: the skills that URL holds, each with `path`, `slug`, `title`, `description`, `files`, `bytes`, `exists`, `tracks_source` and `problem` when it fails a check. Stores nothing |
| `POST /api/admin/v1/skills/import` | `{url, paths}` (paths from explore) or `{url, all: true}`, plus `required`, `team_ids`, `member_uids`, `auto_apply`, `enabled`, `note`: adds them in one pull and lists each result |
| `POST /api/admin/v1/skills/bulk` | `{ids, action}` with `action` `enable`, `disable`, `delete` or `update` (`required`, `team_ids`, `member_uids`): one change to many skills, each result listed |
| `GET /api/admin/v1/skills/export` | the skills as a zip: `ids` (skill ids, comma separated) or `all=1`; `routing:read`, only the skills that are on for a member without `org:manage` |
| `GET /api/admin/v1/skills/{id}` | files, versions, the pending update with its changes |
| `PATCH /api/admin/v1/skills/{id}` | `files` or `skill_md` (a new version), `title`, `description`, `required`, `team_ids`, `member_uids`, `auto_apply`, `note` |
| `DELETE /api/admin/v1/skills/{id}` | remove it with every version |
| `POST /api/admin/v1/skills/{id}/publish` | turn the skill on for its scope |
| `POST /api/admin/v1/skills/{id}/disable` | turn it off; history is kept |
| `POST /api/admin/v1/skills/{id}/check` | pull the source URL again |
| `POST /api/admin/v1/skills/{id}/approve` | make the pending version current (`version` optional, recommended) |
| `POST /api/admin/v1/skills/{id}/reject` | decline the pending version |
| `POST /api/admin/v1/skills/{id}/rollback` | `{version, note}`: that version's files become the next version |
| `GET /api/admin/v1/skills/{id}/versions/{version}` | one version's files |
| `GET /api/cron/skills` | the daily update check (the cron secret, not for people) |

A skill that cannot be created answers 400 with `code` and, when there are several problems, `errors`: for example `invalid_skill`,
`not_text`, `several_skills`, `archive_unsafe`, `archive_too_large`, `skill_exists`. A URL the cloud may not call is a 422 `url_blocked`; a
server that fails or times out is a 422 `fetch_failed`.

A skill's `enabled` is true when it is on. `status` is kept for older clients: `published` is on and `disabled` is off. `publish` on a
create is the older name of `enabled`. The batch calls (`import`, `bulk`, an upload with `all=1`) answer 200 or 201 with a `results`
list even when some skills fail: read each entry's `ok` and `error`.

```bash
curl -sS -X POST "$VENOM_CLOUD/api/admin/v1/skills" \
  -H "authorization: Bearer $VENOM_ADMIN_TOKEN" -H "content-type: application/json" \
  -d '{"url": "https://github.com/acme/skills/tree/main/skills/pdf-forms", "enabled": false}'

# What a repository holds, then two of its skills in one pull.
curl -sS -X POST "$VENOM_CLOUD/api/admin/v1/skills/explore" \
  -H "authorization: Bearer $VENOM_ADMIN_TOKEN" -H "content-type: application/json" \
  -d '{"url": "https://github.com/acme/skills"}'
curl -sS -X POST "$VENOM_CLOUD/api/admin/v1/skills/import" \
  -H "authorization: Bearer $VENOM_ADMIN_TOKEN" -H "content-type: application/json" \
  -d '{"url": "https://github.com/acme/skills", "paths": ["skills/pdf-forms", "skills/brand-voice"]}'
```

## For agents: MCP {#mcp}

The Admin product's `admin_skill_*` tools (see [Agents and the workspace MCP](/docs/cloud/agents-capabilities.md)): `admin_skill_list`,
`admin_skill_get`, `admin_skill_export` (the download url and the zip as base64 when it fits), `admin_skill_version_get`, `admin_skill_create`, `admin_skill_import`,
`admin_skill_source_preview` (what a URL holds), `admin_skill_source_import` (several of them in one pull), `admin_skill_update`,
`admin_skill_scope_set`, `admin_skill_refresh` (check the source), `admin_skill_approve`, `admin_skill_reject`,
`admin_skill_publish` (turn on), `admin_skill_disable` (turn off), `admin_skill_rollback`, `admin_skill_delete`, `admin_skill_bulk_update` (turn several on or
off, or set their scope) and `admin_skill_bulk_delete`. They run with the member's role, with
the agent as the actor in the audit log, and refuse an argument they do not declare. `admin_skill_import`, `admin_skill_source_preview`, `admin_skill_source_import` and
`admin_skill_refresh` make one outbound request each.

## Security {#security}

A skill is instructions an agent follows, so a skill pulled from a URL is a supply-chain input, and the registry treats it as one.

- The cloud stores its own copy and pins every version by hash.
- An upstream change never reaches anyone until an admin has approved the diff, unless that skill's own auto-apply switch is on.
- Only owners and admins add skills, approve updates, or turn a skill on or off.
- The pull is the registry's one outbound call. It runs only when an admin explores or imports a URL or asks for a check, and in the daily check of
  the URL skills an admin imported. It needs https, refuses loopback, private, link-local and metadata addresses (checked again on every
  redirect hop), sends no credentials, stops after 15 seconds or 10 MiB, and refuses web pages.
- Archives are read as untrusted input (limits above) and nothing in a skill is executed by the cloud.
- The audit log (`skills.created`, `updated`, `published`, `disabled`, `update_found`, `approved`, `auto_applied`, `rejected`,
  `rolled_back`, `deleted`) records slugs, versions, hashes and source URLs, never the text.

## Related

- [Team library and starter packs](/docs/cloud/console-library.md): prompts and skills venom loads, over the same endpoint.
- [Quick chat](/docs/agents/quick-chat.md#skills): skills in the agents page.
- [Agents and the workspace MCP](/docs/cloud/agents-capabilities.md): the generated list of every tool.
