Why Cursor's Background Agent Ignores Custom Commands
Cursor's background agent ignores custom slash commands for one of two reasons, and they're easy to mix up because they look identical from the chat window. The first is a confirmed backend bug. The background agent runtime doesn't load commands stored in a repo's .cursor/commands/ folder, even though the editor's own UI highlights the slash command in yellow as if it recognized it. The second is by design. Commands and skills defined at the personal level, outside the repo, don't reach cloud sessions at all unless you turn on a specific sync setting, and most people never see the toggle. There's also a narrower gray area between the two, covered further down, for commands old enough to predate the sync setting entirely.
A forum thread from October 2025 captures the first case exactly. A user reported that /request-qa worked fine in a normal agent chat but got treated as plain text by the background agent, despite the UI's yellow highlight suggesting the command was recognized. A Cursor team member, Dean Rie, confirmed it was a backend problem, writing that "the Background Agent runtime isn't loading custom commands from .cursor/commands/, even though the frontend highlights them correctly." The thread's last update, from October 31, said the team was still investigating. No fix or workaround has been posted since.
Commands, skills, and a naming change that adds to the confusion
Cursor's documentation once described Custom Commands as their own thing, reusable prompts you'd save to a project or a personal library and trigger with a slash. That material now lives under the Skills docs instead, folded into a broader mechanism for teaching the agent workflows. Cursor also ships a built-in converter, /migrate-to-skills, that identifies "eligible rules and commands and converts them to skills automatically." Per the docs, it converts dynamic rules without glob patterns, plus "slash commands: both user-level and workspace-level commands, preserving their explicit invocation behavior."
That's a real, current feature, which means if your team set up custom commands any time before this rename, you're likely running a mix, with some slash triggers still old-style commands and others migrated into skills, behaving differently in a background session. This is worth checking before you assume you've found the October bug, because the newer system has a separate, better-documented failure mode.
The sync toggle nobody notices until an agent misses it
Skills can live in four places. .cursor/skills/ and .agents/skills/ inside the repo, or ~/.cursor/skills/ and ~/.agents/skills/ on your machine, outside any repo. The first pair ships with the codebase, so a cloud agent checking out the repo gets them along with everything else. The second pair doesn't. Cursor's docs are explicit about the fix, telling you to open Settings → Agents, then turn on Sync Skills for Cloud Agents under Context and Tools. Skip that step and those personal skills stay put; per the docs, unsynced local skills and anything in ~/.agents/skills/ never reach Cloud Agents, the Agents Window's remote SSH mode, or self-hosted workers.
Read that against how background agents build their context in the first place. The docs describe configuring environments with agent-led setup, a saved snapshot, or a Dockerfile in .cursor/environment.json, and that setup is what gives an agent, in the docs' own words, "full context on your codebase and organization." A personal command you saved to your home directory was never part of that build. It isn't broken. It was never in scope, provided it's actually in a format that build step knows how to sync.
That caveat matters, because the sync toggle's documentation covers exactly one folder, ~/.cursor/skills/, while ~/.agents/skills/ is documented as staying on your machine regardless of the toggle. It says nothing about ~/.cursor/commands/, the folder personal commands lived in before Skills existed. If your command predates the split and you never ran it through the migration step, flipping the sync toggle is untested territory, not a documented fix. The safer move is running /migrate-to-skills first, confirming the command reappears as a skill under ~/.cursor/skills/, and only then turning on the toggle.
What this looked like at one shop
A tooling repo can carry a personal command for years without anyone noticing where it actually lives. That's what happened at Salt & Anchor, a wholesale bakery-supply ordering system, where engineer Priya Wexford had written a /pr-checklist command long before Cursor split commands from skills. It stayed in ~/.cursor/commands/ because that's where it had always been. It walked through the team's release rules, things like no schema migration without a rollback script and no new external call without a timeout. Typing /pr-checklist in an interactive chat ran through the list every time.
She tagged Cursor's background agent on a GitHub issue asking it to add a rate limiter to an outbound webhook call, expecting the same checklist to run before it opened a PR. It didn't.
Priya, in the task thread: Did you run the PR checklist before opening this?
Agent: I don't have a command called pr-checklist available in this session. I added a timeout and basic retry logic to the webhook call based on the surrounding code's conventions.
Priya pasted the checklist's five bullet points straight into the task description and re-ran it. The agent applied all five without hesitation, because the task prompt is context every background session unambiguously receives, the same way it always has been. The command itself, sitting in a folder on her laptop, never made the trip. Whether turning on the sync toggle would have changed that is genuinely unclear. Cursor's docs describe that toggle syncing ~/.cursor/skills/ and ~/.agents/skills/. They say nothing about a command that was never migrated out of the old folder, which is exactly the state Priya's was still in.
Confirming which failure you've hit
Before assuming you're stuck with either the bug or the sync limitation, work through it in order.
- Check where the command lives.
.cursor/commands/or.cursor/skills/inside the repo ships with every clone, including whatever the background agent checks out. - If it's project-level and still missing, ask the agent directly. "Do you have a command called X available?" A background agent that says no to a command living in the repo is showing the same symptom as the October forum thread, not a sync problem.
- If it's personal-level, check the format before touching any toggle. Cursor's sync setting is documented for
~/.cursor/skills/only;~/.agents/skills/stays on your machine either way.cursor/commands/. A command still sitting in that old folder is in territory Cursor hasn't written about. The safer path is running/migrate-to-skillsto convert it first, confirming it lands in~/.cursor/skills/`, before you flip the sync toggle and expect it to matter. - Test the identical repo state in an interactive session. If the local agent runs the command and the background agent doesn't, and the command is checked into the repo, you've ruled out sync and you're looking at the unresolved bug.
If it's the sync gap, the fix is one settings toggle, once the command itself is in a format the toggle actually covers. If it's the project-level bug, there isn't a documented fix yet, and the honest answer is to move whatever the command was supposed to enforce into the task prompt itself until Cursor closes the report.
Retyping the checklist has a ceiling
Retyping the load-bearing rules into every task prompt is a real fix, and it's the one Cursor's own thread leaves you with. It also has a ceiling. It only covers whatever a person remembers to paste, for every task, every time, which is fine for one five-item checklist and breaks down once a team has a dozen commands like that. And it says nothing about facts that change faster than a markdown file gets edited, like which customer is escalating this specific bug, whether this exact webhook has broken for anyone before, or which account renewal makes the fix urgent this week versus next. A command file, loaded correctly, is still just what someone wrote down at some point in the past.
+ ChatGPT
issue filedagent taskPast that point, the fix isn't a better command, it's not depending on a locally-stored file reaching the right session at all. Modem keeps a live graph of accounts, people, and open issues built from Slack, support tickets, and sales calls. Through the Cursor integration, Modem can write the current facts, who's affected, how many times this has come up, what was already tried, directly into a background agent's task description at the moment the task is created, so there's no separate command or file that has to survive the trip. An agent working locally can query the same graph over Modem's MCP server instead of trusting a checklist that may or may not have loaded. We build Modem, and we're saying so up front. The free path stays a well-maintained, project-level command or skill, checked into the repo so it ships with every checkout, plus pasting the exceptions into the prompt by hand when the bug above still swallows it. That's the right call for teams where the facts change slowly enough that nobody minds retyping them. For the broader set of ways to get customer context in front of Cursor at all, see the six best tools for it, and for the related gap where AGENTS.md itself goes missing in a background session, see why Cursor's background agent skips AGENTS.md.
If your setup falls into the sync gap, flipping the toggle is real progress, but only once the thing waiting to sync is actually a skill and not a leftover file sitting in the old commands folder. Run /migrate-to-skills on anything still under ~/.cursor/commands/, confirm it lands in ~/.cursor/skills/, then turn on Sync Skills for Cloud Agents and try the background agent again. If that still comes up empty, or the command was already project-level to begin with, you're looking at the unresolved bug from the forum thread, and pasting the rule into the task by hand remains the only fix Cursor has confirmed works.
