cursor-agent-cli
npx machina-cli add skill yu-iskw/coding-agent-skills/cursor-agent-cli --openclawexecuting-cursor-agent
Purpose
Use this skill to perform coding, research, or automation tasks using the cursor-agent CLI. It leverages Cursor's native execution modes to balance autonomy with safety.
Execution Modes
| Mode | Flag | Capability | Approval Required | Typical Tasks |
|---|---|---|---|---|
| Plan | --mode plan | Read-only analysis, research, and planning. | No | Code audits, architectural planning. |
| Ask | --mode ask | Q&A style for explanations and questions. | No | Explaining code, searching documentation. |
| Default | (none) | Full access (edits + shell execution). | Yes | Feature implementation, bug fixes. |
Implementation Workflow
1. Analyze & Classify
Analyze the user's intent to determine the appropriate mode.
- Plan Mode: Does the task only involve analyzing the codebase or proposing a plan without making changes?
- Ask Mode: Is the user asking a specific question or seeking an explanation?
- Default Mode: Does the task require modifying files or running shell commands?
2. Security Protocol
If the task requires Default Mode, you MUST obtain user approval before execution, as cursor-agent has full access to tools like bash and write.
Use the AskQuestion tool to confirm:
"I've detected that this task requires full agent permissions to modify files and execute commands. OK to proceed with
cursor-agent?"
3. Execution
Execute cursor-agent using the determined mode. Use --print for non-interactive output suitable for the calling agent.
# Plan Mode
cursor-agent --print --mode plan "<prompt>"
# Ask Mode
cursor-agent --print --mode ask "<prompt>"
# Default Mode (requires approval)
cursor-agent --print "<prompt>"
4. Advanced Commands
MCP Management
cursor-agent mcp list: View configured MCP servers.cursor-agent mcp list-tools <id>: Inspect tools available in a specific MCP.
Rule Generation
cursor-agent generate-rule: Create new.cursorrulesor project-specific rules.
Configuration
This skill uses native cursor-agent flags. Ensure CURSOR_API_KEY is set in the environment if required, or run cursor-agent login first.
Examples
Refer to references/usage-examples.md for concrete scenarios.
Source
git clone https://github.com/yu-iskw/coding-agent-skills/blob/main/skills/cursor-agent-cli/SKILL.mdView on GitHub Overview
Use the Cursor Agent CLI to perform coding, research, or automation tasks. It provides structured modes—Plan for analysis, Ask for explanations, and Default for full automation—each with guardrails and explicit approval when needed.
How This Skill Works
The skill selects the appropriate Cursor Agent mode based on the task intent. Plan uses --mode plan for read-only analysis, Ask uses --mode ask for explanations, and Default enables full edits (requiring prior approval). Advanced commands include MCP management (cursor-agent mcp list, cursor-agent mcp list-tools <id>) and rule creation (cursor-agent generate-rule). Use --print to surface non-interactive output during execution.
When to Use It
- Plan or audit a codebase to propose architecture or improvements (Plan mode).
- Ask questions or get explanations about code or documentation (Ask mode).
- Implement features or fix bugs that require file edits or shell commands (Default mode, requires approval).
- Inspect MCP configurations or available tools to understand the tooling environment (MCP list / MCP list-tools).
- Create or update project-specific rules for Cursor (generate-rule) to enforce policies.
Quick Start
- Step 1: Decide the mode (plan, ask, or default) and craft your prompt.
- Step 2: Run the appropriate command with --print for Plan or Ask, e.g., cursor-agent --print --mode plan "<prompt>".
- Step 3: If using Default Mode, obtain explicit approval before executing: cursor-agent --print "<prompt>".
Best Practices
- Decide the mode (plan, ask, or default) before issuing a command.
- For Default Mode, obtain explicit user approval prior to execution.
- Use --print to capture non-interactive output suitable for downstream processing.
- Validate intent in Plan or Ask before applying changes in Default.
- Leverage MCP management and rule-generation commands to manage tools and safety rules.
Example Use Cases
- Plan a backend refactor: run cursor-agent --print --mode plan '<prompt>' to audit dependencies and propose an architecture.
- Explain a complex API: use cursor-agent --print --mode ask '<prompt>' to get step-by-step explanations.
- Implement a bug fix: after approval, run Default mode to modify files and run tests via cursor-agent.
- Inventory tools: cursor-agent mcp list followed by cursor-agent mcp list-tools <id> to inspect capabilities.
- Create project rules: run cursor-agent generate-rule to add or update .cursorrules for a repo.
