Spec packages: install and publish

What a spec package is

A spec package is a versioned package with a name like my-org/toolkit: an org, a slash, then a name. It holds one or more of four things:

• A spec says what software should do, in numbered rules written in GEARS, plain English of the form “when this happens, the system shall do that”.
• A skill is an Agent Skills folder: a SKILL.md file of instructions that an agent loads when a task needs it.
• A playbook is a workflow written in plain language, which Spex compiles so that AI agents can carry it out together.
• An applet is a small web page that the IDE shows beside your project.

You install packages from Spex Space, and you publish your own to it. Both work in the Spex IDE, or with the Spex CLI, its command-line tool.

Claude Code reads skills from .claude/skills/. Codex, Gemini CLI, Kimi Code and OpenCode read them from .agents/skills/.

Install a package

1. Open Spex, and open your project.
2. Open Playbooks, and select your project's side.
3. Choose Add from registry, and search for the package.
4. Pick a version, then choose Add.

Spex does the rest. It works out the exact version to use. It installs the files. It copies the skills into the folders your agents read.

Public packages need no account. Private packages never show up in search. To add one, sign in first (see Before you publish). Then choose Add from registry → Add by name. Enter the package's org/name and a version, such as 1.2.3, ^1.2.3 or ~1.2.3 (see Versions and fixes). Then choose Add.

Use it

• A playbook needs one more step. Find it under Not enabled. For every role, pick a player: the agent that plays that role. Choose Enable. Then start a new task and type / to find its command.
• A skill or a spec needs nothing more. Your agent finds it by itself when a task needs it.
• An applet shows as a tab in your project, named after the applet.

Or use the CLI

The Spex CLI does the same from a terminal. Install it with npm install -g @sublang/spex; it needs Node.js 22 or later. Keep Spex running: the CLI finds the running app on this computer by itself. Run the commands in your project's folder:

spex package search toolkit
spex package add my-org/toolkit --version '^1.0.0'
spex package status

search finds public packages. add adds a package to your project and installs it. status shows what your project has installed. Put your own package names in place of the examples.

If a command loses its connection, the work may still finish. Check with spex package status before you try again.

Publish a playbook you made in Spex

First sign in and get an org (see Before you publish).

1. In Playbooks, choose New playbook. Enter a short lowercase id, your Org and a License.
2. Describe the workflow in the conversation: what it does, who does what, and when it is done.
3. Choose Compile. Spex turns your words into a workflow the agents can run.
4. On the Enable tab, pick a player for each role and enable the playbook. Try its command in a new task.
5. Back on the Enable tab, choose Publish. Check where it will go, its name, its version and its files. Then confirm Publish.

Spex keeps the playbook's package in spex-packages/<id>/ in your project. Commit that folder with your code. Publishing uploads only the package's own files from that folder: its meta.yaml, README.md and LICENSE, and the folders its meta.yaml names. The rest of your project is not uploaded.

Publish a skill or a spec you already have

A skill you wrote in Claude Code lives in .claude/skills/<name>/. A spec of your project lives in specs/packages/<name>.md. Neither is a package yet. One command makes a package folder from it.

1. Make the package folder

For a skill, run this in your project's folder:

npx @sublang/spex package init my-org/my-skill --skill .claude/skills/my-skill --move

This makes the folder spex-packages/my-skill/. It holds the skill, a README.md, your project's LICENSE if it has one, and a meta.yaml. The meta.yaml describes the package: its name, version, description, license and contents. The version starts at 0.1.0. Edit meta.yaml if you want another description or license.

--move moves the skill into the package, so it leaves .claude/skills/. Once you add the package in step 2, Spex puts the skill back there from the package. Leave out --move to copy the skill instead. Your own copy then stays in .claude/skills/, and Spex leaves it alone: it does not put the package's skill over it.

For a spec, run:

npx @sublang/spex package init my-org/my-pkg --spec specs/packages/my-pkg.md

The package's name must be the spec file's name: my-pkg.md goes in my-org/my-pkg. That is because the spec's rules are named after the file, such as my-pkg-1. A spec is always copied, never moved. To put several skills and a spec in one package, give --skill once for each skill, and --spec too.

npx @sublang/spex runs the CLI without installing it. With the CLI installed, spex package init is the same command. init only writes files in your project. It needs no sign-in, and Spex need not be running. It changes nothing on Spex Space.

