Skip to content

Cursor.mdx

Latest commit

 

History

History
100 lines (60 loc) · 4.05 KB

Cursor.mdx

File metadata and controls

100 lines (60 loc) · 4.05 KB
Raw
title Cursor Configuration (.cursor)
icon wand-magic-sparkles
description How Omi uses the .cursor folder (rules, skills, commands, and agents) to guide AI assistance in this repository.

Overview

This repo includes a .cursor/ directory that configures Cursor + AI agents to work effectively across Omi’s codebase. It contains:

  • Rules that apply based on file patterns (backend/flutter/web/etc.)
  • Reusable “skills” and slash commands
  • Specialized agents (e.g. backend API, Flutter, firmware)
  • Internal reference docs for agents (not the same as the public docs/ site)

If you’re contributing to Omi and using Cursor, understanding .cursor/ makes it much easier to add consistent automation and avoid common mistakes.

.cursor/ vs docs/ (important)

  • docs/ is the public Mintlify site at docs.omi.me. What belongs there is defined in docs/AGENTS.md: how to use the app, hardware/DIY, and how to build on Omi. Unlisted MDX or MD under docs/ is still a public URL.
  • .cursor/ is editor/agent configuration for contributors and AI tooling inside this repo.

Do not dump a runbook, flag table, invariant, or agent-only rule into docs/ "temporarily." Those live next to the owning code (backend/docs/, desktop/macos/docs/, .github/agent-docs/, product/invariants/) or in a private tracker. We document .cursor/ publicly here so contributors can use it; .cursor/docs/ is not the public site.

What’s inside .cursor/

Rules (.cursor/rules/)

Rules are small, focused guidance files (typically *.mdc) that apply automatically based on globs (e.g. backend/**/*.py, app/**/*.dart, web/**/*.ts(x)).

Typical rule topics:

  • Architecture: module boundaries + import hierarchy
  • Testing & verification: what to run before merging
  • Style and conventions: formatting, localization requirements, common mistakes

Skills (.cursor/skills/)

Skills are reusable “playbooks” for recurring workflows. A skill folder typically contains:

  • SKILL.md: the skill’s instructions and checklists
  • commands/: slash commands (e.g. /backend-test, /pr)
  • agents/: specialized agents that focus on specific domains

Commands (.cursor/commands/)

Legacy / general commands that show up in Cursor when you type /. (Many commands also live under skills/*/commands/.)

Agents (.cursor/agents/)

Legacy / compatibility agent definitions. Most agents live under skills/*/agents/.

Internal agent docs (.cursor/docs/)

Internal reference docs used by agents (architecture maps, component indexes, internal guidance).

Note: These are for agent operation and contributor context, not for end users.

Hooks (.cursor/hooks/ and .cursor/hooks.json)

Optional hook scripts/config to observe and extend the agent loop. Useful for enforcing workflows, validation, and automation.

MCP config (.cursor/mcp.json)

Configuration for MCP servers that provide external tools (e.g. browser testing, Notion/Figma integration if enabled).

Common contributor workflows

Add a new rule

  1. Add a focused rule file under .cursor/rules/ (e.g. backend-foo.mdc)
  2. Ensure it targets the correct file glob(s)
  3. Keep it actionable: conventions + “how to verify”

Add a new skill

  1. Create .cursor/skills/<skill-name>/SKILL.md
  2. Put any related slash commands under .cursor/skills/<skill-name>/commands/
  3. Put any related agents under .cursor/skills/<skill-name>/agents/

Update public documentation

If your change affects how people use the app, hardware, or public developer APIs:

  • Read docs/AGENTS.md first. Only then update docs/ and docs/docs.json.
  • Operator runbooks, flags, and invariants do not go on the public site.

Safety & maintenance notes

  • Don’t put secrets (tokens, keys, credentials) in .cursor/ files.
  • Keep rules layer-aware (e.g. don’t encourage importing from routers/ inside utils/).
  • Prefer linking to public docs in docs/ only when the page fits docs/AGENTS.md. Keep .cursor/docs/ for internal agent context.