Skills commands

Every decimalai skills command, with its flags and exit codes. For the workflows, read Skills on disk and Authoring Skills.

Command	What it does
`skills search`	Find a skill in the public registry: no key.
`skills add`	Add a skill: listed in `.decimal/skills.toml`, written to `.agents/skills/`, locked.
`skills install`	Make the folders and the lock match the manifest; `--frozen` installs exactly what the lock records.
`skills update`	Move skills to newer versions.
`skills remove`	Take a skill off the project’s list.
`skills status`	Compare folders with the lock, and your own skills with the platform.
`skills verify`	Check folders the way native skill loaders read them.
`skills migrate`	Move a project off a version 1 or npx lock.
`skills pull`	Copy a public skill to disk: no key, no lock.
`skills list`, `sync`, `scan`, `review`, `benchmark`, `push`	Upload, safety-check and measure your own skills.

Skills on disk

Registry skills installed into a project like packages. Skills on disk explains the files. The commands in this section share these options, so their own tables leave them out:

Option	Default	Description
`--directory DIR`	the project of the working directory	The project root: the nearest folder holding the manifest or the lock, then any `.decimal/`, then the repository root. It never goes above the repository or your home directory. Not on `search` and `pull`.
`--api-key`	`$DECIMAL_API_KEY`	Without a key, only public skills are available, fetched anonymously. Not on `search`, `remove`, `verify` and `pull`.
`--base-url`	`$DECIMAL_BASE_URL`, else `https://api.decimal.ai`	The registry. The key is only ever sent here, never to the base URL a committed lock records. Not on `remove` and `verify`.
`--yes`, `-y`	off	On `add`, `install` and `update`: accept a skill whose safety review has not cleared it (Caution, not yet reviewed). On a terminal you are asked instead; without one, such a skill is refused unless `--yes`.

Exit codes are the same for each of these commands, and stable across releases. decimalai skills --help prints the same table.

Code	Meaning
0	OK
1	`status --check` or `verify` found problems; an interrupted run left a folder that matches neither its old nor its new state; another `decimalai skills` run holds the project (`.decimal/.skills.lck`) for more than 30 seconds; the filesystem refused a write
2	Usage error
3	The manifest or lock is missing or unreadable, or the lock is a version 1 or npx lock (run `skills migrate`)
4	`install --frozen`: the lock is out of date with `.decimal/skills.toml`
5	Local edits, a folder the lock does not list, or a symlink block the operation (`--force` overrides the first two, never a symlink)
6	Integrity: served bytes differ from the declared or locked hashes, or `lock_hash` does not recompute
7	Unavailable: not found, ambiguous, withheld, blocked, version unsafe, no access, name taken, already installed under another name, not in this project, not confirmed (`--yes`), the rendering is gone or invalid, or the registry has no install routes
8	Network failure (a spent quota included), or `--offline` needed a fetch

`decimalai skills search`

Find a skill in the public registry: no signup, no API key. Each result says how an agent did with the skill and without it, the same sentence the skill’s page leads with, and gives the command that adds it. A Blocked skill is named apart, with no such command.

decimalai skills search browser automation
decimalai skills search pdf --limit 25
decimalai skills search pdf --json                   # the registry's answer

Argument / Option	Default	Description
`QUERY`	(required)	What your agent does, in one or more words.
`--limit`	10	How many skills to show, from 1 to 100.
`--json`	off	Print the registry’s answer as JSON.

A skill tested before August 2026 shows no count, because results were counted differently then. Its page has the detail. It always reads anonymously, even with DECIMAL_API_KEY set. No results is not an error: it exits 0 and suggests what to try. Exit 8 means the registry could not be reached or did not answer.

`decimalai skills add`

Add a skill: one from the registry, or one you wrote in .agents/skills.

decimalai skills add acme/refund-policy           # follow the newest version ("latest")
decimalai skills add acme/refund-policy@3         # pin version 3
decimalai skills add pdf --yes                    # accept a Caution skill without a terminal
decimalai skills add refund-tone                  # a skill you wrote: .agents/skills/refund-tone/SKILL.md
decimalai skills add pdf --to-agent support       # straight onto agent "support" on DecimalAI

Where the skill goes depends on whether the project is connected:

