playbooks

home / skills / basedhardware / omi / agent-modes

agent-modes skill

/.cursor/skills/agent-modes

This skill guides you to choose and use Agent, Ask, Plan, and Debug modes to match tasks and workflows.

npx playbooks add skill basedhardware/omi --skill agent-modes

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
2.4 KB
---
name: agent-modes
description: "Guidance on choosing and using Cursor agent modes: Agent, Ask, Plan, and Debug. Use when selecting the right mode for a task or when explaining mode capabilities."
---

# Agent Modes Skill

Guidance on choosing and using the right agent mode for your task.

## When to Use

Use this skill when:
- Selecting the right mode for a task
- Explaining mode capabilities
- Switching between modes
- Understanding mode-specific workflows

## Mode Selection

### Agent Mode (Default)

**Best for:** Complex features, refactoring, autonomous exploration

**Use when:**
- Implementing features requiring multiple file changes
- Refactoring across codebase
- Clear, well-defined tasks
- Need autonomous exploration and fixes

**Example:**
- "Add a new API endpoint for goals"
- "Refactor authentication system"
- "Update components to new design system"

### Ask Mode

**Best for:** Learning, planning, read-only exploration

**Use when:**
- Learning about unfamiliar code
- Understanding system architecture
- Planning before implementation
- Exploring codebase structure

**Example:**
- "How does authentication work?"
- "Explain memory extraction flow"
- "What happens when user submits form?"

### Plan Mode

**Best for:** Complex features requiring planning

**Use when:**
- Complex features with multiple approaches
- Tasks touching many files/systems
- Unclear requirements
- Architectural decisions need review

**Example:**
- "Add user preferences system"
- "Implement real-time notifications"
- "Refactor data layer"

**Workflow:**
1. Agent asks clarifying questions
2. Researches codebase
3. Creates implementation plan
4. You review and edit plan
5. Click to build when ready

### Debug Mode

**Best for:** Tricky bugs, regressions

**Use when:**
- Bugs you can reproduce but can't figure out
- Race conditions and timing issues
- Performance problems
- Regressions

**Example:**
- "Audio streaming stops after 30 seconds"
- "Memory extraction fails for some conversations"
- "BLE connection drops intermittently"

**Workflow:**
1. Explore and hypothesize
2. Add instrumentation
3. Reproduce bug
4. Analyze logs
5. Make targeted fix
6. Verify and clean up

## Mode Switching

- Use mode picker dropdown
- Press `Cmd+.` (Mac) or `Ctrl+.` (Windows/Linux)
- Set keyboard shortcuts in settings

## Related Resources

- Rule: `.cursor/rules/agent-modes.mdc`
- Commands: `/plan`, `/ask`, `/debug`

Overview

This skill provides clear guidance on choosing and using the four agent modes: Agent, Ask, Plan, and Debug. It helps you match a mode to the task, explains mode-specific workflows, and shows when to switch modes for better outcomes. Use it to reduce friction when moving between exploration, planning, implementation, and bug fixing.

How this skill works

The skill describes the purpose and workflows for each mode and gives concrete signals that indicate which mode fits a task. It outlines step-by-step behaviors you can expect—how an agent autonomously explores, how Ask mode performs read-only analysis, how Plan mode creates multi-step strategies, and how Debug mode instruments and validates fixes. It also summarizes quick switching and shortcut options for fluid workflows.

When to use it

  • Selecting the right mode for a development task
  • Explaining mode capabilities to team members or collaborators
  • Preparing to implement a complex feature that needs planning
  • Diagnosing reproducible bugs or performance regressions
  • Exploring unfamiliar code or system architecture

Best practices

  • Start in Ask mode for unfamiliar code to gather context before changing files
  • Use Plan mode when requirements are unclear or multiple approaches exist and iterate on the plan with reviewers
  • Switch to Agent mode for autonomous, multi-file implementations once the plan is approved
  • Use Debug mode for reproducible issues: add instrumentation, reproduce, analyze logs, and apply targeted fixes
  • Use keyboard shortcuts or the mode picker to switch quickly and avoid mode-mismatch work

Example use cases

  • Add a new API endpoint spanning backend and client components — Plan, review, then Agent to implement
  • Understand how authentication flows work in a legacy codebase — Ask for read-only exploration
  • Refactor the data layer across many files with coordinated changes — Plan to design then Agent to execute
  • Investigate intermittent audio streaming drops — Debug to instrument, reproduce, and fix
  • Create a user preferences system with architectural trade-offs — Plan to outline options and gather feedback

FAQ

When should I start in Ask instead of Agent?

Start in Ask when you lack context or must avoid changing files. Use it to learn architecture, locate code paths, and form questions before making edits.

Can I switch modes mid-task?

Yes. Switch any time via the mode picker or keyboard shortcuts. Use Plan to design, Agent to implement, and Debug to troubleshoot as needed.