Lola Modules

Lola Modules

Create portable AI modules with lazy context loading that work across multiple AI assistants (Claude Code, Cursor, Gemini CLI).

Overview

Lola modules are portable skill packages - collections of AI instructions, workflows, scripts, and templates that work across multiple AI assistants. Lola modules provide:

• Multi-assistant support - Write once, install to Claude Code, Cursor, or Gemini CLI
• Automatic format conversion - SKILL.md converts to each assistant's native format
• Slash commands - Custom commands that convert to each assistant's format
• Installation management - Central registry with versioning and updates
• Modular organization - Multiple skills and commands in one module

Foundation: This skill builds on the skill-creator skill. For core principles about skills, progressive disclosure, and bundled resources, consult that skill first. This skill focuses on Lola-specific features and multi-assistant packaging.

Lola vs Traditional Skills

When to Use Lola Modules

Use Lola modules when:

• Supporting multiple AI assistants (Claude Code, Cursor, Gemini CLI)
• Building complex workflows with trigger-based context loading
• Creating reusable personas or workflow libraries
• Managing installations across multiple projects
• Distributing skills to teams or communities

Always make Lola modules instead of traditional skills. If there is already an existing module you should add the skill or command to it.

Module Structure

my-module/
├── .lola/
│   └── module.yml       # Required: module manifest
├── skill-name/          # One or more skill directories
│   ├── SKILL.md         # Required: skill definition with frontmatter
│   ├── scripts/         # Optional: helper scripts
│   └── templates/       # Optional: templates
└── commands/            # Optional: slash commands
    ├── command1.md
    └── command2.md

Creation Workflow

1. Initialize Module

lola mod init my-module
cd my-module

This creates the basic structure with .lola/module.yml and a starter skill.

2. Define module.yml

Edit .lola/module.yml:

type: lola/module
version: 0.1.0
description: What this module provides

skills:
  - skill-one      # Directory names containing SKILL.md
  - skill-two

commands:          # Optional
  - command-name   # From commands/ directory

Key fields:

• type: Always lola/module
• version: Semantic versioning
• description: Brief module summary
• skills: List of skill directory names
• commands: List of command names (without .md extension)

3. Create Skills

Each skill directory needs a SKILL.md with YAML frontmatter:

---
name: skill-name
description: When to use this skill and what it does
---

# Skill Title

Instructions, workflows, and guidance following skill-creator principles.

Important:

• The description field is the primary trigger mechanism. Include specific scenarios and keywords that should activate the skill.
• Apply all skill-creator principles to each skill: progressive disclosure, bundled resources (scripts/, references/, assets/), appropriate degrees of freedom, etc.
• Each skill in a Lola module is a complete, standalone skill that follows the same creation process as traditional skills.

4. Add Commands (Optional)

Create command files in commands/:

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

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

Command variables:

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

Commands auto-convert to each assistant's format:

• Claude/Cursor: Markdown passthrough
• Gemini: TOML with {{args}} substitution

Installation and Distribution

Register Module

# From git repository
lola mod add https://github.com/user/my-module.git

# From local directory
lola mod add ./my-module

# From archive
lola mod add ~/Downloads/my-module.zip

Modules are registered in ~/.lola/modules/.

Install to Assistants

# Install to all assistants (user scope)
lola install my-module

# Install to specific assistant
lola install my-module -a cursor
lola install my-module -a claude-code
lola install my-module -a gemini-cli

# Install to project (required for Cursor and Gemini CLI skills)
lola install my-module -s project ./my-project

Installation creates:

• Claude Code: .claude/skills/<module>-<skill>/SKILL.md (native format)
• Cursor: .cursor/rules/<module>-<skill>.mdc (converted frontmatter)
• Gemini CLI: GEMINI.md (managed section with markers)
• All: .lola/modules/<module>/ (local copy of module assets)

Scope Limitations

Note: Cursor and Gemini CLI require project scope for skills, but commands work in both scopes.

Manage Installations

# List installed modules
lola installed

# Update module from source
lola mod update my-module

# Regenerate assistant files
lola update

# Uninstall
lola uninstall my-module

The installation registry (~/.lola/installed.yml) tracks all installations with module name, assistant, scope, project path, and installed skills.

Testing Workflow

1. Create test project:

   mkdir /tmp/test-lola
   cd /tmp/test-lola
   

2. Install module:

   lola mod add ./my-module
   lola install my-module -s project .
   

3. Open in assistant:

   cursor .  # or claude, gemini
   

4. Verify:

   • Skills load correctly in each assistant
   • Instructions appear in assistant-specific format
   • Scripts execute properly
   • Commands work with arguments
   • Bundled resources are accessible

5. Iterate:

   • Edit source module
   • Run lola mod update my-module
   • Run lola update to regenerate files
   • Test again

Key Concepts

Progressive Disclosure

Lola modules follow the same progressive disclosure principles as traditional skills:

1. Module metadata - Always loaded (name, description)
2. Skill frontmatter - Loaded to determine when skill triggers
3. Skill body - Loaded when skill activates
4. Bundled resources - Loaded on-demand (references/) or executed without loading (scripts/)

This minimizes token usage while maintaining full functionality. See skill-creator for detailed guidance on progressive disclosure patterns.

Multi-Assistant Portability

Lola handles format conversion automatically:

• Claude Code: Native SKILL.md format (no conversion needed)
• Cursor: Converts frontmatter to .mdc format with special syntax
• Gemini CLI: Appends to managed section in GEMINI.md between markers
• Commands: Converts to assistant-specific formats (Markdown or TOML)
• Paths: Adjusts resource paths for installed locations

Best Practices

1. Follow skill-creator principles - Apply progressive disclosure, bundled resources, and organization patterns
2. Clear skill descriptions - Make trigger keywords obvious and specific in frontmatter
3. One purpose per skill - Keep individual skills focused
4. Scripts for heavy lifting - Offload computation, API calls, file ops to scripts
5. Return structured data - Scripts should return JSON or structured output
6. Document thoroughly - Add comprehensive README for module users
7. Test across assistants - Verify behavior in Claude Code, Cursor, and Gemini CLI
8. Version carefully - Use semantic versioning for updates
9. Organize logically - Group related skills in the same module
10. Security review - Audit scripts from untrusted sources

Troubleshooting

Module Won't Install

• Verify .lola/module.yml exists and has valid YAML
• Check that skills list matches actual directories
• Ensure SKILL.md files have proper frontmatter

Skills Not Triggering

• Review description field - it's the primary trigger
• Try more specific keywords or scenarios
• For Cursor/Gemini CLI, ensure project scope installation

Commands Not Working

• Verify command frontmatter has description field
• Check argument substitution syntax ($ARGUMENTS, $1, etc.)
• Confirm commands are listed in module.yml

Bundled Resources Not Found

• Verify resource paths are correct relative to skill directory
• Check that resources are listed in skill references section
• Ensure resources were included in module installation

Further Reading

• skill-creator - Core principles for skill design, progressive disclosure, bundled resources
  • See skill-creator's references/workflows.md for sequential workflows and conditional logic patterns
  • See skill-creator's references/output-patterns.md for template and example patterns
• Lola README - references/lola-README.md for CLI reference and installation