Skip to main content

​
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 single source of truth for user-facing documentation and is what gets deployed to docs.omi.me.
  • .cursor/ is editor/agent configuration intended to help contributors and AI tooling inside this repo.
In other words: we document .cursor/ publicly here (so contributors can use it), but .cursor/docs/ is not the public documentation 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, GitHub automation, 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 user-facing behavior or developer APIs:
  • Update docs/ (public)
  • Add/adjust nav entries in docs/docs.json if you add a new page

​
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/ when something is user-facing, and keep .cursor/docs/ for internal agent context.