Authoring & publishing

A skill is a folder in the open agentskills.io format. To govern it — to version it, deprecate it, or ban it across every developer's machine — you add one small manifest and publish it to your organisation's registry. This page covers writing a skill, making it governable, and shipping it.

What a skill is

A skill is a directory with a required SKILL.md and optional bundled resources:

crm-entry/
├── SKILL.md          # required: frontmatter + instructions
├── skillsvault.json        # makes the skill governable (see below)
├── scripts/          # optional: code the skill runs
├── references/       # optional: docs the agent reads on demand
└── assets/           # optional: templates, images, fixtures

SKILL.md is YAML frontmatter — a name and a description are the minimum — followed by the instructions the agent follows:

---
name: crm-entry
description: Create and update HubSpot contacts from a deal brief. Use when a rep
  hands off a closed deal that needs a CRM record.
---

# CRM entry

1. Parse the deal brief for company, contact, and value.
2. Upsert the contact in HubSpot…

Make it governable

A published skill always has a namespaced identity (namespace/name), so a policy can target it by namespace or as a Specific skill. Add an skillsvault.json manifest next to SKILL.md to carry that identity and a version with the folder, plus the intent and targets metadata — targets are what target policies match on:

{
  "skillsvault_schema": 1,
  "manifest_id": "mf_91ac3d",
  "name": "acme/crm-entry",
  "version": "1.4.0",
  "namespace": "acme",
  "intent": "crm-data-entry",
  "targets": ["hubspot"],
  "description": "Create and update HubSpot contacts from a deal brief."
}

The manifest is additive — a harness that doesn't know about skillsvault ignores it entirely. See the manifest reference for every field.

Publish a skill

skillsvault login

skillsvault publish ./crm-entry

✓ published acme/crm-entry@1.4.0 (3 bundled files)

skillsvault publish ./crm-entry --name acme/crm-entry --version 1.4.0

Submit a skill for review

Members don't publish directly, but they can propose. Propose skill in the sidebar opens the same editor, AI assist included; Propose a change on any skill opens it with that skill's current content. Instead of saving, Submit for review sends the draft, with a note for reviewers, to Requests. From the terminal, a member's skillsvault publish is recorded as a submission the same way.

Owners, admins and governance officers get an email and a count beside Requests. A submission shows the change as a diff against the current version, the risk summary, what the scanner reads it as doing (shell, packages, network, environment variables, writes), the AI review (run when it is submitted, so it's ready when you open it), and what the gate would decide under today's policies if it were approved. Approving publishes a version that keeps that review: the content is reviewed once. Then:

• Approve and publish publishes it as a new version (a new skill starts at 0.1.0; for a change, the reviewer picks the version bump).
• Request changes sends it back with a note, which is required.

The author gets an email either way, can Withdraw a submission while it waits, and after Request changes can Revise and resubmit, which reopens the editor with what they submitted. Nothing a member submits reaches a machine until it is approved. A member can have up to 10 submissions awaiting review at a time.

Versions are immutable

Every publish creates a new, immutable version and records a content hash the registry computes — you never set it. Re-publishing a version with the same content is a no-op; publishing an existing version number with different content is refused (409), so bump the version for every change. The most recently published version becomes current: it is the one that distributes to harnesses and that the gate reports.

Use semantic versioning: bump the patch for a fix, the minor for additive instructions, the major when behaviour changes in a way that could break callers.

Status drives distribution and the gate

A skill's status is set in the console and has a precise, observable effect:

Banning is the lever behind the classic migration fix: ban the old skill, publish its replacement, and the next sync removes the dead skill from every machine while the gate blocks any lingering invocation with your reason.

Import an existing skill

You don't have to author from scratch. In Registry → Add from source, type in Search skills.sh to find a skill in the public skills.sh directory: each result shows its source repository and install count, and Add references it. Skills your organisation already references are marked Added. Or paste an origin:

• a GitHub repo (owner/repo or a github.com/... URL),
• a skills.sh listing,
• or a raw SKILL.md URL.

skillsvault fetches the SKILL.md from its repository (never from the directory), runs the scanner and the AI review on it, and adds it to your registry. Imported skills keep a link to their origin. skillsvault re-checks every external skill daily (and when you press Check origin): an imported skill whose source now differs from its current version is marked Changed at source, and one whose source stopped answering, Origin unreachable. Machines keep running the version you reviewed either way; Update from origin brings the new content in as a version, scanned and AI-reviewed. Turn on the An imported skill changed at its source alert to hear about it in Slack.

Version history and diffs

The skill page lists every version. Compare on a version opens a line-by-line diff against the version before it — SKILL.md, every bundled file, and the manifest — so a reviewer sees exactly what changed between releases.

AI assist and AI review

Two optional helpers use the deployment's AI provider (OpenRouter, or the Vercel AI Gateway):

• AI assist in the skill editor drafts or revises a skill from a prompt. It proposes a change, shows it as a diff against your draft, and edits nothing until you press Apply.
  • Test triggering writes about 16 labelled prompts from your draft and your organisation's other skills (ones that should load it, and near-misses that belong to a sibling), then has a cheaper model play the agent: it picks skills from your catalog, with your draft's description in place, three times per prompt. You get precision, recall, a per-prompt table and a warning when the draft collides with another skill. Improve description sends only the failing training prompts to AI assist and re-runs the held-out validation prompts on the proposal, so you see whether the new description generalises before you apply it. It is simulated routing against your catalog — not a guarantee of how your agent behaves. A run counts as 4 AI assists (3 when re-running after Improve); re-running an unchanged description is free.
  • Scorecard rates activation, clarity, structure and progressive disclosure, each with the criteria and reasons behind it. Hard rules (frontmatter, description length, body over 500 lines, missing referenced files) are checked exactly; the model judges the rest, and a quote it cites is shown only if it is really in your draft. Each failed criterion becomes a suggestion that prefills AI assist with its fix. It counts as 1 AI assist. Neither tool gates a save or a publish.
• AI review runs in the background after each publish: a short summary, risks with quoted evidence, and which of your existing policies look like they should cover the skill. A version that wasn't reviewed (published before reviews were enabled, or past the plan's daily review limit) gets a Review now button. The review is advisory — the gate never reads it, and a suggested policy only becomes a draft when someone ratifies it.

Without a configured provider, both say AI isn't available, and publishing works the same.

The scanner

Every published version is also scanned, deterministically and for free — no AI provider needed. The scanner reads every file in full and flags bundled secrets (AWS, GitHub, OpenAI/Anthropic-style keys, private keys), download-and-execute (curl … | sh, iwr … | iex, Invoke-Expression), base64/hex blobs over 1 KB, zero-width, bidirectional and tag unicode, content hidden behind whitespace padding, and binary or compiled files such as .pyc. The skill page's review card shows its findings next to the model's, plus a What this skill can do summary: the hosts it talks to, the environment variables it reads, the paths it writes, and whether it runs a shell or installs packages. When there's a previous version, the card says what changed.

On each finding, Fix in editor opens the editor with AI assist prefilled to address it, and Dismiss records it as a false positive or an accepted risk. A dismissal carries to later versions of the skill for as long as the finding's evidence is unchanged.

The quality score

When you publish or import, the console shows a 0–100 quality score for the skill. It starts at 100 and deducts for problems found in SKILL.md: a missing or malformed frontmatter, a missing name or description, a name that isn't lowercase-kebab or is too long, or empty instructions. Failures cost more than warnings. The score is advisory — it nudges you toward discoverable, well-formed skills; it doesn't block publishing.

Next