DreamLake

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 toRunNetwork
Set up once, after installing the CLIdl initno
See what exists and what is installeddl skill list (--refresh pulls the latest catalog)no (--refresh: yes)
Install one or more skillsdl skill install <name...>yes
Update installed skillsdl skill update [name...]yes
Remove a skilldl skill remove <name>no
Install without the CLIDownload 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:

SkillForRequires
dreamlake-clisetup, 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-lakeshoreenroll and inspect hosts, launch machines through a user-configured launch server, Slurm and external job tracking, Infrastructure Stacks, Connect AWS, Lakeshore queues and workersdreamlake-cli
dreamlake-memosread, edit, collaborate on, attach to, reference, version and restore Memosdreamlake-cli
dreamlake-taskstask folders, subtasks, lifecycle, progress events, linked Memosdreamlake-cli
dreamlake-artifactsauthor content for the offline rendering frame; publish, version, share, revoke, delete and restore artifactsdreamlake-cli
dreamlake-scenesgenerate scenes, package and push MJCF/URDF, layer and compose, validate physics with its tools, preview and read backdreamlake-cli
dreamlake-librariespush, curate (dreamlake.yml, licenses, thumbnails, embeddings), search and pull asset libraries; add or remove one assetdreamlake-cli
dreamlake-datasetslay out robot data, upload, connect a Source, verify paths, write and validate .dreamrcdreamlake-cli
sim-to-mcaproll out a trained policy in simulation and write MCAP, handing off to datasetsdreamlake-datasets
dreamlake-workflowswrite a WorkflowSpec from a description, validate locally, publish and reviewdreamlake-cli
video-labeling-workflowthe fixed video sub-task labeling template, with its confirmation gatesdreamlake-workflows, dreamlake-datasets
dreamlake-annotationsupload and revise annotated training episodes with the Python SDK—
launch-claude-remoteopen another Claude remote session—
launch-codex-chatopen 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 changedWhere to editThen
A product fact: a command, flag, API, behavior, limit or exampleThe owning docs: docs/pages in dreamlake-workspace, docs/pages in dreamlake-cliPublish 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, routingdreamlake-skills/<name>/actions/*.md (and SKILL.md for routing)Open a PR in dreamlake-skills.
A schema, template, example file or scriptdreamlake-skills/<name>/assets/ or tools/ (tools ship with tests)Open a PR in dreamlake-skills.
A new skillCopy 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

  1. In a dreamlake-skills checkout, copy _template/ to <name>/; set name in skill.json and in the SKILL.md frontmatter; fill description, requires and the docs URL list.
  2. Write SKILL.md (when to use it; route to one action) and one actions/*.md per task; delete the example action. Add assets/ or tools/ (with tools/test_*.py) only where a task needs them.
  3. python3 scripts/sync_references.py --skill <name> to fetch reference/, then python3 scripts/catalog.py.
  4. python3 scripts/check.py (--offline skips the live URL check) and python3 -m unittest discover -s scripts -p 'test_*.py'.
  5. Copy the branch's <name>/ and its requires closure into a temp project's .claude/skills/ and .agents/skills/ (not dl 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".
  6. Open a PR with reference/, references.lock and catalog.json included; the nightly tag publishes it. Rules and caps: CONTRIBUTING.md.

Maintain an existing skill

  1. 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/.
  2. Edit the action page (or SKILL.md for routing, assets/, tools/), never reference/. Change skill.json's docs only to add a page the skill should carry, then re-run sync_references.py --skill <name>.
  3. Renaming, merging or splitting: new directories, one line per old name in renamed.json, delete the old directory, python3 scripts/catalog.py.
  4. python3 scripts/check.py --offline and the unit tests.
  5. Copy the branch's skill and its requires closure 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.
  6. Open a PR; after the nightly release, dl skill update <name> picks it up. Bump dreamlake-cli/skills.lock only when the embedded copy must follow. Rules and caps: CONTRIBUTING.md.

Anatomy of a skill

dreamlake-skills/<name>/
  skill.json             metadata: name, description, requires, docs URLs, tool requirements
  SKILL.md               hand-written: when to use this skill; routes a request to one action (≤ 80 lines)
  actions/*.md           hand-written: one task per page, command first, then exceptions
  tools/                 hand-written, optional: scripts and their tests
  assets/                hand-written, optional: schemas, templates, examples, contract documents
  reference/*.md         generated: pages fetched by CI from the docs sites; first line names the source
  .dreamlake-skill.json  written by the CLI at install time; not in the repository

Example skill.json:

json
{
  "name": "dreamlake-artifacts",
  "description": "Author, publish, version, share and restore DreamLake artifacts.",
  "requires": ["dreamlake-cli"],
  "docs": [
    "https://docs.dreamlake.ai/artifacts",
    "https://cli.dreamlake.ai/artifacts",
    "https://cli.dreamlake.ai/projects"
  ],
  "tools": { "python": ">=3.12", "packages": [] }
}

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:

<!-- generated from https://docs.dreamlake.ai/artifacts at 0.1.101; do not edit -->

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

FileWritten byHolds
renamed.jsona developer, when a skill is merged or renamedold name → new name
catalog.jsonscripts/catalog.py, from every skill.json, renamed.json and the release tagthe index that dl skill list and dependency resolution download
references.lockscripts/sync_references.pyper 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:

EndpointResult
GET /skillsBundle version: { tag, commit }, skill catalog and renames.
GET /skills/:skillThe 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.