Agent skills
DreamLake skills are written once, in the public
dreamlake-skills repository,
and published as a release: a catalog.json listing every skill and a
skills.tar.gz holding their directories. The dl CLI is the installer.
It carries one skill, dreamlake-cli, embedded for offline use; everything else
is downloaded from the latest release. Manual install is unpacking the same
tarball. Reading a skill needs no install: skill read prints any file of
any catalog skill from the server's registry (or the embedded bundle), with the
revision it came from.
Setup
Run dl init once. It asks which agent you use (Claude Code, Codex,
or both) and where skills should go (this project or your home directory), remembers
both, installs the embedded dreamlake-cli skill without touching the
network, and lists the other skills in the catalog.
With --agent, init runs without prompts and still saves the choice; add
--global to save global scope. Non-interactive or --json usage requires
--agent with claude, codex, all, or a comma-separated list such as
claude,codex. Canceling the guided setup writes nothing,
not even the preference.
The choice is saved as { "agent", "scope" } in
~/.local/state/dreamlake/skill-preferences.json ($XDG_STATE_HOME is
honoured). Several agents are saved as { "agent", "agents", "scope" }:
agents is the list and agent its first entry, so a CLI older than
multi-agent support still reads the file and uses that one agent. Every skill subcommand defaults to it; --agent, --global,
--project and --dir <path> override it for one invocation without changing
it. With nothing saved and no --agent, commands use Claude Code and the
current project and print a one-line hint to run dl init.
Commands
| Command | Reads | Writes | Network |
|---|---|---|---|
init | embedded bundle and catalog snapshot | preference file, dreamlake-cli | never |
skill list | server registry when logged in, else catalog snapshot; install manifests | nothing | when logged in, unless --local; --refresh fetches the release |
skill read <name> [--file <path>] | server registry when logged in, else the embedded bundle | nothing | when logged in, unless --local |
skill install <name...> | latest catalog.json, skills.tar.gz | the named skills and their requires | yes; dreamlake-cli alone works offline |
skill update [name...] | latest catalog.json, skills.tar.gz, manifests | changed, new and retired files | yes; dreamlake-cli alone works offline |
skill remove <name> | the manifest | deletes listed, unedited files | never |
Reading a skill
skill read <name> prints one file of a skill — SKILL.md unless --file <path> names another — so an agent or a script can load a skill without
installing it. skill list shows the same catalog. Both answer from one of
two sources, and every answer names the source and the bundle's tag and commit:
| Source | What it is | Chosen when |
|---|---|---|
remote | the server's read-only skills registry (GET /skills, GET /skills/:skill, GET /skills/:skill/files/*), serving the bundle the server pins | a login is saved, or --remote |
local | the bundle embedded in this CLI — dreamlake-cli and the catalog snapshot — offline | no login, or --local |
--remote without a login is kind: "not-logged-in" with dl login
as the next action; --local with --remote is kind: "invalid-source".
Without a flag, a registry that cannot answer at all — unreachable, 503 skills_unavailable, 503 skills_lock_mismatch, a refused token — falls back
to the embedded bundle with one stderr warning that says why; --remote never
falls back. A refusal about the skill itself (skill_not_found,
skill_file_not_found, skill_path_invalid, skill_file_binary) is
reported as such and the embedded copy is not consulted, because it would
answer a different question. Only dreamlake-cli is embedded: reading
another catalog skill with --local is kind: "not-embedded", and the next
action is the same read with --remote.
When the server's pin is not this CLI's, every remote answer carries one stderr line and nothing else changes:
skill list --json repeats it under registry.mismatch. It is a warning,
never a failure: the bytes are the server's and the version reported is theirs.
The body is the whole of stdout, so skill read pipes; the header goes to
stderr:
A retired name resolves through the catalog's renamed map, and the answer
says so (a renamed: line; renamedFrom in JSON). Paths are relative,
forward-slash, inside the skill: .. is refused with skill_path_invalid
before anything is read, and a file that is not UTF-8 text with
skill_file_binary — the same checks, with the same codes, as the server's.
One contract, three surfaces
The output examples below illustrate the response shape; release versions, commits, hashes and file counts depend on the installed or serving catalog.
dl skill read --json, the TypeScript dl.skills.read({ skill, path })
(TypeScript API) and the built-in agent's
dreamlake_skills_read tool are one operation. All three return tag,
commit, skill, renamedFrom (only when the name was retired), path,
sha256, content, files, filesTotal and filesTruncated, and refuse
with the same codes. The agent tool pages long files (start, end, total,
next, complete) and clips its file index to a budget, setting
filesTruncated when it did; the CLI and the TypeScript API return the whole
file and the whole index, so the paging fields never appear, filesTruncated
is always false and filesTotal equals files.length. The CLI adds
source, status and nextAction:
sha256 is the hash of content; the CLI and the TypeScript API verify it
against the skill's file index (and the file route's ETag) before answering.
The embedded bundle is held to its pin the same way: the manifest the build
wrote beside it indexes every file with its hash, files is that index, and
a bundled file that was edited after the build, or is indexed but gone, is
refused with kind: "skill-file-mismatch" rather than attributed to the
commit it no longer matches; the next action is the same read with
--remote. A file on disk that the manifest never indexed is
skill_file_not_found.
On failure the object is { "status": "error", "error", "kind", "code"?, "nextAction" }. code is the registry's identifier when the refusal is one
it defines; kind is the CLI's:
code | HTTP | kind | Meaning |
|---|---|---|---|
skills_unavailable | 503 | skills-unavailable | the server could not load its bundle |
skills_lock_mismatch | 503 | skills-lock-mismatch | the server's bundle does not match its skills.lock |
skill_not_found | 404 | skill-not-found; not-embedded when --local knows the name but has no copy | no such skill |
skill_file_not_found | 404 | skill-file-not-found | the skill has no such file |
skill_path_invalid | 400 | skill-path-invalid | not a relative path inside the skill |
skill_file_binary | 415 | skill-file-binary | the file is not UTF-8 text |
Kinds without a code are the CLI's own: not-logged-in, invalid-source,
unauthorized (the server refused the saved login), registry-unreachable,
no-bundle, skill-file-mismatch (the embedded copy is not what its manifest
pinned) and read-failed. skill_result_too_large (413) and
skill_range_invalid (400) belong to the paged agent tool only.
Where it goes
| Agent | project (default) | --global |
|---|---|---|
claude | <cwd>/.claude/skills/<name>/ | ~/.claude/skills/<name>/ |
codex | <cwd>/.agents/skills/<name>/ | ~/.agents/skills/<name>/ |
Skill names are lower-case letters, digits and dashes, starting with a letter
(^[a-z][a-z0-9-]*$); anything else is refused with kind: "invalid-name"
before any path is resolved, and a skill is always a direct child of the
skills directory. --project forces the current project when dl init
saved global scope. --dir <path> replaces the project root and overrides --global and
--project, retaining the agent-specific subdirectory. It does not name the
skill directory itself. Codex's supported
skill locations include
.agents/skills.
Requires CLI 0.93.0 or later: --agent all (or claude,codex, or what
init saved) selects both rows of the table: every install, update and remove handles each agent's copy on
its own, with its own manifest, from one catalog and one download. update
with names skips an agent that does not have the skill, and remove skips an
agent where it is absent; a skill absent under every selected agent is still
not-installed. When only one agent's copy conflicts, the suggested --force
command names that agent alone.
Sources and versions
Every result names where each skill came from and which release it is:
- embedded — the
dreamlake-clidirectory built into this CLI, with the release tag it was cut from.installandupdateuse it when the latest catalog carries the same version, and whenever the release cannot be reached. While the CLI pins a commit rather than a tag, the version is that commit and is shown as its first 12 hex digits. - catalog — downloaded from
skills.tar.gzof the latest release. Only the directories you asked for (plusrequires) are unpacked. The release'scatalog.jsonmust name the tarball underassets["skills.tar.gz"].sha256(every release does); the download is hashed before anything is unpacked. A catalog without that record is refused before any download, and a download that does not hash to it is refused before unpacking — both arestatus: "error"withkind: "integrity"and write nothing.
install resolves names through the catalog's renamed map first: an old name
prints the new one and exits with kind: "renamed". Each skill's requires
are installed with it, in one download.
When the release is unreachable, dreamlake-cli still installs from the
embedded copy and the output says the release was not consulted. Any other
skill is an error with kind: "catalog-unreachable" and a nextAction of
kind: "download" naming the tarball address, so you can install by hand:
A hand-unpacked directory has no manifest. skill list reports it as
unmanaged, install never adopts it on its own (identical: exists with
unmanaged: true and the command to adopt; otherwise a conflict), and
install --force or update --force adopts it: the skill's files are
written, a manifest listing only them is written, and your other files are
reported under extra — the manifest never lists a file you did not
explicitly accept, so remove can never delete one.
Versions: never an implicit downgrade
Release tags are vYYYY.MM.DD with an optional .N, and only those are
ordered. Before install or update compares a single file of a skill that
already has a manifest, it orders the candidate's version against the
installed one:
| Installed vs candidate | Result |
|---|---|
| same version string (whatever its form) | compared file by file, as usual |
| candidate newer | compared file by file, as usual |
| candidate older | exists with message: "installed vX is newer than available vY; nothing changed"; the manifest keeps its version |
| not comparable (a commit pin against a tag, an unknown format, a missing version) | error, kind: "version-unknown"; nothing changed; nextAction is the --allow-downgrade command |
--allow-downgrade is the explicit way through both: with it an older
release, or one whose version cannot be ordered against the installed one,
replaces the installed copy and the manifest records the new version.
--force keeps its single meaning — overwrite files you edited — and does not
bypass this guard; the two combine when an edited skill is to be downgraded.
update is the command for changing versions: it compares three ways and
replaces files you did not edit on its own. install onto a managed copy
compares bytes only, so with --allow-downgrade it still reports every
differing file as a conflict until --force is added.
When the release is unreachable, update of a skill whose manifest says
source: "catalog" is error, kind: "catalog-unreachable" — it is never
replaced by the embedded copy. dreamlake-cli installed from the embedded
copy is updated from a newer embedded copy, and left alone (exists, with
the message above) when the embedded copy is older.
Environment overrides
| Variable | Effect |
|---|---|
DREAMLAKE_SKILLS_RELEASE_URL | Release base URL (same layout as GitHub: <base>/latest/download/catalog.json, <base>/download/<tag>/skills.tar.gz), or a file:// URL / filesystem path to a directory holding catalog.json and skills.tar.gz. |
DREAMLAKE_SKILLS_DIR | A local skills/ directory to treat as the embedded bundle (a checkout, for development): dreamlake-cli/ plus the optional side files .manifest.json and catalog.json. An invalid path fails instead of falling back. |
DREAMLAKE_SKILLS_MANIFEST_FILE | JSON { tag, commit, files } describing the bundle in DREAMLAKE_SKILLS_DIR; defaults to <dir>/.manifest.json, else the bundle is unversioned. |
DREAMLAKE_SKILLS_CATALOG_FILE | A catalog.json to use as the embedded snapshot; defaults to <dir>/catalog.json. |
The install manifest
Every install or update writes <skill>/.dreamlake-skill.json:
files maps every path the installer wrote to the sha256 of those bytes.
update and remove trust nothing else: a file whose hash still matches is
the installer's to replace or delete; anything else is yours. Paths are
relative, forward-slash, without ..; a manifest that breaks that rule, or is
a symlink, is rejected when read and the directory is treated as unmanaged.
What is and is not touched
Both .claude/skills/ and .agents/skills/ are shared directories. Yours
probably already holds hand-written skills next to anything you install. The
installer never rm -rfs a directory, never touches .claude/settings.json or
settings.local.json, and never assumes every entry under a skills directory
is a directory.
A skills directory that is itself a symlink (a dotfiles setup that links
~/.claude/skills elsewhere) is followed: the directory is resolved once per
command, every target and path in the output is the resolved one, and
before any write or delete the target is checked to still be a direct child
of that resolved directory. Symlinks inside a skill directory are never
followed: a symlink where a file belongs is a conflict --force does not
override, and a symlinked manifest is rejected.
install
| Target | Behaviour | status | rc |
|---|---|---|---|
| absent | write it and a manifest | installed | 0 |
| present with a manifest, every file byte-identical | refresh the manifest only | exists | 0 |
| present with a manifest, differs | refuse, list the paths, print the --force command | conflict | 1 |
present with a manifest, differs, --force | overwrite only the files that differ | installed | 0 |
| present without a manifest, every file byte-identical, nothing else there | nothing written, no manifest; unmanaged: true, nextAction is skill update <name> --force | exists | 0 |
| present without a manifest, anything missing or different, or other files present | refuse; conflicts lists the missing/differing files, extra the others | conflict (kind: "unmanaged") | 1 |
present without a manifest, --force | write the missing and differing files, write a manifest listing only the skill's files; other files kept under extra | installed (exists when nothing had to be written) | 0 |
| a file or symlink where a file belongs | refuse; --force does not override | conflict | 1 |
| a file where the directory belongs | refuse | error | 1 |
Nothing was written. A skill you edited survives a mistyped install.
update
update compares three things per path — the old manifest's hash, the local
file, and the new release — and never deletes anything the manifest does not
vouch for:
| Old manifest | Local file | New release | Result |
|---|---|---|---|
| hash A | matches A | A | unchanged |
| hash A | matches A | B | overwritten |
| hash A | edited | B | conflict; --force overwrites |
| hash A | edited | A | unchanged (already current) |
| hash A | missing | any | written |
| hash A | matches A | retired | deleted, empty directories pruned |
| hash A | edited | retired | kept, listed under extra |
| none | present | B | conflict (new path collides with your file) — even when the bytes are identical, since the manifest never vouched for it; --force adopts it (overwriting only if it differs) |
| none | absent | B | written |
| no manifest | anything | any | every present file is a conflict until --force adopts the directory and writes a manifest |
Status is installed when anything was written or deleted, exists when the
skill was already current, conflict when at least one path needs --force,
error when the skill is not installed, its manifest is invalid, or its
version cannot be ordered against the candidate's (version-unknown). Without
names, update takes every manifest-bearing skill in the selected agent and
scope.
Neither command adopts a file on its own: install into a directory without
a manifest and update of a managed directory both treat a file the
manifest does not list as yours, identical or not, until --force accepts it.
remove
Deletes the files the manifest lists whose hash still matches, then the
manifest, then directories left empty — the skill directory included. A file
you edited and a file the manifest does not list are kept and reported
under kept; the status is still removed. There is no --force: nothing
makes the installer delete an edit. When SKILL.md is among the kept files
the agent still discovers the skill, and the prose output says so — delete
the directory yourself if that is what you want. A directory without a
manifest is an error (kind: "unmanaged"): it was not installed by the
CLI, so the CLI will not delete it.
Reminders after updating
At the start of a terminal command, the CLI compares each installed manifest's
version with the newest version it knows — the embedded dreamlake-cli tag,
and the catalog snapshot for other skills — for both agents, in the current
project and your home directory. When something newer exists it prints one
stderr line per installed path per CLI version:
Reminders never change files, never use the network, and stay out of JSON,
piped and background invocations. skill list --refresh is the networked
check and shows latest next to each installed version.
--json
Every subcommand emits one object with a discriminated status and a
required, nullable nextAction ({ "kind": "run", "command" },
{ "kind": "download", "url" }, or null). On failure, stdout still carries
exactly one object and stderr stays empty.
state is one of absent, installed, modified (a manifest file was
edited or removed), unmanaged (a directory with no valid manifest; error
says why when one was rejected), or blocked (something that is not a
directory is in the way). When --refresh fails, latest is
{ "error", "url" } and the rest of the object is unchanged. catalog.origin
is remote when the rows came from the server's registry, embedded for the
snapshot (with catalog.unreachable saying why a default remote fell back) and
none when this build carries neither; registry is the pin that answered —
source, tag, commit, and mismatch when the server's differs from the
embedded one. See Reading a skill.
init adds preferences (what was saved, and where) and available (the
other skills in the embedded catalog snapshot). Its catalog.origin is never
release: init does not use the network.
The top-level status is the worst across skills (error > conflict >
installed > exists). Per skill, files lists what this run wrote, so
files: [] is the proof nothing happened; a conflict carries conflicts;
unowned files appear under extra; an exists that was a guarded no-op
(the installed copy is newer, or the target has no manifest and was not
adopted — then also unmanaged: true) carries message. update adds
previous (the manifest's version before the run) and deleted. catalog.origin is release,
embedded (the release was not consulted or unreachable — then
catalog.unreachable says why) or none.
kept lists, relative to target, every file left behind: manifest files
you edited and files the manifest never listed. remove has only removed
and error statuses.
Several agents
With one agent every object above is unchanged. With several, the top-level
agent is replaced by agents, and:
install,updateandinitlist one entry per agent and skill inskills, each with anagent;init'spreferencescarriesagents.removeputs one single-agent result per agent inremovals; the top level hasagents,scope,skill,status(errorwhen any removal failed) and that failure'serrorandkind.listreplaces each row'sprojectandglobalwithinstalls, keyed by agent.
Error kind values: invalid-agent, agent-required, canceled,
invalid-name, unknown-skill, renamed, ambiguous, bad-catalog,
catalog-unreachable, integrity
(the release catalog names no sha256 for skills.tar.gz, or the download does
not match it),
bad-release, missing-in-release, version-unknown, not-installed,
not-a-directory, unmanaged, invalid-manifest, write-failed,
remove-failed, no-bundle.
Where the skills come from
Skill content is not authored in this repository. Facts about commands live in
these docs; task steps live in dreamlake-skills/<name>/actions/; each skill's
reference/ is fetched from the documentation sites by that repository's CI.
This CLI pins one dreamlake-skills revision in skills.lock (a release tag,
or a commit until the first tag exists); the build downloads that revision's
archive, verifies its sha256, and embeds dreamlake-cli/ together with a
manifest of its tag, commit and file hashes. The npm package ships the same
directory as skills/dreamlake-cli/ with skills/.manifest.json and
skills/catalog.json beside it, so an npm install reports the same version
and source as the native binary. Bumping the pin is an ordinary pull request.
Release acceptance checklist
- Edit docs first; regenerate the command-help examples
(
node docs/scripts/gen-help-examples.mjs) and commit them with the source. - Run source tests and the isolated native packaging test in CI.
- Compile all platforms from the reviewed commit. The build embeds the
pinned release's
dreamlake-cli—SKILL.md,skill.jsonand everyreference/page itsdocs[]names — and rejects a bundle missing any of them. - Test a copied binary outside the checkout with a temporary home and no
DREAMLAKE_SKILLS_*variables:init, byte readback, identical reinstall, conflict refusal, forced update preserving peer files,removekeeping an edited file, the offline error shape, and — against local release directories — arequiresclosure install, anupdatethat overwrites, retires and adds files and rewrites the manifest, a release without a checksum refused, an older release left alone. - Pack the npm package, install it into an empty prefix, and read the
same skill back through
bin/dreamlake.js(skill list,skill install). - Publish immutable versioned binaries and npm packages; verify downloaded bytes before moving release pointers.
- Repeat
dl initandskill install <name>from the public native download and npm package.
bun run scripts/verify-native-skills.ts runs the isolated packaging gate and
the npm acceptance locally.