2. Add it, then publish it

In the IDE, open Playbooks and choose Add from folder. Enter my-org/my-skill and the folder spex-packages/my-skill, then choose Add. Choose Publish on the package's row. Check where it will go, its name, its version and its files. Then confirm Publish.

Or use the CLI, with Spex running:

spex package add my-org/my-skill --path spex-packages/my-skill
spex package publish spex-packages/my-skill --dry-run
spex package publish spex-packages/my-skill

add --path uses the folder in your project as the package. --dry-run shows where the package will go, its name, its version and its files, and uploads nothing. The last command publishes the package and shows what it published.

Publishing needs a sign-in and an org (see Before you publish).

Add an applet

An applet is a small static web page inside a package. Its folder is applets/<id>/, and its entry page is index.html in that folder. Its scripts, styles and images sit beside it. Spex builds nothing and runs nothing for it: the IDE shows the files as they are.

Once the package is installed, your project shows a tab named <id> with the page in it. The page can read your project's folder, but it cannot change it:

• ./~/<path> reads one file of your project, such as ./~/README.md.
• ./~/<folder>/, with the slash at the end, lists a folder as JSON: { entries: [{ name, kind, size, modified }] }. kind is file or folder. modified is when it last changed, in milliseconds since 1970.

So a playbook can write a report into your project, and an applet can show it.

The page runs in a sandbox. It cannot reach the network or other sites. It cannot reach the IDE either, and it keeps nothing in the browser.

Here is a tiny applets/report/index.html:

<!doctype html>
<meta charset="utf-8">
<title>Report</title>
<h1>Latest report</h1>
<pre id="out">Loading…</pre>
<script>
  const out = document.getElementById('out');
  fetch('./~/reports/latest.json')
    .then((r) => (r.ok ? r.json() : Promise.reject(r.status)))
    .then((report) => { out.textContent = JSON.stringify(report, null, 2); })
    .catch(() => { out.textContent = 'No report yet.'; });
</script>

Declare the applet in the package's meta.yaml, beside the playbook that writes the report. An applet has no language:

artifacts:
  weekly-report: { kind: playbook, language: en }
  report: { kind: applet }

spex package init does not add applets. Add the applets/<id>/ folder to the package folder by hand, and add its line to meta.yaml by hand. Spex refuses an applet folder that has no index.html at its top. Then publish the package as usual.

Applet tabs show for projects on this computer. A project on a team server shows none yet.

Before you publish: sign in and an org

Installing a public package needs no account. Publishing does, and so does installing a private package.

Sign in through Space in the IDE. Spex Space has no passwords: you sign in with an account you already have elsewhere. You can also sign in from the CLI, while Spex is running:

spex auth login --instance https://spex.sublang.xyz
spex auth status

Follow the sign-in steps it shows.

If your team uses a Space at another address, add it in the IDE under Space → Add instance… and sign in there; the CLI takes that address after --instance.

To publish, you need an org: the first part of org/name. Claim one on Your orgs. Your personal namespace, the one named after your login, does not count as an org.

No group of your own to claim? Open Space in the IDE and choose New group. Give it a name and a lowercase path, such as team-tools. Then claim that path on Your orgs. If New group is not offered, ask the people who run this Space for a top-level group that you own.

For private packages, choose Private when you claim the org. Then only the org's members can see its packages. To install one, a member signs in and uses Add by name.

Versions and fixes

A published version never changes. To fix or change anything, raise version in meta.yaml, such as from 0.1.0 to 0.1.1. Then publish again.

If publishing says the version already exists, raise the version and publish again. A version number is never used twice.

• 1.2.3 means exactly that version.
• ^1.2.3 means that version or any later one before 2.0.0; ^0.1.0 stops before 0.2.0.
• ~1.2.3 means that version or any later one before 1.3.0.

To keep new installs off a bad version, yank it through the HTTP API in the agent guide. A yanked version is never picked for ^ or ~. It can still be installed by its exact version.

More

• The full Spex guide: install the IDE and try a first task.
• The CLI guide: every command and its options.
• The agent guide: the package format, and publishing over HTTP for scripts and agents.
• The rules for writing specs.

Spex can also keep your project's records, its specs, decisions and agent sessions, in a group shared with its members; you find your groups on the Groups page. This is optional: read the sharing notice in Spex first, because group members can see the records, including session attachments.