Skip to main content
skill CX Codex

obsidian-dev-rules — Claude Code skill: what it does, how to install

obsidian-dev-rules is a Claude Code skill with rules for building TypeScript plugins and CSS themes for Obsidian. It guides API usage and event cleanup.

MIT 317 installs ★ 107 updated 2026-10-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add Agents365-ai/365-skills --skill obsidian-dev-rules -a claude-code
Open on GitHub

What obsidian-dev-rules does

This skill provides development guidelines and API references for Obsidian plugins and themes directly from official documentation. It guides project setup around the obsidian package, covering the Plugin lifecycle (onload, onunload), command registration, views, and setting tabs. It also establishes DOM construction standards, barring dynamic innerHTML in favor of element helpers like createEl.

File access and editor rules prevent common vault bugs. The instructions require atomic file mutations through process instead of separate read and modify calls, and mandate editing active notes via the Editor interface to keep selections intact. Failing to register DOM events or timers via registerEvent leaves lingering listeners active long after disabling the plugin.

The skill also outlines directory submission requirements. It verifies manifest fields, confirms that release tags match the manifest version, and ensures assets like main.js are uploaded as separate files instead of zip archives.

What it helps with

  • build an Obsidian plugin with TypeScript
  • safely edit vault notes using the atomic process method
  • build plugin UI and settings without dynamic innerHTML
  • prepare release assets for the Obsidian community directory

Example prompts for the agent

  • Review this Obsidian plugin lifecycle to ensure no listeners leak on unload
  • Write a command that updates the active note selection via Editor API
  • Validate my plugin manifest.json and release structure before publishing

How to install obsidian-dev-rules

1Skills CLI (Vercel)

npx skills add Agents365-ai/365-skills --skill obsidian-dev-rules -a claude-code

2Manually: put the files in place

~/.claude/skills/obsidian-dev-rules/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/obsidian-dev-rules/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about obsidian-dev-rules

How to install obsidian-dev-rules in Claude Code?

Run npx skills add Agents365-ai/365-skills --skill obsidian-dev-rules -a claude-code. The rule set is placed in ~/.claude/skills/obsidian-dev-rules/SKILL.md.

What does obsidian-dev-rules do?

It guides the agent when creating Obsidian extensions and themes. The skill enforces correct Vault patterns, CodeMirror 6 extensions, workspace leaves, and teardown logic.

Why does the skill require process over read and modify?

The process method executes file reads and mutations atomically. This avoids data loss if external edits occur between separate read and write operations.

Source text

SKILL.md · MIT
---
disable-model-invocation: true
name: obsidian-dev-rules
description: Authoritative reference and rules for developing for Obsidian — building TypeScript plugins (Plugin lifecycle, manifest.json, commands, settings, modals, views, ribbon/status bar), the Vault and Editor APIs, the event system, Markdown post-processing & code-block processors, CodeMirror 6 editor extensions, building CSS themes (CSS variables, theme.css/manifest), and submitting plugins/themes to the community directory. Use whenever the user asks to build, debug, or review an Obsidian plugin or theme, work with the Obsidian API (Vault/Editor/Workspace/Plugin), register commands/views/events, process Markdown, or release/submit to the Obsidian community.
license: MIT
metadata: {"source":"https://docs.obsidian.md/Home","docVersion":"latest","fetched":"2026-05-24"}
---

# Obsidian Dev Rules