Not connected: on the project’s list, .decimal/skills.toml. A registry skill is also installed and locked. A skill you wrote is listed under [authored].
Connected (.decimal/link.toml exists), or with --to-agent: on the agent on DecimalAI. A registry skill is assigned to it, and a skill you wrote is uploaded to your organization, not published, and added. .decimal/skills.toml doesn’t change. It needs an API key.

Argument / Option	Description
`REF`	A registry name, url_slug, install name or skill id, optionally with `@N` (pin version N) or `@latest`; or the folder name of a skill you wrote. Adding an installed skill with another version changes its version.
`--force`	Replace a folder the lock does not list that already uses the skill’s install name, or a `.agents/.claude-plugin/plugin.json` this tool did not write. Each is copied to `.decimal/backup/<txid>/` first.
`--no-install`	Only record the skill in `.decimal/skills.toml`; `skills install` fetches it later.
`--to-agent NAME`	Add the skill to agent `NAME` on DecimalAI. Required in a project connected for more than one agent; with one, that agent is the default.

The registry chooses the install name, and the trust gate decides what is installed, refused or asked about. Tools dropped from allowed-tools, and attachments the registry cannot serve, are printed. A new skill’s output ends with how to try it: a question to ask your agent, which names the skill, and where to ask it. When DecimalAI wrote a test that a model failed without the skill and passed with it, the question comes from that test.

`decimalai skills install`

Make .agents/skills match the manifest and the lock. New manifest entries are resolved and installed, entries it no longer lists are removed, and missing folders are fetched at their locked version. It never moves a version: that is update. Folders the lock does not list are never touched.

decimalai skills install                     # after editing .decimal/skills.toml, or on a fresh clone
decimalai skills install --frozen            # in CI, or a Dockerfile
decimalai skills install --frozen --offline  # the root is committed: fetch nothing

Option	Description
`--frozen`	Install exactly what `.decimal/skills.lock` records. Nothing is resolved, neither file is written, and the lock must agree with the manifest (exit 4). A missing folder is fetched by its lock entry and every byte is checked (exit 6). It never asks a question.
`--offline`	Fail with exit 8 instead of fetching a missing folder.
`--force`	Restore folders with local edits to their locked files, each copied to `.decimal/backup/<txid>/<install-name>/` first. Without it, such a folder is left alone with a warning, or stops `--frozen` (exit 5).

`decimalai skills update`

Move skills to newer versions. Each changed folder is replaced whole, and folder names never change. If any skill cannot be updated, none is.

decimalai skills update                         # every "latest" entry; pinned entries stay
decimalai skills update acme-refund-policy@4    # change that skill's version to 4
decimalai skills update acme-refund-policy      # pinned: refresh its files at the same version
decimalai skills update --dry-run --json        # the plan, for a script

Argument / Option	Description
`NAME`	The install name or the registry name. `NAME@N` or `NAME@latest` changes the manifest’s version for it. `NAME` alone updates a `latest` entry, or refreshes an exact pin at the same version. With no `NAME`, entries added to or removed from the manifest are reconciled too.
`--force`	Replace folders with local edits; each is copied to `.decimal/backup/<txid>/<install-name>/` first, and the path is printed.
`--dry-run`	Say what would change and change nothing. Reaches the registry to resolve, fetches no files.
`--json`	Print the result as JSON.

`decimalai skills remove`

Take a skill off the project’s list. A registry skill’s folder goes too, with its manifest and lock entries; a skill you wrote (listed under [authored]) keeps its folder.

decimalai skills remove acme-refund-policy

Argument / Option	Description
`NAME`	The install name or the registry name, or the folder name of a skill you wrote.
`--force`	Remove a folder with local edits too, after copying it to `.decimal/backup/<txid>/<install-name>/`.

No network call is made, and nothing changes on the registry. In a project connected to DecimalAI, its agents keep the skill: remove it from an agent in the dashboard. A name the project does not list exits 7.

`decimalai skills status`

Show the installed skills, and how the skills you author compare with the platform.

decimalai skills status
decimalai skills status --remote --check   # in CI: exit 1 when anything drifted
decimalai skills status ./agents/skills    # only the authored skills in that folder

  Installed skills (.agents/skills in /home/me/support-bot):
    ✓ acme-refund-policy               acme/refund-policy v3 (latest)           clean  [outdated (v3 -> v4)]
    ✗ pdf-tools                        pdf-tools v1 (pinned)                    modified: SKILL.md

