Provides development guidelines for creating Obsidian plugins, including boilerplate generation and API best practices.

Install

mkdir -p .claude/skills/obsidian && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/248" && unzip -o skill.zip -d .claude/skills/obsidian && rm skill.zip

Installs to .claude/skills/obsidian

Activation

This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.

Comprehensive guidelines for Obsidian.md plugin development including ESLint rules from eslint-plugin-obsidianmd v0.4.1, TypeScript best practices, memory management, API usage (requestUrl vs fetch), UI/UX standards, popout window compatibility, community.obsidian.md submission process, and Scorecard optimization. Use when working with Obsidian plugins, main.ts files, manifest.json, Plugin class, MarkdownView, TFile, vault operations, or any Obsidian API development.
471 chars✓ has a “when” triggerlonger than Claude Code's old 250-char listing cap (fine on current versions)
Intermediate

Key capabilities

  • →Generate new Obsidian plugin project boilerplate
  • →Validate plugin IDs and names against community rules
  • →Manage event listeners for automatic cleanup
  • →Use Editor API for active file edits
  • →Check `minAppVersion` for API availability
  • →Ensure popout window compatibility with `activeWindow`

How it works

The skill provides guidelines derived from official Obsidian ESLint plugin rules and submission requirements. It offers an interactive boilerplate generator for new plugin projects.

Inputs & outputs

You give it
User request to create a new plugin or a plugin code snippet
You get back
Generated boilerplate code or suggested code improvements based on guidelines

When to use obsidian

  • →Generate a new Obsidian plugin project boilerplate
  • →Validate plugin naming against community rules
  • →Optimize plugin code for memory and performance
  • →Prepare plugin for submission to community.obsidian.md

About this skill

Obsidian Plugin Development Guidelines

Follow these comprehensive guidelines derived from the official Obsidian ESLint plugin rules, submission requirements, and best practices.

Getting Started

Quick Start Tool

For new plugin projects, an interactive boilerplate generator is available:

  • Script: tools/create-plugin.js in the skill repository
  • Command: Invoke create-plugin using your agent's method (/create-plugin, $create-plugin, or @create-plugin)
  • Generates minimal, best-practice boilerplate with no sample code
  • Detects existing projects and only adds missing files

Recommend the boilerplate generator when users ask how to create a new plugin, want to start a new project, or need help setting up the basic structure.


Rules Reference (eslint-plugin-obsidianmd v0.6.0)

Submission & Naming

#Rule✅ Do❌ Don't
1Plugin IDOmit "obsidian"; don't end with "plugin" (checked only with validate-manifest's checkId: true — turn it on before first submission)Include "obsidian" or end with "plugin"; rename a published plugin's id
2Plugin nameOmit "Obsidian" and "Plugin"Include "Obsidian" or "Plugin" anywhere in the name
3Plugin nameAvoid parts of "Obsidian"Use "obsi", "sidian", or a leading "ob"
4DescriptionSay what it does; don't repeat or start with the nameUse "Obsidian", "This plugin", "A plugin that", or start with the name
5Description10–250 chars, ending with ., !, or ?End with ) or no punctuation

Memory & Lifecycle

#Rule✅ Do❌ Don't
6Event cleanupUse registerEvent() for automatic cleanupRegister events without cleanup
6aDOM eventsUse registerDomEvent() on the plugin or owning componentPair addEventListener with manual removeEventListener cleanup
7View referencesReturn views/components directlyStore view references in plugin properties or pass plugin as component to MarkdownRenderer
8Leaf detachmentLet Obsidian handle leaf cleanupCall detachLeavesOfType() in onunload

Type Safety

#Rule✅ Do❌ Don't
9TFile/TFolderUse instanceof for type checkingCast to TFile/TFolder; use any; use var
10DOM instanceofUse .instanceOf(T) for DOM Nodes/UIEvents; e.targetNode?.instanceOf(T) for event targetsUse instanceof for cross-window DOM checks, including e.target instanceof HTMLElement

UI/UX

