Cursor Commands Overview

This document explains precisely how the /adm-* custom commands work with Cursor. It covers discovery, invocation, structure, and execution flow.

What Are Cursor Commands?

Cursor supports custom slash commands — reusable prompts stored as Markdown files. When you type / in Cursor chat or Agent input, Cursor scans for commands and shows them in a dropdown.

Two locations:

Project commands: .cursor/commands/ — shared with your team via git
Global commands: ~/.cursor/commands/ — personal, machine-specific

The ADM Toolkit uses project commands in .cursor/commands/. Each file adm-*.md becomes the command /adm-*.

Discovery: How Cursor Finds Commands

You open the project in Cursor (the cursor-adm-toolkit folder).
You type / or /adm- in the chat input.
Cursor scans .cursor/commands/ for .md files.
The filename (without .md) becomes the command name:
- adm-research.md → /adm-research
- adm-roi.md → /adm-roi
- adm-help.md → /adm-help
Cursor shows a dropdown of matching commands with their descriptions.

No configuration required. If the folder exists and contains .md files, Cursor discovers them automatically.

Invocation: What Happens When You Run a Command

When you type:

/adm-research Adobe

or:

/adm-roi 2500 220000 Adobe

Cursor matches the command name to adm-research.md or adm-roi.md.
Cursor loads the full contents of that file into the conversation context.
The AI agent (the model in Cursor — Claude, GPT, etc.) receives:
- The command file content (objective, arguments, process, execution context)
- Your message (the part after the command)
The agent follows the process steps in the command file, using your message to populate arguments ($1, $2, $3, …).

The command file is injected as a system-like prompt — it tells the agent what to do and how to do it.

Command File Structure

Each command file has two parts: frontmatter (YAML) and body (Markdown with XML-like sections).

Frontmatter

---
name: adm-research
description: Research enterprise account — revenue, eng headcount, AI strategy
tools:
  read: true
  write: true
  web_search: true
---

Field	Purpose
`name`	Command identifier (usually matches filename). Shown in Cursor UI.
`description`	Short summary. Shown in the command dropdown.
`tools`	Permissions: `read`, `write`, `web_search`, `bash`, `ask_question`. Controls what the agent can do.

Body Sections

Section	Purpose
`<objective>`	High-level goal. What the command accomplishes.
`<arguments>`	Positional args: $1, $2, $3. Maps to words in the user's message.
`<execution_context>`	Files to load into context. Uses `@path` syntax.
`<process>`	Step-by-step instructions. The agent follows these.

Argument Mapping

The user's message is split on whitespace. Arguments map by position:

User types	$1	$2	$3
`/adm-research Adobe`	Adobe	—	—
`/adm-research Adobe deep`	Adobe	deep	—
`/adm-roi 2500 220000`	2500	220000	—
`/adm-roi 2500 220000 Adobe`	2500	220000	Adobe
`/adm-expansion 200 2000 Adobe`	200	2000	Adobe

If the user omits an optional argument, the command's process should handle it (e.g., read from STATE.md or prompt the user).

Execution Context: Loading Files

The <execution_context> section lists files to load when the command runs:

<execution_context>
@.cursor/get-adm-done/workflows/research-account.md
@.cursor/get-adm-done/templates/account.md
@.cursor/get-adm-done/references/research-sources.md
</execution_context>

@ means "include this file in context."
Paths are relative to the project root.
These files are read and injected into the agent's context before it executes the process.

This gives the agent:

Workflows — detailed step-by-step logic
Templates — output structure (e.g., ACCOUNT.md format)
References — search patterns, benchmarks, caveats

Subagents: The "Spawn" Pattern

Many ADM commands instruct the agent to spawn a subagent:

## Step 2: Spawn Account Researcher
Spawn adm-account-researcher subagent with:
- Company name
- Depth level
- Web search enabled

How this works:

The main agent (the one handling your chat) reads the command and follows the process.
When it reaches "Spawn adm-account-researcher," it uses Cursor's subagent capability (Agent mode / Plan mode).
Cursor looks for an agent definition: .cursor/agents/adm-account-researcher.md.
A subagent runs with that definition, the provided context, and the specified task.
The subagent produces output (e.g., writes ACCOUNT.md); control returns to the main agent.
The main agent continues with the next process step (e.g., "Display summary").

Agent files live in .cursor/agents/. Each defines:

<role> — persona (e.g., "enterprise account researcher")
<principles> — quality rules
<execution_flow> — steps the subagent follows
tools — read, write, web_search, etc.

The main agent does not execute the research itself; it delegates to the specialized subagent.

Data Flow

Location	Purpose
`.adm/accounts/{account}/`	Per-account data. One folder per company (e.g., `adobe`, `stripe`).
`.adm/STATE.md`	Active account, last-used context. Used when no account is specified.

Output files (written by commands):

ACCOUNT.md — company research
ROI.md — ROI model
DEPLOYMENT.md — deployment plan
HEALTH.md — health score
EXPANSION.md — expansion proposal
RISK.md — risk assessment
QBR-{quarter}.md — QBR brief
etc.

Commands read existing files for context and write new or updated files.

Tool Permissions

Each command declares which tools the agent can use:

Tool	Purpose
`read: true`	Read files (e.g., ACCOUNT.md, templates)
`write: true`	Create/update files (e.g., write ROI.md)
`web_search: true`	Run web searches (e.g., for account research)
`bash: true`	Run terminal commands (e.g., run CLI)
`ask_question: true`	Prompt the user for input (e.g., confirm inputs)

If a command needs web search (e.g., /adm-research), it must have web_search: true. The agent will not use tools not declared.

End-to-End Example: `/adm-research Adobe`

User types: /adm-research Adobe
Cursor loads: .cursor/commands/adm-research.md
Arguments: $1 = "Adobe", $2 = (default: standard)
Context loaded: research-account.md, account.md template, research-sources.md
Agent executes process:
- Step 1: Normalize company → "adobe", depth → "standard"
- Step 2: Spawn adm-account-researcher subagent with company=Adobe, depth=standard
- Subagent runs: reads research-sources.md, runs 5–8 web searches, extracts data, writes .adm/accounts/adobe/ACCOUNT.md
- Step 3: (Subagent completes)
- Step 4: Main agent displays: "Account research complete: Adobe. See .adm/accounts/adobe/ACCOUNT.md"

Summary

Concept	How It Works
Discovery	Cursor scans `.cursor/commands/*.md`. Filename = command name.
Invocation	User types `/adm-xyz args`. Cursor loads the file and injects it + user message into the agent.
Arguments	$1, $2, $3 map to space-separated words in the user's message.
Context	`@path` in execution_context loads workflow, template, and reference files.
Subagents	"Spawn X" triggers a subagent defined in `.cursor/agents/X.md`.
Data	Commands read/write `.adm/accounts/{account}/*.md`.
Tools	Frontmatter `tools` controls read, write, web_search, bash, ask_question.

No MCP required. Commands work with Cursor's built-in Agent mode. MCP is optional for MongoDB persistence and automations.

What Are Cursor Commands?​

Discovery: How Cursor Finds Commands​

Invocation: What Happens When You Run a Command​

Command File Structure​

Frontmatter​

Body Sections​

Argument Mapping​

Execution Context: Loading Files​

Subagents: The "Spawn" Pattern​

Data Flow​

Tool Permissions​

End-to-End Example: /adm-research Adobe​

Summary​

See Also​