nexus-mobile-compat
Skill158 starsChanged 10 days agoMITView on GitHub
Keep Nexus loading on mobile and compliant with the Obsidian plugin store — vet a dependency, import without crashing init, confine a vault path, and prove none of it regressed with the reachability checker. Use before adding an npm package or a Node import, when writing to caller-supplied vault paths, when gating a desktop-only feature, when a PDF or worker-backed feature misbehaves, or when the plugin fails to load on a phone.
In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- nexus-agentsSkill
- nexus-eval-harnessSkill
- nexus-llm-adaptersSkill
- nexus-model-evalSkill
- nexus-model-updatesSkill
- nexus-releaseSkill
- nexus-storageSkill
- nexus-testingSkill
- nexus-tool-schemasSkill
- nexus-ui-mockupsSkill
- nexusSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 33
Read the protocol the table names, in full, before editing anything.
- Very specific: line 61
NEVER treat obsidian dev:mobile on as evidence of mobile safety.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Nexus mobile & plugin-store safety
Nexus ships isDesktopOnly: false, so main.js runs on phones with no Node.js.
The defect this skill exists to prevent has no compiler and no type behind it: a
static import executes during module init, before any Platform.isDesktop
check, so one import on the startup path takes the plugin down at launch on every
phone — from a diff that looks unrelated.
The reachability checker below is now wired into the repo's own gate: npm run
lint runs lint:obsidian (ESLint) then lint:mobile (this checker), and npm
run build runs npm run lint first. A violation fails the build. Run the
checker directly anyway while you work — the gate is the floor, not the loop.
Workflow
Pick the row that matches the job and follow that protocol. Do not improvise from this page; each protocol carries the steps and the checks.
| Situation | Protocol |
| Adding or upgrading an npm package | protocols/vet-a-dependency.md |
| Need a Node built-in, a heavy module, or a desktop-only feature | protocols/import-without-crashing.md |
| Writing, reading or deleting at a caller-supplied vault path | protocols/confine-a-vault-path.md |
| About to ship a change that touched imports or the startup path | protocols/verify-mobile-safety.md |
| "It won't load on my phone" / a mobile-only failure | protocols/diagnose-mobile-crash.md |
| Session that used this skill is ending | protocols/self-refine.md |
- Read the protocol the table names, in full, before editing anything.
Whatever the protocol, you MUST run the reachability checker before calling the change done — it is the only guard for this defect class:
node scripts/check-mobile-imports.mjs . # identical, the way the build invokes it: npm run lint:mobilescripts/check-mobile-imports.mjsin the repo IS the checker — one implementation, edit it there. It was a Python script behind a launcher until 2026-08-15, when Obsidian's community scorecard failed build verification on a clean container that has Node but no Python. A build gate may only depend on what the build already needs.It walks static imports from
src/main.ts, follows noawait import(), and exits non-zero when a Node built-in is reachable from init. Run--helpfor--trace <file>(is this module on the startup path, and via what chain) and--packages(which npm packages init loads).npm run lintnow runs both halves: ESLint for the store rules that are mechanical, then the reachability checker. A green ESLint says nothing about reachability, and a green checker says nothing about the store rules — which is why the composed script runs both, and whynpm run buildcalls it. ESLint additionally hard-errors on Node built-in and Node-dependent package imports undersrc/settings/components/**(issue #221): those shared UI primitives are reachable from init today, but the per-file ban holds even if the import graph shifts. The blocklists are theMOBILE_BANNED_*arrays at the top ofeslint.config.mjs; widen the guard by adding a glob to that block'sfiles.- NEVER treat
obsidian dev:mobile onas evidence of mobile safety. It emulatesPlatform.isMobile, touch and layout inside Electron, whererequire('fs')still resolves — this crash class cannot reproduce there. Seereferences/init-order.md.
Map
protocols/the procedures above, each ending at the next one.references/read on demand:init-order.md(why a platform guard below an import is decoration, and what reachability really guarantees),plugin-store-rules.md(the store rules and which are already lint-enforced),pdfjs-in-electron.md(the worker constraint and the single sanctioned entry).- The import-graph checker lives in the repo, not here:
scripts/check-mobile-imports.mjs. Run it; do not reimplement it as a grep — grep cannot see reachability, and this repo has known-correct hits that a grep reports as violations.
Boundaries
The full store guidance lives in docs/obsidian-plugin-guidelines.md; this skill
is the part that bites in practice. Test lanes, the in-app Obsidian CLI loop and
mock-versus-real questions belong to nexus-testing. Storage roots, the event
store and migrations belong to nexus-storage. Release packaging belongs to
nexus-release.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

