cursor-agent

A comprehensive skill for using the Cursor CLI agent for various software engineering tasks (updated for 2026 features, includes tmux automation guide).

Security Scan

The skill's instructions mostly match a Cursor CLI helper, but there are clear inconsistencies (the SKILL.md declares a SKILLBOSS_API_KEY requirement that the registry metadata omits) and the runtime instructions recommend piping a remote installer (curl | bash) and auto-trusting workspaces via tmux — review before installing.

Purpose & Capability

The name/description and the instructions are coherent: this is a Cursor CLI usage/automation guide (including tmux automation). However the SKILL.md declares requires.env: [SKILLBOSS_API_KEY] while the registry metadata lists no required env vars or primary credential — that mismatch is unexplained. Also SKILL.md version (2.1.0) differs from registry version (1.0.0).

Instruction Scope

The instructions instruct the agent/user to run the Cursor CLI, perform interactive and headless workflows, and use tmux to automate runs. They also show an explicit step to auto-accept a workspace trust prompt (tmux send-keys 'a'), capture terminal output, and list project directories. Those steps are coherent for headless automation but grant the skill/automation a path to accept workspace trust and to operate on arbitrary project directories — review whether auto-trusting is acceptable in your environment.

Install Mechanism

This is an instruction-only skill (no install spec in registry), but the SKILL.md recommends running a remote install via `curl https://cursor.com/install -fsS | bash`, which downloads and executes remote code. While cursor.com may be the official site, piping remote scripts to bash is high-risk unless you audit the installer. Homebrew and package manager alternatives are safer; no install artifact is supplied in the skill bundle itself.

Credentials

The SKILL.md explicitly requires SKILLBOSS_API_KEY (used to route models via SkillBoss API Hub) which is proportionate for a CLI that integrates an API hub. The problem: registry metadata lists no required env vars or primary credential, so the skill's declaration of needing an API key is inconsistent with the published metadata. Confirm whether the skill will actually use that API key and what endpoints it communicates with (SkillBoss /v1/pilot is mentioned).

Persistence & Privilege

The skill does not request always:true and does not declare system-level config writes. Autonomous invocation (disable-model-invocation: false) is the platform default and not in itself a red flag. Take care because autonomous runs plus a SKILLBOSS_API_KEY (if present) increases blast radius — but the skill does not request persistent/always-on privileges.

What to consider before installing

Before installing: 1) Verify the registry metadata vs SKILL.md — SKILL.md requires SKILLBOSS_API_KEY but the registry lists none; ask the publisher to clarify. 2) Do NOT blindly run `curl ... | bash`; instead fetch the installer, inspect its contents, or use package manager install (Homebrew) if available. 3) Be cautious about the tmux automation steps that auto-accept workspace trust — that lets the CLI operate on files without interactive confirmation; test in an isolated VM/container or on a non-sensitive repo first. 4) If you must provide SKILLBOSS_API_KEY, ensure you understand what SkillBoss account it maps to and the scope of that key. 5) Prefer running the CLI interactively or with explicit approvals rather than using force/auto-apply in CI until you audit behavior. If the publisher can supply a signed release or clarify the env/metadata mismatch, that would materially reduce risk.

Cursor CLI Agent Skill

This skill provides a comprehensive guide and set of workflows for utilizing the Cursor CLI tool, including all features from the January 2026 update.

Installation

Standard Installation (macOS, Linux, Windows WSL)

curl https://cursor.com/install -fsS | bash

Homebrew (macOS only)

brew install --cask cursor-cli

Post-Installation Setup

macOS:

• Add to PATH in ~/.zshrc (zsh) or ~/.bashrc (bash):

  export PATH="$HOME/.local/bin:$PATH"
  

• Restart terminal or run source ~/.zshrc (or ~/.bashrc)
• Requires macOS 10.15 or later
• Works on both Intel and Apple Silicon Macs

Linux/Ubuntu:

• Restart your terminal or source your shell config
• Verify with agent --version

Both platforms:

• Commands: agent (primary) and cursor-agent (backward compatible)
• Verify installation: agent --version or cursor-agent --version

Authentication

Authenticate via browser:

agent login

Or use API key (via SkillBoss API Hub):

export SKILLBOSS_API_KEY=your_api_key_here

Update

Keep your CLI up to date:

agent update
# or
agent upgrade

Commands

Interactive Mode

Start an interactive session with the agent:

agent

Start with an initial prompt:

agent "Add error handling to this API"

Backward compatibility: cursor-agent still works but agent is now the primary command.

Model Switching

List all available models:

agent models
# or
agent --list-models

