Microsoft's Cross-Tool Package Manager Silently Drops Your Cursor Rules at User Scope. The Fix Has Been Ready for Six Weeks (2026)

apm install -g --target cursor is supposed to put your rules where every other target’s global install puts them. For eight of the nine tools APM supports, it does. For Cursor, it silently writes agents, skills, and hooks to ~/.cursor/ — and zero instruction files. No error, no warning beyond a generic “partial support” notice. Issue #3054, filed against Microsoft’s apm repository on September 22, 2026, is the first time anyone wrote that gap down as a tracked bug rather than a known limitation — even though a working fix for it has existed since early August.

What APM Is, and Why the Gap Matters

APM — “Agent Package Manager” — is Microsoft’s answer to the fact that every AI coding tool wants its context in a different file, in a different format, at a different path. It’s npm for agent configuration: one apm.yml manifest declares your instructions, skills, agents, hooks, and MCP servers once, and apm install writes them out in each target’s native layout — Copilot, Claude Code, Grok Build, Cursor, OpenCode, Codex, Gemini, Windsurf, and Kiro, according to the project README. It has 3,877 GitHub stars and ships commits daily; this isn’t a weekend project. The whole pitch is portability: clone a repo, run apm install, and every agent in it is configured the same way regardless of which harness you personally use.

That pitch has one asterisk, and it’s Cursor at user scope. Run apm install -g --target cursor and APM’s own targets matrix documents the reason up front: “Partial. instructions is excluded at user scope; Cursor reads global rules from its Settings UI rather than from disk.” That’s the documented behavior. The bug is that it’s not actually why the files aren’t written — and it hasn’t reflected how Cursor’s rules system has worked for a while.

The Actual Mechanism, Per the Issue

Issue #3054 traces the real cause to a single line in APM’s target registry: KNOWN_TARGETS["cursor"] sets user_supported="partial" and unsupported_user_primitives=("instructions",). That flag makes for_scope(user_scope=True) drop the instructions primitive before any integrator code runs — so it’s not that Cursor rejects the files, it’s that APM never tries to write them for a global install.

