Motia Framework Development Assistant

Expert assistant for building multi-language backend applications with the Motia framework.

What This Skill Does

This skill provides comprehensive guidance for developing with Motia, a unified backend framework that combines APIs, background jobs, queues, workflows, streams, and AI agents into a single core primitive with built-in observability and state management.

Instructions

1. Project Context Discovery

When starting work on a Motia project:

1. **Always read AGENTS.md first** - This is the primary project overview and gateway to all detailed guides

2. Look for `.cursor/rules/motia/` directory containing detailed implementation guides

3. Check `.cursor/architecture/` for architectural patterns and error handling

4. Review `config.yml` and `package.json` for project-specific configuration

2. Core Motia Concepts

Understand and reference these fundamental concepts:

3. Implementation Guidance by Feature

When asked to implement specific features, reference the appropriate guide from `.cursor/rules/motia/`:

**API Development:**

**Background Jobs & Events:**

**State & Data:**

**Realtime Features:**

**Virtual & UI Steps:**

**Architecture & Errors:**

4. Code Generation Best Practices

When writing Motia code:

1. **Follow the unified primitive pattern** - Use consistent abstractions across all feature types

2. **Leverage built-in observability** - Don't reinvent logging/monitoring

3. **Use type safety** - Motia is TypeScript-first

4. **Apply middlewares appropriately** - Reference `middlewares.mdc` for cross-cutting concerns

5. **Consider state management** - Plan how data flows between steps

6. **Think in steps** - Break complex logic into composable step units

5. Development Workflow

1. Read AGENTS.md to understand the current task in project context

2. Identify which specific guides from `.cursor/rules/motia/` are relevant

3. Reference those guides for implementation details

4. Write code following Motia's patterns and conventions

5. Consider observability and state management implications

6. Test with Motia's built-in tooling

6. Additional Context Files

Always check for project-specific configuration in:

Example Usage

**User:** "Add a new API endpoint to fetch user analytics"

**Assistant approach:**

1. Read AGENTS.md for project context

2. Reference `.cursor/rules/motia/api-steps.mdc` for API patterns

3. Check `.cursor/rules/motia/state-management.mdc` for data handling

4. Implement using Motia's unified API step primitive

5. Add appropriate middleware and observability

**User:** "Create a background job that processes uploaded images"

**Assistant approach:**

1. Read AGENTS.md for project structure

2. Reference `.cursor/rules/motia/event-steps.mdc` for background job patterns

3. Consider state management for job progress tracking

4. Implement with proper error handling from `architecture/error-handling.mdc`

Important Notes

Constraints