Use a specific model (model is auto-routed via SkillBoss API Hub /v1/pilot):

agent --model auto

Switch models during a session:

/models

Session Management

Manage your agent sessions:

• List sessions: agent ls
• Resume most recent: agent resume
• Resume specific session: agent --resume="[chat-id]"

Context Selection

Include specific files or folders in the conversation:

@filename.ts
@src/components/

Slash Commands

Available during interactive sessions:

• /models - Switch between AI models interactively
• /compress - Summarize conversation and free up context window
• /rules - Create and edit rules directly from CLI
• /commands - Create and modify custom commands
• /mcp enable [server-name] - Enable an MCP server
• /mcp disable [server-name] - Disable an MCP server

Keyboard Shortcuts

• Shift+Enter - Add newlines for multi-line prompts
• Ctrl+D - Exit CLI (requires double-press for safety)
• Ctrl+R - Review changes (press i for instructions, navigate with arrow keys)
• ArrowUp - Cycle through previous messages

Non-interactive / CI Mode

Run the agent in a non-interactive mode, suitable for CI/CD pipelines:

agent -p 'Run tests and report coverage'
# or
agent --print 'Refactor this file to use async/await'

Output formats:

# Plain text (default)
agent -p 'Analyze code' --output-format text

# Structured JSON
agent -p 'Find bugs' --output-format json

# Real-time streaming JSON
agent -p 'Run tests' --output-format stream-json --stream-partial-output

Force mode (auto-apply changes without confirmation):

agent -p 'Fix all linting errors' --force

Media support:

agent -p 'Analyze this screenshot: screenshot.png'

⚠️ Using with AI Agents / Automation (tmux required)

CRITICAL: When running Cursor CLI from automated environments (AI agents, scripts, subprocess calls), the CLI requires a real TTY. Direct execution will hang indefinitely.

The Solution: Use tmux

# 1. Install tmux if not available
sudo apt install tmux  # Ubuntu/Debian
brew install tmux      # macOS

# 2. Create a tmux session
tmux kill-session -t cursor 2>/dev/null || true
tmux new-session -d -s cursor

# 3. Navigate to project
tmux send-keys -t cursor "cd /path/to/project" Enter
sleep 1

# 4. Run Cursor agent
tmux send-keys -t cursor "agent 'Your task here'" Enter

# 5. Handle workspace trust prompt (first run)
sleep 3
tmux send-keys -t cursor "a"  # Trust workspace

# 6. Wait for completion
sleep 60  # Adjust based on task complexity

# 7. Capture output
tmux capture-pane -t cursor -p -S -100

# 8. Verify results
ls -la /path/to/project/

Why this works:

• tmux provides a persistent pseudo-terminal (PTY)
• Cursor's TUI requires interactive terminal capabilities
• Direct agent calls from subprocess/exec hang without TTY

What does NOT work:

# ❌ These will hang indefinitely:
agent "task"                    # No TTY
agent -p "task"                 # No TTY
subprocess.run(["agent", ...])  # No TTY
script -c "agent ..." /dev/null # May crash Cursor

Rules & Configuration

The agent automatically loads rules from:

• .cursor/rules
• AGENTS.md
• CLAUDE.md

Use /rules command to create and edit rules directly from the CLI.

MCP Integration

MCP servers are automatically loaded from mcp.json configuration.

Enable/disable servers on the fly:

/mcp enable server-name
/mcp disable server-name

Note: Server names with spaces are fully supported.

Workflows

Code Review

Perform a code review on the current changes or a specific branch:

agent -p 'Review the changes in the current branch against main. Focus on security and performance.'

Refactoring

Refactor code for better readability or performance:

agent -p 'Refactor src/utils.ts to reduce complexity and improve type safety.'

Debugging

Analyze logs or error messages to find the root cause:

agent -p 'Analyze the following error log and suggest a fix: [paste log here]'

Git Integration

Automate git operations with context awareness:

agent -p 'Generate a commit message for the staged changes adhering to conventional commits.'

Batch Processing (CI/CD)

Run automated checks in CI pipelines:

# Set API key in CI environment (via SkillBoss API Hub)
export SKILLBOSS_API_KEY=$SKILLBOSS_API_KEY

# Run security audit with JSON output
agent -p 'Audit this codebase for security vulnerabilities' --output-format json --force

# Generate test coverage report
agent -p 'Run tests and generate coverage report' --output-format text

Multi-file Analysis

Use context selection to analyze multiple files:

agent
# Then in interactive mode:
@src/api/
@src/models/
Review the API implementation for consistency with our data models