Argument / Option	Description
`SKILLS_DIR`	Print only the authored section, for that folder. Cannot be combined with `--remote`, `--check`, `--json` or `--directory`.
`--remote`	Also ask the registry: outdated versions, descriptions or renderings changed upstream, revoked versions.
`--check`	Exit 1 when anything has drifted: a modified, missing or interrupted folder, a manifest that disagrees with the lock, a version 1 lock, a lock git ignores, an authored skill that is `local_ahead`, `remote_ahead` or `conflict`, and with `--remote` everything it reports. Exit 8 when the authored check could not reach the platform.
`--json`	Print the installed section as JSON.

Installed section. Each folder of .agents/skills against the lock: clean, modified, missing (locked, not on disk), unmanaged (not in the lock), illegal (a symlink or a file), interrupted. Authored section. When ./skills exists and an API key is set, each SKILL.md there against this checkout’s last skills sync: in_sync, local_ahead, remote_ahead, conflict, local_only. Drift changes the exit code only with --check; a refusal, such as a network failure under --remote, exits with its own code.

`decimalai skills verify`

Check skill folders the way the native skill loaders read them. It only reads: it takes no lock on the project and writes nothing.

decimalai skills verify                   # the project: .agents/skills against the lock
decimalai skills verify ./skills --strict # CI for a repository of skills you author

Argument / Option	Description
`PATH`	A skill folder, its `SKILL.md`, or a folder of skill folders. Checked by the rules for unmanaged folders; no lock is read.
`--strict`	Make the rules of scope `sdk` errors in folders the lock does not list, and in `PATH`.
`--json`	Print the findings as JSON.

Without PATH, every folder the lock lists must hold exactly its locked files, and every rule is an error there. Folders the lock does not list are checked like PATH: rules of scope loader (at least one native loader rejects, drops or renames a skill that breaks it) are errors, and rules of scope sdk are warnings. Exit 0 with no errors, 1 with any; 3 when the lock is unreadable or a version 1 lock, or there is neither a lock nor a root; 2 for a PATH that is not a skill folder.

Rule	Scope	Checks
F1	loader	UTF-8; the frontmatter opens and closes with lines that are exactly `---`; a YAML mapping with no duplicate keys
F2	sdk	top-level keys are only `name`, `description`, `license`, `compatibility`, `allowed-tools`, `disable-model-invocation`, `metadata`
F3	loader	`name` is lowercase letters, digits and single hyphens, at most 64 characters, and equals the folder name
F4, F5	loader	`description` is a non-empty string of at most 1,024 characters; `compatibility` is a string of at most 500
F6a	loader	`allowed-tools` is one string, not a list
F6b	sdk	`allowed-tools` has no bare `Bash` (`Bash`, `Bash()` or `Bash(:*)`)
F7	sdk	`disable-model-invocation` is absent or exactly `true`
F8, F9, F10	loader	`metadata` is a flat map of strings; `license` is a string; the body is not empty
F11, F12	sdk	managed: the `decimalai-*` metadata keys and the body’s sha256 equal the lock
F13	sdk	managed: LF line endings, and exactly one final newline
F14	sdk	an attachment path is relative and under `scripts/`, `references/`, `templates/` or `assets/`
F15	loader	no file or folder named `SKILL.md`, in any case, below the skill’s own
V1	loader	no symlink in the skills tree, `.agents/` or `.decimal/`
V2	loader	each skill is a real folder directly in the root, holding its `SKILL.md`; the managed root holds nothing else
V3, V4	sdk	managed: exactly the files the lock lists, with its sha256 and exec bits (POSIX)
V5	loader	`.agents/.claude-plugin/plugin.json` names the plugin `decimalai-skills` at version `lock-<first 12 hex of lock_hash>`
V6, V7	sdk	`lock_hash` recomputes, no entries from an older decimalai, and `.decimal/skills.toml` agrees with the lock
V8	sdk	a folder whose `SKILL.md` carries `metadata.decimalai-skill-id` is in the lock
V9	sdk	no interrupted run: `.decimal/skills.lock.journal` is absent

In an unmanaged folder, F11-F13, V3 and V4 do not apply, and F14 reports only an unsafe path. Each finding prints its rule, the file and a fix.

`decimalai skills migrate`

Move a project from a version 1 lock or an npx lock to the manifest and a version 2 lock. Every entry is installed fresh from the registry. Old folders inside .agents/skills and the old locks move to .decimal/migrated-v1/<txid>/, nothing is deleted, and a second run does nothing. The full procedure: Migrations.