#Rule✅ Do❌ Don't
11UI textSentence case — "Advanced settings"; add your own terms with acronyms (adds to the built-in list) and brands (replaces it)Title Case — "Advanced Settings"
12JSON localeSentence case in JSON locale files (recommendedWithLocalesEn)Title case in locale JSON
13TS/JS localeSentence case in TS/JS locale modulesTitle case in locale modules
14Command namesOmit "command" as a redundant label; "Run command" or copy-command-id (what the command acts on) is fineAdd "command" as a label — "Command: open note", "Open settings command"
15Command IDsOmit plugin ID/name from command IDs/namesDuplicate plugin ID in command IDs
16HotkeysNo default hotkeysSet default hotkeys
16acheckCallbackRead checking and run the action only when it is false (commands/check-callback-uses-checking); use callback if the command is always availableIgnore checking — the action runs every time Obsidian asks whether the command is available
17Settings headingsUse .setHeading()Create manual HTML headings; use "General", "settings", or plugin name in headings
17eAwaiting SettingBuild a Setting or component chain without awaitawait new Setting(...) or return one from an async function — its chaining then() never settles and the app hangs (no-await-chainable, error)

Note (v0.5.0): ui/sentence-case is off in recommended (and the scanner doesn't run it) — sentence case is still the convention, so opt in with "obsidianmd/ui/sentence-case": ["warn", { enforceCamelCaseLower: true }]. recommendedWithLocalesEn checks English locale files (rules 12–13).

Declarative Settings (1.13.0+)

All four settings-tab rules ship as warn in recommended. Rules 17a/17c/17d read minAppVersion from manifest.json; 17b is not version-gated.

#Rule✅ Do❌ Don't
17asettings-tab/require-displayKeep display() when minAppVersion < 1.13.0Ship declarative-only settings that render nothing on older Obsidian
17bsettings-tab/prefer-setting-definitionsImplement getSettingDefinitions() on every PluginSettingTabRely on display() alone — settings won't appear in 1.13+ global search
17csettings-tab/prefer-update-over-displayCall this.update() to re-render declarative settingsCall this.display() — it's bypassed when definitions are non-empty
17dsettings-tab/no-deprecated-displayDelete display() once minAppVersion >= 1.13.0 and definitions existLeave a dead display() behind (auto-fixable)
—Settings dataKeep all persisted data inside plugin.settingsStore sibling keys via saveData() — auto-persist clobbers them

Detection caveat: these rules match a bare extends PluginSettingTab only. extends obsidian.PluginSettingTab is out of scope and won't be flagged — but the underlying guidance still applies.

API Best Practices

#Rule✅ Do❌ Don't
18Active file editsUse Editor APIUse Vault.modify() for active file edits
19Background file modsUse Vault.process()Use Vault.modify() for background modifications
20File deletionUse FileManager.trashFile() (1.6.6+), which follows the user's "Deleted files" settingUse Vault.trash() or Vault.delete() with a fixed destination
21File lookupUse Vault.getAbstractFileByPath()Iterate all files with Vault.getFiles().find()
22User pathsUse normalizePath()Hardcode .obsidian path; use raw user paths
23OS detectionUse Platform APIUse navigator.platform/userAgent
24Network requestsUse requestUrl()Use fetch()
24aResponse typingParse response.text and validate/cast once at the API boundaryPass response.json (typed any) into plugin code
25LoggingMinimize console logging; none in onload/onunload in productionUse console.log in onload/onunload
26Input suggestUse built-in AbstractInputSuggestCopy Liam's TextInputSuggest implementation
26aConfirm dialogsUse built-in ConfirmationModal (1.13.0+); use FileManager.promptForDeletion() to confirm and delete filesHand-build a Modal subclass with its own confirm/cancel button row
27API compatibilityCheck minAppVersion for API availability (e.g., getSettingDefinitions() 1.13.0, setCssProps() 1.1.7, instanceOf() 0.15.3)Use APIs not available in declared minAppVersion
28Language detectionUse Obsidian's getLanguage()Use localStorage.getItem('language') or i18next-browser-languagedetector

Popout Window Compatibility

#Rule✅ Do❌ Don't
29Document/WindowUse activeDocument and activeWindowUse global document and window
29aWindow-wide stateAdd and remove <body>/<html>/<head> classes, CSS variables, and styles in each window's document (window-open + open windows)document.body.addClass() (main window only) or activeDocument.body.addClass() (whichever window has focus)
29bGetter captureCapture activeDocument in a variable when the same document is needed laterCall activeDocument at setup and again at cleanup — it follows focus and may return different documents
30TimersUse window.setTimeout(), window.setInterval(), etc. (exception to rule 29); activeWindow.requestAnimationFrame() is fine for a popout's frames; set and clear a timer on the same windowUse bare setTimeout()/setInterval(), or activeWindow.setTimeout() — prefer-window-timers flags both; set a timer on one window and clear its ID on another
31Main workspace UIUse this.app.workspace.containerEl.ownerDocument from settingsUse activeDocument to update main workspace from settings window

Note (v0.6.0): prefer-active-doc warns in recommended. It reports the global document and offers an editor suggestion, not an autofix. Changes to document.body/documentElement/head get their own message and no suggestion (rule 29a) — except an element put in document.body only for a moment (a download link, a textarea for copying), which gets an activeDocument.body suggestion for all its document.body calls at once. document in a listener on the main window's document/window, as the fallback in activeDocument ?? document, and lookups of main-window-only UI (status bar, ribbons) are not reported. Test, tooling, and web worker files are exempt.

Note (v1.13.0): Settings now open in a new window. activeDocument from settings callbacks points to the settings window, not the main vault. Use this.app.workspace.containerEl.ownerDocument to target main workspace UI.

Note: activeDocument/activeWindow are dynamic getters that track the focused window. A listener added via activeDocument.addEventListener() at setup cannot reliably be removed via activeDocument.removeEventListener() at cleanup. Prefer registerDomEvent() (rule 6a), which captures the target at registration.

Event Handling

#Rule✅ Do❌ Don't
31Editor drop/pasteWhen

Content truncated.

When not to use it

  • →When developing plugins for platforms other than Obsidian.md
  • →When the project does not involve Obsidian API development

Limitations

  • →Guidelines are specific to Obsidian.md plugin development
  • →Rules are based on eslint-plugin-obsidianmd v0.4.1

How it compares

This skill provides specific, documented rules and a generator for Obsidian plugin development, unlike a manual approach that would require consulting multiple external documents.

Compared to similar skills

obsidian side by side with the closest alternatives in the catalog.

SkillInstallsUpdatedSafetyDifficulty
obsidian (this skill)294moNo flagsIntermediate
cursor-rules-config44moReviewIntermediate
drizzle2385moNo flagsIntermediate
zustand1135moNo flagsIntermediate

Try saying

Example prompts that trigger this skill in your AI assistant.

You might also like

cursor-rules-config

jeremylongshore

Configure .cursorrules for project-specific AI behavior. Triggers on "cursorrules", ".cursorrules", "cursor rules", "cursor config", "cursor project settings". Use when configuring systems or services. Trigger with phrases like "cursor rules config", "cursor config", "cursor".

428

drizzle

lobehub

Drizzle ORM schema and database guide. Use when working with database schemas (src/database/schemas/*), defining tables, creating migrations, or database model code. Triggers on Drizzle schema definition, database migrations, or ORM usage questions.

238873

zustand

lobehub

Zustand state management guide. Use when working with store code (src/store/**), implementing actions, managing state, or creating slices. Triggers on Zustand store development, state management questions, or action implementation.

113434

motion-canvas

davila7

Complete production-ready guide for Motion Canvas with ESM/CommonJS workarounds, full setup templates, and troubleshooting for programmatic video creation using TypeScript

58202

turborepo

vercel

Turborepo monorepo build system guidance. Triggers on: turbo.json, task pipelines, dependsOn, caching, remote cache, the "turbo" CLI, --filter, --affected, CI optimization, environment variables, internal packages, monorepo structure/best practices, and boundaries. Use when user: configures tasks/workflows/pipelines, creates packages, sets up monorepo, shares code between apps, runs changed/affected packages, debugs cache, or has apps/packages directories.

61191

shadcn-ui-setup

maneeshanif

Install and configure Shadcn/ui component library with Radix UI primitives, Aceternity UI effects, set up components, and manage the component registry. Use when adding Shadcn/ui to a Next.js project or installing specific UI components for Phase 2.

37194

Search skills

Search the agent skills registry