Lola - AI Context Package Manager

Write Agent Skills and Contexts once, use everywhere.

Lola is a universal AI Package Manager. If an agent's skills were an RPM, Lola is the DNF for it. Write your skills and context modules once as portable packages, then install them to any AI assistant or agent with a single command.

Supported AI Assistants

¹ Project scope only — VS Code has no user-scope location for slash commands.

GitHub Copilot has two targets that share the same .github/ (project) and ~/.copilot/ (user) files but differ in MCP handling:

• copilot-cli - writes MCP servers using the mcpServers key (~/.copilot/mcp-config.json for user scope).
• copilot-vscode - writes MCP servers to .vscode/mcp.json using VS Code's servers key. VS Code has no user-scope location for slash commands or MCP, so those are skipped (with a warning) when installing at user scope.

When no assistant is selected explicitly, copilot-vscode is preferred over copilot-cli to avoid writing the same project files twice.

Installation

# Recommended: install from PyPI
uv tool install lola-ai

# Or with pip
pip install lola-ai

Want the latest dev version? uv tool install git+https://github.com/LobsterTrap/lola

Quick Start

# Set up the official marketplace
lola market add general https://raw.githubusercontent.com/RedHatProductSecurity/lola-market/main/general-market.yml

# Add a module
lola mod add https://github.com/user/my-skills.git

# Install to all detected assistants
lola install my-skills

# Or install to a specific assistant
lola install my-skills -a claude-code

Declarative Installation

Create a .lola-req in your project:

python-tools>=1.0.0
https://github.com/user/module.git@main
https://github.com/quay/ai-helpers.git@main#subdirectory=plugins/dev
https://github.com/user/repo.git#assistant=claude-code,cursor

URL fragments support:

• subdirectory=path/to/module - Install from a subdirectory in the repository
• assistant=name1,name2 - Install to specific assistants

lola sync

Documentation

Full documentation is available at lobstertrap.org/lola.

Official Lola Marketplace

We maintain an official, community-driven marketplace with curated modules at github.com/RedHatProductSecurity/lola-market.

Quick setup:

lola market add general https://raw.githubusercontent.com/RedHatProductSecurity/lola-market/main/general-market.yml

This gives you instant access to community modules like workflow automation, code quality tools, and more. We highly encourage you to:

• Use modules from the official marketplace
• Contribute your own modules
• Share feedback and improvements

All contributions are welcome! See the marketplace contributing guide.

Register a marketplace

# Add a marketplace from a URL
lola market add general https://raw.githubusercontent.com/RedHatProductSecurity/lola-market/main/general-market.yml

# List registered marketplaces
lola market ls

Search and install from marketplace

# Search across all enabled marketplaces
lola mod search authentication

# Install directly from marketplace (auto-adds and installs)
lola install git-workflow -a claude-code

When a module exists in multiple marketplaces, Lola prompts you to select which one to use.

Manage marketplaces

# Update marketplace cache
lola market update general

# Update all marketplaces
lola market update

# Disable a marketplace (keeps it registered but excludes from search)
lola market set --disable general

# Re-enable a marketplace
lola market set --enable general

# Remove a marketplace
lola market rm general

Marketplace YAML format

Create your own marketplace by hosting a YAML file with this structure:

name: My Marketplace
description: Curated collection of AI skills
version: 1.0.0
modules:
  - name: git-workflow
    description: Git workflow automation skills
    version: 1.0.0
    repository: https://github.com/user/git-workflow.git
    tags: [git, workflow]

  - name: code-review
    description: Code review assistant skills
    version: 1.2.0
    repository: https://github.com/user/code-review.git
    tags: [review, quality]

Fields:

• name: Marketplace display name
• description: What this marketplace provides
• version: Marketplace schema version
• modules: List of available modules
  • name: Module name (must match repository directory name)
  • description: Brief description shown in search results
  • version: Module version
  • repository: Git URL, zip/tar URL, or local path
  • tags (optional): Keywords for search

CLI Reference

Module Management (lola mod)

Marketplace Management (lola market)

Installation

Installation Scopes

Lola supports two installation scopes:

• Project scope (default): Installs to project directories (.claude/, .cursor/, .opencode/, etc.)
• User scope: Installs globally to user configuration directories

User scope locations:

• Linux/Unix: ~/.config/opencode/, ~/.claude/, ~/.cursor/
• macOS: ~/.config/opencode/, ~/.claude/, ~/.cursor/
• Windows: ~/.config/opencode/, ~/.claude/, ~/.cursor/

Examples:

# Install to current project (default)
lola install my-module

# Install globally for your user  
lola install my-module --scope user

# Install to specific project
lola install my-module /path/to/project

Creating a Module

1. Initialize

lola mod init my-skills
cd my-skills

This creates an Agent Plugins 1.0 package:

