Prepare a Lola module for Che workspaces

Prepare a Lola module in a Git repository so that Che installs its AI assistant skills, commands, and agents into workspaces at startup.

Lola reads the module and writes its content into the native directory structure of each AI assistant that you install it for. Prepare one module for every assistant that your team uses, rather than one module per assistant: the skills, commands, agents, and instructions are the same, and only the destination directory differs.

Prerequisites
  • A Git repository for the module that workspaces can reach. Prefer a public repository, because a workspace can clone a private repository only when it has Git credentials configured.

  • uv on the workstation that prepares the module, to install the Lola command-line tool. See uv.

  • Lola on the workstation that prepares the module, at the commit the init image pins. The released version predates the agent-plugin layout, so install the commit rather than the package:

    $ uv tool install "git+https://github.com/LobsterTrap/lola@53b3687975b373c856fc67b9a8f18c395c76fca4"
Procedure
  1. Create the module structure in the repository root. Lola takes the module name from the name field of plugin.json, so keep that field equal to the repository directory name. A name argument to lola mod init would create a subdirectory instead:

    $ lola mod init -s <skill-name>

    The command creates the agent-plugin layout with example content:

    plugin.json
    README.md
    mcp.json
    skills/<skill-name>/SKILL.md
    dev.getlola/
      AGENTS.md
      agents/example-agent.md
      commands/example-command.md

    --minimal omits the example content, but it still writes README.md and plugin.json, and creates the empty component directories. You can also create the same files by hand.

  2. Set the module name, version, and description in plugin.json. Keep the dev.getlola extension so that Lola finds the commands, agents, and instructions:

    {
      "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
      "name": "my-agent-config",
      "version": "0.1.0",
      "description": "Team AI assistant configuration.",
      "extensions": {
        "dev.getlola": {
          "commands": "./dev.getlola/commands",
          "agents": "./dev.getlola/agents",
          "instructions": "./dev.getlola/AGENTS.md"
        }
      }
    }
  3. Add skills. Each skill is a directory under skills/ that contains a SKILL.md file. Lola discovers every skill directory automatically, so the manifest does not list them:

    ---
    name: review-checklist
    description: "Review checklist for a Go change: tests, error handling, and rollback."
    ---
    
    # Review checklist
    
    Describe when the assistant uses this skill and what it must do.
    • The file starts with a YAML front matter block.

    • The description field is mandatory. Lola skips a skill without a description and reports a warning.

    • Quote a description that contains a colon. Without quotes the front matter is invalid and Lola skips the whole skill.

  4. Optional: Add commands and agent definitions as Markdown files under dev.getlola/commands/ and dev.getlola/agents/. Each file has a description field in the front matter.

  5. Optional: Add MCP servers to mcp.json. Use type: streamable-http for a remote server. Do not add credentials: the file is stored in Git and copied into the workspace.

  6. Validate the module before you push it. lola mod add . reports the same warnings that the init container reports at workspace startup:

    $ lola mod add .
    $ lola install <module-name> -a <assistant> -s user

    Check that the content is present in the destination of that assistant and that no warning names a skill or an agent.

  7. Validate the module for the other assistants that your team uses. One module serves every assistant: run the command from the previous step once per assistant, or run it without -a to select the assistants interactively:

    $ lola install <module-name> -s user
    • -a accepts a single assistant, for example -a gemini-cli or -a opencode. Run the command once per assistant in the subset that you want to check.

    • Without -a, Lola asks which assistants to select, because the command runs in a terminal. The init container runs without a terminal and installs Lola’s default set, which leaves out copilot-cli.

    • openclaw needs a different command: lola install <module-name> -a openclaw -s user fails with --scope user cannot be used with a project path argument. Run it without -s user. OpenClaw installs into /home/user/.openclaw/workspace, so create that directory first if it does not exist, and it receives the skills only, because Lola drops commands, agents, and MCP servers for that assistant. The init container creates that directory and runs this command itself, so naming openclaw in LOLA_AGENTS works.

    • Each assistant receives the content in its own location. See AI assistant configuration reference.

    • Gemini CLI has no agent definitions: Lola skips the files in dev.getlola/agents/ for that assistant and converts commands to the TOML format.

    • Che installs the module for the assistants that the LOLA_AGENTS variable names, as a single name, a comma-separated list, or all. Check the module with the same list that your workspaces use. See Install the recommended AI assistant configuration in every workspace.

  8. Commit and push the module. Create a tag for each release so that clusters can install a fixed version.

Verification
  • lola list shows the installed modules and the assistants they are installed for. lola mod info <module-name> lists the skills that Lola found in the module.

  • A workspace started with the recommended configuration reports warnings=0 in /home/user/.lola/init-status.