decimalai skills installs registry skills into your project as ordinary folders, .agents/skills/<install-name>/, the layout every native skill loader reads. It works like a package manager. .decimal/skills.toml lists what the project wants, .decimal/skills.lock records the exact bytes written, and decimalai skills install --frozen reproduces those bytes in CI or Docker, or refuses with an exit code that says why.
In a connected project
Whatskills add does depends on that one file:
If
link.toml lists more than one agent, pass --to-agent <name>. --to-agent also does this in a project with no link.toml. skills remove still changes only the project: the agent keeps the skill until you remove it on the agent’s page.
The rest of this page is about files. skills install, update, status and verify work on skills.toml and its lock in either kind of project, and the Python call skillpkg.add() always writes files. Why a project connects: Without a DecimalAI key.
Quick start
DECIMAL_API_KEY, only public skills are available. decimalai.skills_dir() returns the absolute path of .agents/skills, and Native skill loaders has each framework’s one line. Claude Code loads the whole root as a plugin:
.decimal/skills.toml, .decimal/skills.lock and .agents/. CI and Docker run decimalai skills install --frozen.
What skills add writes
.git. It’s the nearest folder holding .decimal/skills.toml or .decimal/skills.lock, else the nearest with any .decimal/, else the repository root. --directory DIR names it instead. The root is always .agents/skills.
.agents/skills/<install-name>/
The registry’s own files for one version of the skill, byte for byte: SKILL.md plus its scripts/, references/, templates/ and assets/. Scripts the skill marks executable get mode 0755, everything else 0644. SKILL.md carries the skill’s identity stamp.
allowed-toolsdepends on who wrote the skill. Claude Code pre-approves every tool a skill lists, so a skill your organization didn’t author keeps onlyRead,GrepandGlob. One it authored keeps its list, except that a bareBashbecomes one scoped entry per bundled script. Each change is printed at install.- Binary attachments aren’t installed. The registry stores text only. A file it can’t serve is named in a warning and recorded in the lock as
unavailable.
.decimal/skills.toml
decimalai skills install afterwards. A value under [skills] is "latest" or a version number written as a string, with no ranges. decimalai skills add my-own-skill writes the [authored] line. A folder it doesn’t list stays off your agents’ list, because Cursor and other tools read that folder too.
.decimal/skills.lock
One entry per installed skill, keyed by install name: its registry name, ids and version, the SHA-256 of every file as written, and the exact rendering. lock_hash covers every entry except installed_at, so two machines that install the same lock agree. Don’t edit it by hand: a frozen install refuses a lock_hash that doesn’t recompute (exit 6). Your API key only ever goes to the registry you configure, never to a URL in a committed lock.
.agents/.claude-plugin/plugin.json
It makes .agents a Claude Code plugin named decimalai-skills, so its skills are listed as decimalai-skills:<install-name>. The engine won’t overwrite one it didn’t write unless you pass --force, which backs it up first.
Install names
The install name is the folder name and thename: in SKILL.md. The registry chooses it from the names your project already uses:
The name is lowercased, accents are dropped, and every other run of characters becomes one
-. A hash of the skill’s id is added when that name is taken in this project or unusable: empty, over 64 characters, reserved (install, search, check, decimalai-skills), a name that lost non-Latin characters, or a word YAML reads as something other than text (404, yes, a date).
An installed skill keeps its folder name for good, through upstream renames. Only remove followed by add picks up a new one.
Versions: latest or exact
skills install never moves a version. skills update moves every latest entry and leaves exact pins alone, and --dry-run says what it would change. Each changed folder is replaced whole, and if one skill can’t be updated, none is. For another organization’s skill, latest installs the newest version that passed its safety scan, and asking for a failed one is refused (exit 7). More: Update, pin or fork.
Commands
Every command and flag is in the CLI reference. The same engine is a Python API.
The trust gate
Every skill passes the registry’s safety review before it’s written.
Skills your organization owns are never asked about. The question comes once per version, and
install --frozen never asks. If the registry later blocks a locked version, a frozen install that has to fetch it refuses. One over a committed root fetches nothing, so it can’t notice: skills status --remote reports the version as revoked.
Commit the root, or gitignore it
Commit it (the default). A fresh clone works with no install step, code review shows which skill text changed, and in CIinstall --frozen re-checks every byte and fetches nothing.
Or gitignore the root. Add .agents/skills/ and .agents/.claude-plugin/ to your .gitignore and commit only the two .decimal/ files. Every checkout then runs install --frozen, which fetches each missing folder and checks every byte. Skills you wrote in .agents/skills/ would be ignored too.
CI
install --frozen exits 4 when someone edited skills.toml without running skills install, and 5 when a committed folder no longer matches the lock. With a committed root, add --offline to fail (exit 8) rather than fetch. A scheduled job can run decimalai skills status --remote --check, which exits 1 when a skill has drifted.
Docker
With the root committed,RUN decimalai skills install --frozen --offline needs no network and no key. With it gitignored, fetch at build time, passing any key as a build secret so it never lands in an image layer:
docker build --secret id=decimal_api_key,env=DECIMAL_API_KEY ., using a key of the organization that wrote the lock.
Local edits, --force and backups
When a file in a managed folder differs from the lock, status shows it as modified, and a command that would replace it stops with exit 5. To keep your edits, copy the folder to a new name: the engine never touches a folder the lock doesn’t list. To discard them, re-run with --force, which first copies the folder to .decimal/backup/<txid>/<install-name>/ and prints that path. It never overrides a symlink, or a file where a skill folder belongs.
Commands fetch and check everything first, then swap whole folders, so a crash leaves each folder as it was or as it should be, and the next command finishes the change. A second command in the same project waits up to 30 seconds, then exits 1.
status and verify
skills status changes nothing. Each folder is clean, modified, missing (locked, not on disk), unmanaged (the lock doesn’t list it, as with a skill you wrote) or illegal (a symlink or a file). --remote also reports outdated and revoked skills, and --check makes it exit 1 on drift.
skills verify catches what a loader would drop without an error, which usually shows up in production as a skill that’s never used. Managed folders must hold exactly their locked files, hashes and exec bits. Your own folders, and any tree you name with skills verify PATH, are checked by the format’s rules, with warnings becoming errors under --strict.
Exit codes
Stable across releases, so CI and Dockerfiles can branch on them.After skills update
Restart the agent process. A loader that has already read a skill can keep serving the old version: which ones do.
How usage is counted
Fetching a skill for disk is an install, not a delivery. Fetches are counted per day, and never as the skill being served to a model. A loader reports a skill by its folder name, bydecimalai-skills:<install-name> or by its path. Before the SDK sends a run, it looks those names up in the project’s lock and adds the skill’s registry ids and body hash. A folder with local edits is reported with no version id, so it’s never credited to the registry version. With no DecimalAI adapter, report a load yourself.
Upgrading from an older SDK
A project with an older lock is refused until you rundecimalai skills migrate once. It installs each skill fresh from the registry and writes skills.toml, a current lock and plugin.json, and nothing is deleted. Upgrade everyone on the project together. Step by step: Migrations.
What changed in the files
Aftermigrate, a project’s files follow this page: one root, the install name as both folder and name:, identity under metadata, allowed-tools and compatibility as single strings, 0755 scripts, a lock with every file’s SHA-256, and no stale files.