Skills: where they come from, how to install, how to change them
A skill is a directory an agent (Claude Code or Codex) loads to learn
when and how to do a DreamLake task. Every public DreamLake skill is
hand-written in one place, the public
dreamlake-skills
repository, and installed from that repository's releases by the dl
CLI. The docs sites remain the only place product facts are written; a skill
fetches the pages it needs.
Installing
| You want to | Run | Network |
|---|---|---|
| Set up once, after installing the CLI | dl init | no |
| See what exists and what is installed | dl skill list (--refresh pulls the latest catalog) | no (--refresh: yes) |
| Install one or more skills | dl skill install <name...> | yes |
| Update installed skills | dl skill update [name...] | yes |
| Remove a skill | dl skill remove <name> | no |
| Install without the CLI | Download skills.tar.gz from the latest dreamlake-skills release and copy the skill directories you need (plus what their catalog.json entries require) into .claude/skills/ or .agents/skills/ | — |
dl init asks which agent (Claude or Codex) and which scope (this
project or your user directory) you want, remembers both as the default for
every later skill command (--agent, --global and --dir override
them), and installs the dreamlake-cli skill from the copy embedded in the
CLI, so it works offline. install downloads from the latest release,
brings along anything the skill requires, and writes an install manifest
(<skill>/.dreamlake-skill.json) recording version, source, agent, scope
and a hash per file. update and remove trust only that manifest.
update replaces unchanged files, reports files you edited as conflicts and
leaves them alone unless you pass --force (which only overwrites edited
files), and never touches files the installer did not write. remove
deletes only unchanged installed files; it has no --force. A manually
copied directory has no manifest; its first update needs --force, which
creates one.
Two guarantees hold whatever state a skill directory is in:
dl skill remove never deletes a file you edited — such files are
kept in place and listed in the result — and dl skill update and
install refuse to downgrade an installed skill to an older release unless
you pass --allow-downgrade.
Each skill is named for a user goal, and install brings in what a skill
requires:
| Skill | For | Requires |
|---|---|---|
dreamlake-cli | setup, login and environments, upload and download, Sources browse and upload, whole-Project transfer, project access grants, ownership, session links, Vault, runnable registration, workflow push; routes to the other skills | — |
dreamlake-lakeshore | enroll and inspect hosts, launch machines through a user-configured launch server, Slurm and external job tracking, Infrastructure Stacks, Connect AWS, Lakeshore queues and workers | dreamlake-cli |
dreamlake-memos | read, edit, collaborate on, attach to, reference, version and restore Memos | dreamlake-cli |
dreamlake-tasks | task folders, subtasks, lifecycle, progress events, linked Memos | dreamlake-cli |
dreamlake-artifacts | author content for the offline rendering frame; publish, version, share, revoke, delete and restore artifacts | dreamlake-cli |
dreamlake-scenes | generate scenes, package and push MJCF/URDF, layer and compose, validate physics with its tools, preview and read back | dreamlake-cli |
dreamlake-libraries | push, curate (dreamlake.yml, licenses, thumbnails, embeddings), search and pull asset libraries; add or remove one asset | dreamlake-cli |
dreamlake-datasets | lay out robot data, upload, connect a Source, verify paths, write and validate .dreamrc | dreamlake-cli |
sim-to-mcap | roll out a trained policy in simulation and write MCAP, handing off to datasets | dreamlake-datasets |
dreamlake-workflows | write a WorkflowSpec from a description, validate locally, publish and review | dreamlake-cli |
video-labeling-workflow | the fixed video sub-task labeling template, with its confirmation gates | dreamlake-workflows, dreamlake-datasets |
dreamlake-annotations | upload and revise annotated training episodes with the Python SDK | — |
launch-claude-remote | open another Claude remote session | — |
launch-codex-chat | open another Codex session | — |
Old names (dreamlake-scene-generation, dreamlake-envs, dreamlake-source,
dreamlake-dataset-viz, remote-source-check, workflow-generator,
workflow-publish, dreamlake-artifact-authoring,
dreamlake-note-references) are not aliases:
dl skill install <old-name> prints the new name and exits.
Where a change goes
| What changed | Where to edit | Then |
|---|---|---|
| A product fact: a command, flag, API, behavior, limit or example | The owning docs: docs/pages in dreamlake-workspace, docs/pages in dreamlake-cli | Publish the docs site as usual. The skill picks the page up on the next nightly fetch; nothing to edit in the skill. |
| A task procedure: steps, exceptions, troubleshooting, routing | dreamlake-skills/<name>/actions/*.md (and SKILL.md for routing) | Open a PR in dreamlake-skills. |
| A schema, template, example file or script | dreamlake-skills/<name>/assets/ or tools/ (tools ship with tests) | Open a PR in dreamlake-skills. |
| A new skill | Copy dreamlake-skills/_template/, fill skill.json, write SKILL.md and actions/ | Open a PR in dreamlake-skills. |
reference/ | Nothing. CI regenerates it from the docs list in skill.json. | — |
A wrong fact is fixed in the docs, never patched in an action. A page is
added to a skill's docs list only when a skill is created or the docs
site gains a page that skill should carry; day-to-day docs edits do not
touch it. The writing rules — a short SKILL.md that only routes, one
action per page, cite reference/ or --help instead of copying flags,
declare requires, verify with an isolated install — are in
dreamlake-skills/CONTRIBUTING.md.
Create a new skill
- In a
dreamlake-skillscheckout, copy_template/to<name>/; setnameinskill.jsonand in theSKILL.mdfrontmatter; filldescription,requiresand thedocsURL list. - Write
SKILL.md(when to use it; route to one action) and oneactions/*.mdper task; delete the example action. Addassets/ortools/(withtools/test_*.py) only where a task needs them. python3 scripts/sync_references.py --skill <name>to fetchreference/, thenpython3 scripts/catalog.py.python3 scripts/check.py(--offlineskips the live URL check) andpython3 -m unittest discover -s scripts -p 'test_*.py'.- Copy the branch's
<name>/and itsrequiresclosure into a temp project's.claude/skills/and.agents/skills/(notdl skill install, which fetches the released copy), read it back, and run a representative task, an SDK request and a capability it lacks with each agent — CONTRIBUTING.md, "Acceptance before merge". - Open a PR with
reference/,references.lockandcatalog.jsonincluded; the nightly tag publishes it. Rules and caps: CONTRIBUTING.md.
Maintain an existing skill
- Decide what changed with the table above: a fact goes to the docs and
needs nothing in the skill; a step goes to
<name>/actions/. - Edit the action page (or
SKILL.mdfor routing,assets/,tools/), neverreference/. Changeskill.json'sdocsonly to add a page the skill should carry, then re-runsync_references.py --skill <name>. - Renaming, merging or splitting: new directories, one line per old name in
renamed.json, delete the old directory,python3 scripts/catalog.py. python3 scripts/check.py --offlineand the unit tests.- Copy the branch's skill and its
requiresclosure into a temp project and read back the changed action (CONTRIBUTING.md, "Acceptance before merge"); the released copy is only re-checked after the tag. - Open a PR; after the nightly release,
dl skill update <name>picks it up. Bumpdreamlake-cli/skills.lockonly when the embedded copy must follow. Rules and caps: CONTRIBUTING.md.
Anatomy of a skill
Example skill.json:
reference/ files carry a site prefix (docs-artifacts.md,
cli-artifacts.md, viz-spec.md) because the sites share page names. Each
starts with a line the fetcher writes:
That line, together with the docs site's own <!-- source: … --> export
header that the fetcher records in references.lock, is how a fact in a
skill traces back to the docs release it was fetched from, and how
check.py detects a hand-edited reference.
The three repository-level files
| File | Written by | Holds |
|---|---|---|
renamed.json | a developer, when a skill is merged or renamed | old name → new name |
catalog.json | scripts/catalog.py, from every skill.json, renamed.json and the release tag | the index that dl skill list and dependency resolution download |
references.lock | scripts/sync_references.py | per fetched page: source URL, docs version, hash of the original and of the converted file |
catalog.json derives from the skill.json files and check.py keeps them
consistent. references.lock is kept apart from skill.json so that "what
the author asked for" and "what CI actually fetched" can be told apart when
a check fails.
Authenticated skills API
The backend serves a separately pinned, read-only public skill bundle. It does not follow the latest public release automatically. These authenticated endpoints report the version actually served:
| Endpoint | Result |
|---|---|
GET /skills | Bundle version: { tag, commit }, skill catalog and renames. |
GET /skills/:skill | The same version, manifest, SKILL.md body and file index. |
GET /skills/:skill/files/* | A UTF-8 file as plain text; binary files return 415. |
Responses carry X-Skills-Tag, X-Skills-Commit and strong ETags. File ETags are
content SHA-256 hashes. A conditional read can return 304. If the archive fails
validation, the endpoint returns a skills loading error.
The built-in dreamlake_skills_list and dreamlake_skills_read tools use this
server bundle and require the turn's skills:read scope. Follow next until
complete when reading a file in pages. Reading a skill grants no Project or
resource authority and does not make every described API/tool available.
Public installs, the CLI's embedded bundle, and the server registry can use different releases. The response headers identify the server's version.
Release and verification
Lifecycle: edit → check.py → PR → merge → nightly fetch, tag and
release → dl skill update. The copy embedded in the CLI follows only
when dreamlake-cli/skills.lock is bumped in its own PR.
Nightly, dreamlake-skills CI re-fetches every reference/, runs
check.py, commits the result, and tags a dated release (vYYYY.MM.DD)
whenever main has moved since the last tag. A docs deploy or a merged
action change therefore becomes an installable skill version the next day
with no manual step. The CLI pins one tag in skills.lock; bumping it is an
ordinary dreamlake-cli PR and is what makes the copy that dl init
installs current.
Before merge, acceptance runs on the branch working tree (CONTRIBUTING.md,
"Acceptance before merge"). Only after the tag, before claiming a skill
change is live, install the released copy into an isolated directory
(dl skill install <name> --dir <tmp>) and read it back: the action
text, and the first line of each reference/ file. Follow the
public contribution guide
for the public skill review and release process.