Agent skill · software engineering · jeremylongshore
obsidian-reference-architecture
Implement Obsidian reference architecture with best-practice project
Why this skill is useful
Provides a detailed modular project structure and specific TypeScript patterns for developing Obsidian plugins that the AI wouldn't reliably generate on its own.
What it needs
Requires esbuild, typescript installed locally. About 6k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
Obsidian Reference Architecture Overview Architecture patterns for complex Obsidian plugins: modular project structure with separate files for views, commands, settings, and services; state management; a service layer for vault operations; command registry; view manager; and CSS scoping. Prerequisites TypeScript and Obsidian API familiarity Working build pipeline (esbuild recommended) Plugin scaffolding complete (manifest.json, package.json, tsconfig.json) Instructions Step 1: Project Structure Step 2: Thin Main Entry Point Step 3: Command Registry Pattern Step 4: View Manager Step 5: Service Layer for Vault Operations Step 6: Settings Architecture Step 7: CSS Architecture with Plugin-Scoped Classes Key CSS rules: Prefix every class with your plugin id to avoid collisions Use Obsidian CSS variables (--text-normal, --background-modifier-hover, etc.) for theme compatibility Use .is-mobile for mobile-specific overrides Never use !important — it breaks theme compatibility Step 8: State Management Pattern For plugins with complex state (multiple views, background sync, shared data): Output Modular src/ directory with separate folders for commands, views, settings, and services Thin main.ts that wires components together without implementing business logic Command registry that scales to dozens of commands without cluttering main.ts View manager with proper lifecycle (onOpen/onClose) and leaf management Service layer abstracting vault operations behind a clean API Type-safe settings with defaults and migration support Plugin-scoped CSS using Obsidian's CSS variable system Error Handling Issue Cause Solution ------- ------- ---------- Circular dependencies Services importing main, main importing services Use type imports or interface segregation Missing types at runtime Interface-only imports Create types.ts for shared interfaces Event listener leaks Direct addEventListener calls Use this.registerEvent() for automatic cleanup Settings lost on upgrade No migration path Vers …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/obsidian-reference-architecture--6e04c5