decimalai skills migrate
decimalai skills migrate --yes

--yes migrates the entries that resolve even when others do not. Without it, an entry that does not resolve stops the migration (exit 7) before anything changes.

`decimalai skills pull`

Copy a public registry skill to disk: no signup, no API key. It writes the registry’s own files into a folder named by the skill’s install name. It is a loose copy: nothing locks it and nothing updates it. To manage a skill, use skills add.

decimalai skills pull playwright-cli                 # ./playwright-cli/SKILL.md
decimalai skills pull pdf --out ~/.claude/skills     # a personal Claude Code skill
decimalai skills pull pdf --stdout                   # print SKILL.md

Argument / Option	Default	Description
`REF`	(required)	A public skill’s url_slug, registry name or id.
`--out`	the current directory	Write the skill to `OUT/<install-name>/`.
`--stdout`	off	Print `SKILL.md` instead of writing anything.
`--no-evals`	off	Skip the skill’s `eval.yaml` test suite (written beside `SKILL.md` when the skill has one).
`--force`	off	Overwrite a folder that holds different files. Files that are not part of the skill are left in place.

It always fetches anonymously, even with DECIMAL_API_KEY set. A Blocked or Withheld skill is refused (exit 7); a Caution or not-yet-reviewed one is written without a question.
A folder that already holds different files is left alone (exit 5) unless --force. A symlink in the way, or a target inside the .agents/skills of a project with a manifest or a lock, is always refused (exit 5).

Removed skills commands

The old verbs decimalai skills export <ref> and decimalai skills install <ref> (with their --agent, --scope and --out flags) were removed, along with the SDK methods that wrapped them. Use decimalai skills add <ref>; Migrations lists what replaces each one. SkillRouter.export(), update_skills() and status() run skills add, skills update and skills status through the same engine.

Skills you author

list, sync, review, benchmark and push also take --api-key and --base-url (Global options). scan takes neither.

`decimalai skills list`

List the skills in your workspace, with each one’s latest version. --limit caps the results, 50 by default.

decimalai skills list --limit 50

`decimalai skills sync`

Sync the SKILL.md files you wrote with your organization on DecimalAI. The guide compares it with the other ways in.

decimalai skills sync                 # ./skills, and the skills .decimal/skills.toml lists under [authored]
decimalai skills sync ./agents/skills
decimalai skills sync .claude/skills --to-agent support-agent   # and put them on support-agent

Argument / Option	Default	Description
`SKILLS_DIR`	`./skills` and the listed skills you wrote	Sync every `SKILL.md` under this folder instead.
`--dry-run`	off	Walk and hash but send nothing: lists what it found, and which agents new skills would reach.
`--to-agent NAME`	none	Add the synced skills to this agent (made if it doesn’t exist yet), except any someone removed from it there.
`--offer-scope`	`restricted`	Which agents get a skill this sync creates: `restricted`, only the agents you add it to; `workspace`, every agent. Existing skills keep theirs.
`--apply-pulls` / `--no-apply-pulls`	`--apply-pulls`	Write DecimalAI’s newer copies back to disk.

Each skill’s instructions are compared with DecimalAI’s copy and with what this checkout last synced:

Only your file changed: it is uploaded as a new version.
Only DecimalAI’s copy changed (an edit in the dashboard, or another checkout’s sync): it is written into your file.
Both changed: DecimalAI’s copy wins. Your file is copied to .decimal/backup/sync-<time>/<name>/SKILL.md first, and the line for it says where. To upload your version instead, copy it back and sync again.

An eval.yaml beside a SKILL.md is uploaded too, and so are text files one level under references/, scripts/, templates/ and assets/ (50 files, 500 KB each). A per-skill error is listed as failed, and the rest of the batch still syncs. A folder installed from the registry, whose SKILL.md carries metadata.decimalai-skill-id, is skipped and named in the output.

`decimalai skills scan`

Run the static safety scan on your SKILL.md files: free, with no API key and no network. Scan before you publish explains what a clean scan does and doesn’t promise, and has a GitHub Actions job.

decimalai skills scan                                       # every SKILL.md under ./skills
decimalai skills scan ./myskill/SKILL.md
decimalai skills scan ./skills --format github --fail-on blocked   # in CI

