Skip to content

Cursor.mdx

Latest commit

 

History

History
100 lines (60 loc) · 3.7 KB

Cursor.mdx

File metadata and controls

100 lines (60 loc) · 3.7 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 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.