> ## Documentation Index > Fetch the complete documentation index at: https://docs.decimal.ai/llms.txt > Use this file to discover all available pages before exploring further. # Skills commands > Every decimalai skills command: search, add, install, update, remove, status, verify, migrate and pull for registry skills on disk; list, sync, scan, review, benchmark and push for the skills you write. Every `decimalai skills` command, with its flags and exit codes. For the workflows, read [Skills on disk](https://docs.decimal.ai/guides/skills-on-disk.md) and [Authoring Skills](https://docs.decimal.ai/guides/authoring-skills.md). | 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-you-author). | ## Skills on disk Registry skills installed into a project like packages. [Skills on disk](https://docs.decimal.ai/guides/skills-on-disk.md) 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. ```bash theme={null} 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`. ```bash theme={null} 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](https://docs.decimal.ai/guides/skills-on-disk.md#in-a-connected-project): * **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//` 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](https://docs.decimal.ai/guides/skills-on-disk.md#install-names), and the [trust gate](https://docs.decimal.ai/guides/skills-on-disk.md#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. ```bash theme={null} 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///` 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. ```bash theme={null} 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///` 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. ```bash theme={null} 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///`. | 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. ```bash theme={null} 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`](#decimalai-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. ```bash theme={null} 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-` | | 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//`, nothing is deleted, and a second run does nothing. The full procedure: [Migrations](https://docs.decimal.ai/migrations.md#upgrading-the-sdk-skills-on-disk). ```bash theme={null} 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-add). ```bash theme={null} 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//`. | | `--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 ` and `decimalai skills install ` (with their `--agent`, `--scope` and `--out` flags) were removed, along with the SDK methods that wrapped them. Use `decimalai skills add `; [Migrations](https://docs.decimal.ai/migrations.md) 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](https://docs.decimal.ai/sdk/cli.md#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. ```bash theme={null} decimalai skills list --limit 50 ``` ### `decimalai skills sync` Sync the `SKILL.md` files you wrote with your organization on DecimalAI. [The guide](https://docs.decimal.ai/guides/authoring-skills.md#put-a-skill-you-wrote-on-decimalai) compares it with the other ways in. ```bash theme={null} 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-