agentleFS
ProfSynapseProfSynapse/nexus/.claude/skills/nexus-mobile-compat/SKILL.md

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.

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
  1. Distinctive:

    Read the protocol the table names, in full, before editing anything.

    line 33
  2. Very specific:

    NEVER treat obsidian dev:mobile on as evidence of mobile safety.

    line 61

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

SituationProtocol
Adding or upgrading an npm packageprotocols/vet-a-dependency.md
Need a Node built-in, a heavy module, or a desktop-only featureprotocols/import-without-crashing.md
Writing, reading or deleting at a caller-supplied vault pathprotocols/confine-a-vault-path.md
About to ship a change that touched imports or the startup pathprotocols/verify-mobile-safety.md
"It won't load on my phone" / a mobile-only failureprotocols/diagnose-mobile-crash.md
Session that used this skill is endingprotocols/self-refine.md
  1. Read the protocol the table names, in full, before editing anything.
  2. 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:mobile

    scripts/check-mobile-imports.mjs in 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 no await import(), and exits non-zero when a Node built-in is reachable from init. Run --help for --trace <file> (is this module on the startup path, and via what chain) and --packages (which npm packages init loads).

  3. npm run lint now 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 why npm run build calls it. ESLint additionally hard-errors on Node built-in and Node-dependent package imports under src/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 the MOBILE_BANNED_* arrays at the top of eslint.config.mjs; widen the guard by adding a glob to that block's files.
  4. NEVER treat obsidian dev:mobile on as evidence of mobile safety. It emulates Platform.isMobile, touch and layout inside Electron, where require('fs') still resolves — this crash class cannot reproduce there. See references/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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.