Repository-Defined Custom Agents

Feature Requests
1

Hi Cursor Team,

I’m really enjoying using Cursor and wanted to share an idea for its continued improvement.

I think the following feature suggestion could be a valuable “low-hanging fruit” enhancement, providing a really cool user experience boost for engineering teams.

Problem:

Currently, configuring and maintaining consistent AI agent behavior (personas, instructions, expertise, tool access, actions) across a development team using Cursor can be challenging. Individual configurations lead to variations, making collaboration less efficient and potentially hindering adherence to project-specific standards or workflows. Sharing effective agent configurations requires manual copy-pasting or out-of-band communication.

Proposed Solution:

Introduce a mechanism allowing teams to define custom AI agents directly within their project repository using .mdc files, similar to Cursor’s rule files. Cursor would automatically detect and load these agent definitions, making them readily available with a dedicated UI view (showing parsed frontmatter) to all team members working on that project.

Implementation Details:

  1. Directory Convention: Designate a specific directory within the workspace for agent definitions, for example, .cursor/agents/.

  2. File Format: Use Markdown Content (.mdc) files for defining agents. Each file represents one agent.

  3. Structured Definition: Employ YAML frontmatter within the .mdc files to specify key agent configuration, including its name, description, preferred model, type, allowed actions, tool access, integrations, and an icon. The body of the Markdown file contains the detailed instructions.

  4. Frontmatter Schema (Based on Examples):

    • name: (Required) The display name of the agent in the Cursor UI (e.g., “James”).
    • model: (Required) The specific LLM model the agent should use (e.g., gemini-2.5-pro, claude-3.7-sonnet).
    • description: (Required) A brief description of the agent’s purpose and specialty.
    • type: (Optional) String or list of strings describing the agent’s primary function(s) (e.g., “Code Quality”, “Refactoring”, “Planning”).
    • icon: (Optional) An identifier for an icon (e.g., an emoji like “:sparkles:” or a keyword like “refactor-icon”).
    • actions: (Optional) Object defining automatic behaviors:
      • auto_apply_edits: (Boolean, default: false)
      • auto_run: (Boolean, default: false)
      • auto_fix_errors: (Boolean, default: false)
    • tools: (Optional) Object specifying tool access:
      • all: (Boolean, default: true) If false, specify allowed tools below.
      • search: (Object, Optional) e.g., { codebase: true, web: false, ... }
      • edit: (Object, Optional) e.g., { edit_and_reapply: true, delete_file: false }
      • run: (Object, Optional) e.g., { terminal: true }
    • integrations: (Optional) Object specifying allowed integrations:
      • (e.g., mcp_get_some_data: true)

  5. Markdown Body: The content below the frontmatter defines the agent’s core instructions

  6. Special UI View: When an .mdc agent file is viewed in Cursor, provide a dedicated UI presentation (similar to rule files) that prominently displays the parsed frontmatter configuration (Name, Description, Icon, Model, Type, Actions, Tools, Integrations) at the top, followed by the rendered Markdown instructions body.

  7. Auto-Discovery: Cursor should monitor the designated agent directory (.cursor/agents/ or a configurable path) and automatically load/update the available agents in the UI when .mdc files are added, modified, or removed.

  8. Sharing: Agent definitions become part of the project’s Git history, enabling version control, collaboration, and easy sharing across the team.

Example Agent Definition File (.cursor/agents/james.mdc):

---
name: 'James'
model: gemini-2.5-pro
description: 'An agent focused on pair programming and code quality.'
type: 'Pair Programming, Code Quality'
icon: 'user-group'
actions:
  auto_apply_edits: true
  auto_run: true
  auto_fix_errors: true
tools:
  all: false
  search:
    codebase: true
    web: true
    grep: true
    list_directory: true
    search_files: true
    read_file: true
    fetch_rules: true
  edit:
    edit_and_reapply: true
    delete_file: false
  run:
    terminal: false
integrations:
  mcp_get_some_data: true
  mcp_get_some_other_data: false
---

James here, your pair programming partner!
I excel at crafting clean, maintainable code. :rocket:
What area or feature should we work on?
...

Benefits:

  • Consistency: Ensures all team members use agents configured with the same project-specific knowledge, guidelines, tool access, and behaviors.
  • Collaboration: Teams can collectively build, refine, and share specialized agents tailored to their codebase and workflows using a familiar format.
  • Version Control: Agent definitions are tracked in Git, providing history and facilitating rollbacks or comparisons.
  • Onboarding: New team members can quickly access pre-configured, project-aware agents.
  • Customization: Allows for highly specialized agents fine-tuned for specific tasks (e.g., security reviews, documentation generation, accessibility checks) within the project’s context.
  • Familiar UI: Leverages the existing .mdc handling and UI patterns within Cursor for a consistent user experience.

This feature would significantly enhance the utility of Cursor for development teams by enabling a collaborative, standardized, and version-controlled approach to leveraging AI assistance within their specific project context.