Argument / Option	Default	Description
`SKILLS_DIR`	`./skills`	A `SKILL.md`, a skill folder, or a tree of them.
`--format`	`text`	`text`, `json`, `github` (annotations for a pull request) or `sarif`.
`--fail-on`	`blocked`	Exit 1 when any skill reaches this status: `blocked`, `flagged` (the Caution band, or worse) or `never`.

Exit 0 when nothing reached --fail-on; 1 when a skill did, or the path holds no SKILL.md; 2 for a usage error.

`decimalai skills review`

Run the full safety review on a skill you already synced, on DecimalAI, to find a rejection before you publish. Each review counts against your plan’s deep-review quota. Deep review has the quotas and what a verdict does.

decimalai skills sync                # send ./skills to your organization, unpublished
decimalai skills review my-skill

It takes the skill’s name, and prints the band, each tier’s status and any findings. Exit 1 when the band is Blocked or the request fails.

`decimalai skills benchmark`

Run a skill’s eval suite on DecimalAI’s runner, each case with the skill and without it, and print the difference. This is a verified run: it counts against your plan’s monthly case quota and feeds the skill’s registry numbers. To iterate for free on your own key, use the local runner and skills push.

decimalai skills benchmark ./skills/gdpr-pii-classifier
decimalai skills benchmark ./skills/gdpr-pii-classifier --model gpt-4o-mini
decimalai skills benchmark ./skills/gdpr-pii-classifier --runs 3

Argument / Option	Default	Description
`SKILL_DIR`	(required)	A folder holding `SKILL.md`, and `eval.yaml` when the skill has one.
`--model MODEL`	the platform’s configured model	The model to test against: one that `GET /api/v1/models` lists, or a Gemini Flash or Flash-Lite text model.
`--runs N`	1	Run the whole suite N times, 1 to 10, and average by mean. `eval.yaml` isn’t changed.

It first uploads the folder’s SKILL.md and eval.yaml, and your local copy wins. An eval.yaml that doesn’t parse stops the command. If the upload fails, the run warns and uses the copy already on DecimalAI. A skill created this way is on no agent until you add it. Exit 1 when the run couldn’t start or finish, which includes being over quota. A run that finishes exits 0 whatever its verdict.

`decimalai skills push`

Attach the results.json of a local skillevaluation run to a skill on DecimalAI. It’s a JSON upload, so it’s free and uses no quota. The run shows on the skill’s Benchmark tab tagged unverified and never feeds registry rankings.

skillevaluation run ./skills/gdpr-pii-classifier --model claude-haiku-4-5
decimalai skills push results.json

Argument / Option	Default	Description
`RESULTS_FILE`	(required)	The `results.json` the local runner wrote.
`--skill`	`skill.name` in the results file	The skill to attach the run to.

The skill has to exist on DecimalAI, so run skills sync first. Otherwise, or when the results document is rejected, it exits 1 and says why. A pushed case with no matching case on DecimalAI is skipped and named in the output.

Python SDK

Skills in your repo

CLI

REST

Skills on disk

`decimalai skills search`

`decimalai skills add`

`decimalai skills install`

`decimalai skills update`

`decimalai skills remove`

`decimalai skills status`

`decimalai skills verify`

`decimalai skills migrate`

`decimalai skills pull`

Removed skills commands

Skills you author

`decimalai skills list`

`decimalai skills sync`

`decimalai skills scan`

`decimalai skills review`

`decimalai skills benchmark`

`decimalai skills push`

​Skills on disk

​decimalai skills search

​decimalai skills add

​decimalai skills install

​decimalai skills update

​decimalai skills remove

​decimalai skills status

​decimalai skills verify

​decimalai skills migrate

​decimalai skills pull

​Removed skills commands

​Skills you author

​decimalai skills list

​decimalai skills sync

​decimalai skills scan

​decimalai skills review

​decimalai skills benchmark

​decimalai skills push

Skills on disk

`decimalai skills search`

`decimalai skills add`

`decimalai skills install`

`decimalai skills update`

`decimalai skills remove`

`decimalai skills status`

`decimalai skills verify`

`decimalai skills migrate`

`decimalai skills pull`

Removed skills commands

Skills you author

`decimalai skills list`

`decimalai skills sync`

`decimalai skills scan`

`decimalai skills review`

`decimalai skills benchmark`

`decimalai skills push`