The issue’s reporter (also the author of the stalled fix — more on that below) points out the actual contradiction: “Cursor already has a file-backed rules surface (.cursor/rules/*.mdc via the existing cursor_rules transform). Project-scope installs use that path; user-scope installs do not, because of the exclusion above. Docs that treat Cursor global rules as Settings-UI-only contradict Cursor’s documented .mdc rules layout.” In other words: apm install (project scope) already writes real .cursor/rules/*.mdc files that Cursor reads from disk. apm install -g (user scope) could write the identical files to ~/.cursor/rules/*.mdc using the exact same code path — it just never tries, because of a flag set for a reason that stopped being fully true once Cursor’s .mdc format became the documented project-rules surface.

Reproduce it yourself with any package that ships an .apm/instructions/ directory:

apm install -g --target cursor
ls ~/.cursor/rules/          # empty — or absent entirely
ls ~/.cursor/agents/         # populated
ls ~/.cursor/skills/         # populated

Same install, same package, three different outcomes depending on which primitive type you’re looking at. That asymmetry — agents and skills land, instructions don’t — is what makes the omission genuinely silent. There’s no missing-instructions warning distinct from the general “Cursor is partially supported” notice APM prints for every install, so a team relying on apm install -g to standardize rules across contributors’ machines gets agents and skills for free and has to notice, on their own, that the rules never showed up.

A Fix Existed. It Got Closed Unmerged.

Here’s the part that makes this more than a routine bug report: the fix already existed, and had for six weeks. PR #2506, opened August 6, 2026, does exactly what the September 22 issue asks for — it clears unsupported_user_primitives for Cursor, reuses the existing cursor_rules transform at user scope, and updates the docs and tests to match. Per the PR’s own validation log, 54 tests passed. It had reviewers assigned. It sat open for five weeks.

It was closed on September 12 — not rejected, but closed as part of what the issue calls an “issue-first intake reset”: a process change requiring every merged fix to trace back to a tracking issue opened before the PR, rather than the other way around. The PR’s author had done the work first and filed the paperwork second, which is a completely normal way to contribute to most open-source projects and, as of September, no longer accepted by this one. The issue exists so the PR can be reopened once a maintainer signs off on scope — the code doesn’t need to be rewritten, just re-sequenced through the new process.

If you maintain any package that other people install with apm install -g --target cursor, this is worth tracking rather than working around: once #3054 is accepted, #2506 (or its equivalent) should close the gap without you doing anything, since it’s a fix to the installer, not to your package. Until then, the practical workaround is apm compile -g, which the targets matrix documents as writing global instructions to ~/.cursor/AGENTS.md — a path Cursor does read automatically, just not the one the Settings UI or the .mdc rules system uses.

The Deeper Bug Neither Fix Touches

Both the PR and the issue are explicit that they’re not fixing everything. The PR’s out-of-scope note: “Fixing Cursor cloud-agent workspaces that are not under $HOME (Cursor-side resolution; document as a caveat).” That’s a reference to a separate, Cursor-side bug that predates APM entirely and sits one layer deeper than anything a package manager can patch around.

A Cursor forum thread from June 2026 has Cursor staff (Colin) explaining it directly: “The home directory of a Cloud Agent is /home/ubuntu, while checked-out code lives at /workspace. Rule resolution currently walks upward from the workspace, so it never reaches /home/ubuntu/.cursor/rules.” He adds the detail that makes this asymmetric rather than a blanket limitation: “We explicitly search the home directory for other configuration, such as skills, but don’t currently do so for rules.” A verified workaround (symlinking /home/ubuntu/.cursor to /.cursor via a Dockerfile RUN command in .cursor/environment.json) existed by August 1. No permanent fix has shipped as of this writing.

Cursor’s own docs paper over the gap rather than describing it. The Cloud Agent documentation states that “user-level hooks from ~/.cursor/hooks.json are also not available since cloud VMs don’t have access to your local home directory” — which is true of your local machine’s home directory, but silently elides that the cloud VM has its own home directory, one Cursor’s own skills-loading code already reads from. The docs describe a hard boundary; the actual mechanism is an incomplete path-resolution walk that happens to work for one primitive type and not another, for reasons that are implementation detail rather than security or architecture. It’s the same asymmetry as the APM bug, one layer down, and it’s the reason APM’s fix explicitly disclaims responsibility for it.

This matters more now than it did in June, because Cursor’s cloud/background-agent infrastructure is no longer a side feature. Projects, which shipped September 10, 2026, runs a coordinator agent “on its own computer in the cloud, so closing your laptop doesn’t stop it,” delegating work to subagents that run in the same cloud environment the background-agent rule-resolution bug applies to. Cursor’s own rules documentation doesn’t distinguish between local Agent chat, Background Agents, and Projects when describing how .cursor/rules gets loaded — it describes one unified system, and the cloud-VM home-directory gap is a caveat you only find by reading a support-forum thread from a different month.

What Actually Works Right Now

For anyone deploying rules to Cursor today, across either channel:

• Project-scope rules (.cursor/rules/*.mdc, committed to the repo) work everywhere — local Agent, Background Agents, and Projects all resolve them the same way, since they live under /workspace, not $HOME. This is the one path with no open issues attached to it.
• User-scope rules in a local Cursor install work fine for local Agent chat. apm install -g --target cursor won’t deploy them until #3054/#2506 lands; deploy manually or use apm compile -g to target ~/.cursor/AGENTS.md instead.
• User-scope rules for Cloud Agents or Projects don’t resolve at all unless you add the Dockerfile symlink workaround from the June forum thread, or move the content into project scope. Skills placed in the equivalent home-directory path do resolve — rules don’t, and there’s no user-facing signal that distinguishes the two until something you expected to be in context turns out not to be.

None of this is a case for avoiding either tool. It’s a case for checking which of the three loading paths — Settings UI, project .mdc, or cloud-agent home directory — your actual setup depends on, since APM’s own documentation and Cursor’s own documentation currently describe fewer paths than actually exist.

Related Reading

• AGENTS.md in Cursor: Complete Setup Guide (2026)
• AGENTS.md vs Cursor Project Rules (.mdc): Which to Use and How to Run Both (2026)
• Claude Code vs Cursor in 2026: An Honest Comparison for Working Developers

Browse real-world Cursor rule files and .mdc examples in our gallery.