Obsidian is extended two ways: **plugins** (TypeScript against the Obsidian API) and **themes/snippets**
(CSS). This skill mirrors the official developer docs at https://docs.obsidian.md so you can build and
review Obsidian plugins/themes without re-fetching. The API ships as the `obsidian` npm package; the
canonical starting point is the [`obsidian-sample-plugin`](https://github.com/obsidianmd/obsidian-sample-plugin).

## When to use this skill

- Building, debugging, or reviewing an **Obsidian plugin** (lifecycle, commands, settings, UI, views).
- Reading/writing notes via the **Vault** API; manipulating the active note via the **Editor** API.
- Subscribing to **events**, registering **Markdown post-processors** / code-block processors, or
  **CodeMirror 6** editor extensions.
- Building a **theme** (CSS variables, `theme.css`, manifest) or snippets.
- **Releasing/submitting** a plugin or theme to the community directory.

## Reference index — load the file you need

| File | Covers |
|------|--------|
| `references/plugin-basics.md` | Project setup, `manifest.json`, Plugin lifecycle (`onload`/`onunload`), resource registration & cleanup, events, dev workflow / hot reload, debugging |
| `references/vault-and-editor.md` | Vault API (read/cachedRead/create/modify/process/delete, TFile/TFolder, adapter, normalizePath), Editor API, Markdown post-processing & code-block processors, CodeMirror 6 editor extensions |
| `references/ui.md` | Commands (callback variants, hotkeys), Settings (PluginSettingTab, load/saveData, Setting controls), Modals (Modal/SuggestModal/FuzzySuggestModal), Views (ItemView, registerView, workspace leaves), ribbon/status bar |
| `references/themes-and-release.md` | Themes (CSS variables, theme.css/manifest, body classes, snippets), submitting plugins & themes, developer policies & guidelines |

## Cheat sheet

```ts
import { Plugin, Notice, MarkdownView, TFile, normalizePath } from 'obsidian';

export default class MyPlugin extends Plugin {
  async onload() {
    await this.loadSettings();
    this.addRibbonIcon('dice', 'Greet', () => new Notice('Hello!'));
    this.addCommand({ id: 'do-x', name: 'Do X', callback: () => {/* ... */} });
    this.addSettingTab(new MySettingTab(this.app, this));
    // Auto-cleaned on unload — always register through these:
    this.registerEvent(this.app.vault.on('modify', (f) => {/* ... */}));
    this.registerInterval(window.setInterval(() => {/* ... */}, 1000));
    this.registerDomEvent(document, 'click', () => {/* ... */});
  }
  onunload() { /* release anything NOT registered via register*/ }
}
```

```ts
// Vault: prefer process() over read()+modify(); use cachedRead() for display only.
const file = this.app.vault.getFileByPath('Notes/x.md');
await this.app.vault.process(file, (data) => data.replace('foo', 'bar'));
// Editor of the active note (preserves cursor/selection):
const view = this.app.workspace.getActiveViewOfType(MarkdownView);
view?.editor.replaceSelection(view.editor.getSelection().toUpperCase());
```

**Plugin files**: `manifest.json` + `main.js` (+ optional `styles.css`) in `<vault>/.obsidian/plugins/<id>/`.
**Theme files**: `manifest.json` + `theme.css` in `<vault>/.obsidian/themes/<name>/`.

## Hard rules

- **Use `this.app`, never the global `app`** (global exists for debugging only and may be removed).
- **Register everything that needs teardown** via `registerEvent` / `registerInterval` /
  `registerDomEvent` / `addCommand` / `registerView` / `registerMarkdownPostProcessor` — Obsidian
  auto-cleans those on unload. Manually release anything else in `onunload()`. Leaked listeners/
  intervals degrade Obsidian after the plugin is disabled.
- **Never** use `innerHTML` / `outerHTML` / `insertAdjacentHTML` with dynamic content — build DOM with
  `createEl()` / `createDiv()` / `createSpan()`.
- **Prefer the Vault API over the Adapter API**; use `getFileByPath()` (not iterate-all); always
  `normalizePath()` user-supplied paths. Use **`process()`** (atomic) instead of sequential
  `read()`+`modify()` to avoid data loss; `cachedRead()` only when you won't write it back.
- **For the active note, edit via the Editor interface**, not `Vault.modify` — it preserves the
  cursor and selection.
- **Don't store references to view instances**; Obsidian may recreate them — fetch with
  `getLeavesOfType()` / `getActiveViewOfType()`.
- **Don't set default hotkeys** for distributed plugins (OS-dependent, conflict-prone). UI text is
  **sentence case**. Use CSS classes + Obsidian CSS variables, not hardcoded inline styles.
- **`manifest.json` required fields**: `id`, `name`, `version` (semver `x.y.z`), `minAppVersion`,
  `description`, `author`, `isDesktopOnly`. `id` must **not** contain "obsidian"; `name` is Basic-Latin,
  no emoji/punctuation except hyphens.
- **Release**: GitHub release whose **tag equals the manifest `version`**, with `main.js`,
  `manifest.json`, and optional `styles.css` attached as **individual binary assets** (not zipped).
- Use `async`/`await` (not Promise chains); `const`/`let` (not `var`).

© Agents365-ai · MIT · Agents365-ai/365-skills

Similar skills

All skills for Notes, tasks and projects →

From the same set33

The whole set →
assetseeker assetseeker searches online sources for photos, icons, video, music, sound effects, and fonts. Use it when a project needs licensed creative assets. CX Codex +1 494installs videogencn videogencn is a Claude Code skill that creates short clips from text, images, frame pairs, or references. It activates for video-generation requests and helps select a model. CX Codex +1 417installs journal-if The journal-if skill looks up and compares journal impact factors. Use it when checking a publication venue or assessing an IF value. CX Codex +1 413installs yt2bb yt2bb turns a YouTube video or playlist into a Bilibili-ready video with burned-in English and Chinese subtitles. Useful when adapting English-language material for a Chinese audience. CX Codex +1 407installs journal-meta journal-meta fetches complete paper metadata from a DOI, PMID, arXiv identifier or title: authors, journal, impact factor, citation count and abstract. CX Codex +1 317installs xfetch xfetch extracts public tweets, profiles, and likes from X using a local Python script and your session cookies. Avoids paid developer API keys for data scraping. CX Codex +1 316installs bbc-skill bbc-skill collects Bilibili video comments into JSONL with a JSON summary. Use it to gather feedback on one video or across an uploader’s videos. CX Codex +1 313installs scientific-thinking scientific-thinking is a skill for analyzing research findings, evaluating evidence, and constructing rigorous arguments. It separates facts from interpretations and calibrates conclusions to evidence quality. CX Codex +1 308installs

More in the catalog

Project sponsors

Companies that keep this analytics open