Modular Agent Skills

Agent Skills to help developers using AI agents with Mojo and MAX. Agent Skills are folders of instructions, scripts, and resources that agents like Claude Code, Cursor, GitHub Copilot, etc. can discover and use to do things more accurately and efficiently.

The skills in this repo follow the Agent Skills format.

Version Support

Both skills support stable and nightly versions of Mojo and MAX:

How it works:
- Common rules in rules/ apply to both stable and nightly
- Version-specific rules are in rules/stable/ and rules/nightly/
- Each skill's SKILL.md includes a comprehensive version difference table
- Breaking changes are documented in reference/breaking-changes.md

Detect your version:

mojo --version           # Check Mojo version
max version              # Check MAX version
pixi list | grep mojo    # Check in pixi environment

Installation

npx skills add modularml/agent-skills

Claude Code Plugin

You can also install the skills in this repo as Claude Code plugins:

/plugin marketplace add modularml/agent-skills
/plugin install mojo-best-practices@modular-agent-skills

Available Skills

mojo-best-practices

Mojo programming best practices from the official modular/modular repository. Contains 122 rules across 12 categories, prioritized by impact. Supports both stable (v25.7) and nightly (v0.26.1).

Use when:

• Writing or reviewing Mojo code
• Converting Python or C to Mojo
• Optimizing Mojo performance
• Implementing GPU kernels (SM90/SM100)
• Working with BLAS/Accelerate

Categories (by priority):

Key stable vs nightly differences:
- Constants: alias (stable) vs comptime (nightly, preferred)
- Nightly-only: @align(N), typed errors, Never type, comptime(expr)

max-best-practices

MAX AI inference framework best practices from Modular. Contains 33 rules across 8 categories. Supports both stable (v25.7) and nightly (v26.1).

Use when:

• Deploying models with MAX Serve
• Building graphs with MAX Graph API
• Multi-GPU inference (NVIDIA + AMD)
• Optimizing inference performance
• Container/Kubernetes deployment

Categories (by priority):

Key stable vs nightly differences:
- Batch size: aggregate (stable) vs per-replica (nightly)
- Driver API: Tensor (stable) vs Buffer (nightly)
- Vision: Llama 3.2 (stable only), Gemma3 (nightly only)

Cross-references: Links to mojo-best-practices for GPU kernel development.

Usage

Skills are automatically available once installed. The agent will use them when relevant tasks are detected.

Examples:

Write a Mojo struct with proper memory management

Optimize this matrix multiplication in Mojo

Deploy a Llama model with MAX Serve

Write a GPU kernel for image processing

Skill Structure

Each skill contains:

• SKILL.md - Instructions for the agent (with Agent Skills frontmatter)
• AGENTS.md - Auto-generated rule index
• rules/ - Individual rule files for targeted context
• metadata.json - Version and metadata
• scripts/build_agents.py - Generates AGENTS.md from rules

License

MIT