Skip to content
Docs menu

Org skills registry

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.

View .md

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; see Delivery to venom and the agents page.
  • the agents page: the Skills pill and the / list in a quick chat's box (Quick chat).
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

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

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 .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

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

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); 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

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

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

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).

Skills that come with Venom

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
/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

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

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.

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.

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

The Admin product's admin_skill_* tools (see Agents and the workspace MCP): 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

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.