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.
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 sameGET /v1/libraryit 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.
Related
- Team library and starter packs: prompts and skills venom loads, over the same endpoint.
- Quick chat: skills in the agents page.
- Agents and the workspace MCP: the generated list of every tool.