my-skills/
  plugin.json          # Package manifest
  skills/
    example-skill/
      SKILL.md         # Initial skill (unless --no-skill)
  mcp.json             # MCP servers (unless --no-mcps)
  dev.getlola/         # Lola extension namespace
    commands/
      example-command.md # (unless --no-command)
    agents/
      example-agent.md   # (unless --no-agent)
    AGENTS.md            # (unless --no-instructions)

Use --format lola for the legacy module/ layout.

2. Edit the skill

Edit skills/example-skill/SKILL.md:

---
name: my-skills
description: Description shown in skill listings
---

# My Skill

Instructions for the AI assistant...

3. Add supporting files to skills

You can add additional files to any skill directory (scripts, templates, examples, etc.). Reference them using relative paths in your SKILL.md:

# My Skill

Use the helper script: `./scripts/helper.sh`

Load the template from: `./templates/example.md`

Path handling: Use relative paths like ./file or ./scripts/helper.sh to reference files in the same skill directory. Each assistant handles these differently:

• Claude Code copies the entire skill directory, so relative paths like ./scripts/helper.sh work because the files are alongside SKILL.md
• Cursor only copies the skill content to an .mdc file, so Lola rewrites ./ paths to point back to .lola/modules/<module>/skills/<skill>/
• Gemini/OpenCode don't copy skills—they add entries to GEMINI.md/AGENTS.md that tell the AI to read the original SKILL.md from .lola/modules/, so relative paths work from that location

Example skill structure:

my-skills/
  skills/
    example-skill/
      SKILL.md
      scripts/
        helper.sh
      templates/
        example.md

4. Add more skills

Create additional skill directories under skills/, each with a SKILL.md:

my-skills/
  skills/
    example-skill/
      SKILL.md
    git-workflow/
      SKILL.md
    code-review/
      SKILL.md

5. Add slash commands

Create a commands/ directory with markdown files:

my-skills/
  skills/
    example-skill/
      SKILL.md
  commands/
    review-pr.md
    quick-commit.md

Command files use YAML frontmatter:

---
description: Review a pull request
argument-hint: <pr-number>
---

Review PR #$ARGUMENTS and provide feedback.

Note: Modules use auto-discovery. Skills, commands, and agents are automatically detected from the directory structure. No manifest file is required.

6. Add to registry and install

lola mod add ./my-skills
lola install my-skills

Module Structure

my-module/
  skills/            # Skills directory
    skill-name/
      SKILL.md       # Required: skill definition
      scripts/       # Optional: supporting files
      templates/     # Optional: templates
  commands/          # Optional: slash commands
    review-pr.md
    quick-commit.md
  agents/            # Optional: subagents
    my-agent.md

Note: Modules use auto-discovery. Skills are discovered from skills/<name>/SKILL.md, commands from commands/*.md, and agents from agents/*.md. No manifest file is required.

SKILL.md

---
name: skill-name
description: When to use this skill
---

# Skill Title

Your instructions, workflows, and guidance for the AI assistant.

Reference supporting files using relative paths:
- `./scripts/helper.sh` - files in the same skill directory
- `./templates/example.md` - subdirectories are supported

Supporting files: You can include scripts, templates, examples, or any other files in your skill directory. Use relative paths like ./file or ./scripts/helper.sh in your SKILL.md to reference them. These paths are automatically rewritten for different assistant types during installation.

Command Files

---
description: What this command does
argument-hint: <required> [optional]
---

Your prompt template here. Use $ARGUMENTS for all args or $1, $2 for positional.

Argument variables:

• $ARGUMENTS - All arguments as a single string
• $1, $2, $3... - Positional arguments

Commands are automatically converted to each assistant's format:

• Claude/Cursor: Markdown with frontmatter (pass-through)
• Gemini: TOML with {{args}} substitution

How It Works

1. Marketplaces: Register catalogs at ~/.lola/market/ with cached data at ~/.lola/market/cache/
2. Discovery: Search across enabled marketplace caches to find modules
3. Registry: Modules are stored in ~/.lola/modules/
4. Installation: Skills and commands are converted to each assistant's native format
5. Prefixing: Skills and commands are prefixed with module name to avoid conflicts (e.g., mymodule-skill)
6. Scopes:
   • Project scope (default): Copies modules to .lola/modules/ within the project
   • User scope: Installs globally to platform-appropriate user config directories
7. Updates: lola mod update re-fetches from original source; lola update regenerates files; lola market update refreshes marketplace caches

Code of Conduct

This project follows the Contributor Covenant Code of Conduct v2.1.

Security

For reporting vulnerabilities, see SECURITY.md.

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Governance

Lola is governed by its maintainers. See GOVERNANCE.md for the project's roles, decision-making process, and release cadence.

Community

Join the community on Matrix: #lola-ai:matrix.org

License

Apache-2.0

Authors

• Igor Brandao
• Katie Mulliken