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
npx skills add Agents365-ai/365-skills --skill obsidian-dev-rules -a claude-codeWhat 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
processmethod - 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-code2Manually: put the files in place
~/.claude/skills/obsidian-dev-rules/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/obsidian-dev-rules/
1Skills CLI (Vercel)
npx skills add Agents365-ai/365-skills --skill obsidian-dev-rules -a codex2Manually: put the files in place
.agents/skills/obsidian-dev-rules/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add Agents365-ai/365-skills --skill obsidian-dev-rules -a cursor2Manually: put the files in place
.cursor/skills/obsidian-dev-rules/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install Agents365-ai/365-skills plugins/obsidian-dev-rules/skills/obsidian-dev-rules2Manually: put the files in place
.github/skills/obsidian-dev-rules/SKILL.md1Skills CLI (Vercel)
npx skills add Agents365-ai/365-skills --skill obsidian-dev-rules -a gemini-cli2Platform CLI
gemini skills install https://github.com/Agents365-ai/365-skills --path plugins/obsidian-dev-rules/skills/obsidian-dev-rulesManually: put the files in place
.devin/skills/obsidian-dev-rules/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add Agents365-ai/365-skills --skill obsidian-dev-rules -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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