obsidian-develop
Build, prototype, extend, debug and review Obsidian community plugins against a live vault: inspect the running app's UI, DOM, console and plugin state, prototype in the runtime, then verify each change with a build, reload and check loop. Use whenever the user is working on an Obsidian plugin, even when they just say "add a command", "make a sidebar view", "my settings tab is blank", "why isn't my view updating" or "get this ready for the community directory"; when they ask about the plugin API (obsidian.d.ts, Workspace, leaves, Vault, MetadataCache, FileManager, views, modals, settings tabs, CodeMirror 6 editor extensions, markdown post-processors, events); or when they want a running Obsidian instance's DOM, CSS, console or plugins inspected. Not for general note-taking, Obsidian Markdown syntax, themes without a plugin, or managing vault content (use ingest, to-vault or vault-recall for those).
- License 许可
- MIT
- 最近更新
- 2026-11-11
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- obsidian-develop
- description
- Build, prototype, extend, debug and review Obsidian community plugins against a live vault: inspect the running app's UI, DOM, console and plugin state, prototype in the runtime, then verify each change with a build, reload and check loop. Use whenever the user is working on an Obsidian plugin, even when they just say "add a command", "make a sidebar view", "my settings tab is blank", "why isn't my view updating" or "get this ready for the community directory"; when they ask about the plugin API (obsidian.d.ts, Workspace, leaves, Vault, MetadataCache, FileManager, views, modals, settings tabs, CodeMirror 6 editor extensions, markdown post-processors, events); or when they want a running Obsidian instance's DOM, CSS, console or plugins inspected. Not for general note-taking, Obsidian Markdown syntax, themes without a plugin, or managing vault content (use ingest, to-vault or vault-recall for those).
02 资源文件 22
- 参考文档evals/evals.json4.4 KB
- 脚本evals/fixtures/blank-settings-plugin/esbuild.config.mjs805 B
- 参考文档evals/fixtures/blank-settings-plugin/manifest.json211 B
- 参考文档evals/fixtures/blank-settings-plugin/package.json397 B
- 脚本evals/fixtures/blank-settings-plugin/src/main.ts783 B
- 脚本evals/fixtures/blank-settings-plugin/src/settings.ts1.2 KB
- 其他evals/fixtures/blank-settings-plugin/styles.css—
- 参考文档evals/fixtures/blank-settings-plugin/tsconfig.json563 B
- 脚本evals/fixtures/todo-plugin/esbuild.config.mjs805 B
- 参考文档evals/fixtures/todo-plugin/manifest.json207 B
- 参考文档evals/fixtures/todo-plugin/package.json398 B
- 脚本evals/fixtures/todo-plugin/src/main.ts500 B
- 脚本evals/fixtures/todo-plugin/src/settings.ts834 B
- 其他evals/fixtures/todo-plugin/styles.css—
- 参考文档evals/fixtures/todo-plugin/tsconfig.json563 B
- 参考文档references/api-map.md5.0 KB
- 参考文档references/lifecycle-and-cleanup.md3.8 KB
- 参考文档references/patterns.md7.3 KB
- 参考文档references/project-setup.md3.1 KB
- 参考文档references/review-checklist.md3.9 KB
- 参考文档references/runtime-inspection.md5.9 KB
- 脚本scripts/deploy.sh916 B
03 SKILL.md 正文
Obsidian plugin development
Turn a plain-language request into a plugin change that works in the running app and passes community review. One loop does it: spec → explore → prototype → implement → build, reload, verify → review. Code written against what is actually in the live app beats code written from memory of the API, because Obsidian's DOM and private internals move between releases.
obsidian.d.ts in node_modules/obsidian/ is the source of truth for every public signature.
Read it rather than guessing. Docs: https://docs.obsidian.md.
Step 0: find the runtime backend
The loop needs six capabilities. Work out which backend gives them before writing code.
- An Obsidian MCP server. List the connected tools and match on purpose, not exact names.
Names differ between servers (
obsidian_eval,obsidian_execute_js, …). - The official Obsidian CLI (installer 1.12.7+, Settings → General → Command line
interface). Check with
obsidian versionin Bash. It covers every capability itself, and the best-maintained MCP server is a thin wrapper around it. - Neither. Build, then ask the user to reload the plugin and paste the console output (and a screenshot if the change is visual). Say which checks you could not run yourself.
| Capability | Typical MCP tool | CLI command |
|---|---|---|
| Eval JS | *_eval, *_execute_js |
obsidian eval code="…" |
| Read console and errors | *_console, *_errors |
obsidian dev:console [level=error] [clear], obsidian dev:errors |
| Query DOM and CSS | *_dom, *_css, *_dom_query |
obsidian dev:dom selector=… [text] [all], obsidian dev:css selector=… |
| Screenshot | *_screenshot |
obsidian dev:screenshot path=<file> |
| Reload or enable a plugin | *_plugin_reload, *_enable_plugin |
obsidian plugin:reload id=<id> |
| List or run commands | *_commands, *_command |
obsidian commands filter=<id>, obsidian command id=<id> |
CDP-based servers need Obsidian started with the debug port, after quitting any running instance:
/Applications/Obsidian.app/Contents/MacOS/Obsidian --remote-debugging-port=9222. CLI-based
servers need the CLI setting on. Setup for either, plus CLI gotchas: references/runtime-inspection.md.
Safety. Prefer a dedicated test vault. Exploration evals must be read-only. Ask before any eval that writes, renames, moves or deletes vault files or changes another plugin's settings. The user's vault is not a sandbox.
The loop
1. Clarify the spec
Restate the request as three short lists before touching code:
- Behaviours: what the user sees or can do, including when it updates.
- API surfaces: which classes and events (see
references/api-map.md). - Done when: the observable checks you will run in step 5, such as "view lists 3 notes in the test vault", "no errors in console after reload", "command appears in palette".
Ask only if a behaviour is ambiguous in a way that changes the code. Otherwise state your assumption and go.
2. Explore before writing
Inspect the live app so the code targets what is there:
- the DOM and CSS classes of the UI you will touch or sit beside
- existing views and leaves, registered commands, enabled plugins
- the metadata cache for real notes the feature reads
- the plugin's own loaded state (
app.plugins.plugins["<id>"])
Snippets: references/runtime-inspection.md. Check signatures in obsidian.d.ts. If the only way
to do something is an undocumented app.* internal, say so to the user, isolate it behind one
function, and guard it so a missing property degrades instead of throwing.
3. Prototype in the runtime
Try the core logic with eval against the live app first, for example the query that collects the
data, or the DOM structure you plan to render. One eval answers in seconds what a
build-reload cycle answers in a minute. Return plain projections ({path, fm}), not TFile or
App, which cannot be serialised.
4. Implement
Write it into the plugin project using references/patterns.md and
references/lifecycle-and-cleanup.md. main.ts only wires things up. Each view, modal, settings
tab and editor extension lives in its own module. No project yet: references/project-setup.md.
5. Build, reload, verify
npm run build. Fix type errors before anything else.- Deploy and reload. Use
scripts/deploy.sh <vault-path>when the project is outside the vault, orplugin:reloadwhen it already lives in<vault>/.obsidian/plugins/<id>/. - Clear the console, exercise the feature (run the command or open the view via eval), then read the console. Any error from the plugin is a failure.
- Query the DOM for the elements the spec promised, and screenshot the affected UI.
- Check the "done when" list item by item. Loop until each one passes.
Report what you verified and how. If a check could not run, say so and why.
6. Review
Run npx eslint . from the repo root (not eslint src, which skips manifest.json and
LICENSE), then walk references/review-checklist.md. Fix every error. Treat warnings as
blockers too, since they count against the plugin in review.
Rules that matter most
Each one maps to a review rejection or a real bug.
- Register everything.
registerEvent,registerDomEvent,registerInterval,addCommand,registerView,registerEditorExtension. Thenonunloadhas nothing to do. Never detach leaves inonunload. - Never hold a view reference on the plugin. Find views with
workspace.getLeavesOfType(TYPE). - Defer startup work to
this.app.workspace.onLayoutReady(...).onloadmust stay fast. - Files through the Vault and FileManager APIs. Use
vault.processfor background edits,fileManager.processFrontMatterfor frontmatter, theEditorfor the open note, andfileManager.trashFilefor deletes. Look files up withvault.getFileByPath, never by looping all files. Pass user paths throughnormalizePath. Usevault.adapteronly for files outside the vault index. - Active view via
workspace.getActiveViewOfType(MarkdownView)orworkspace.activeEditor?.editor, neverworkspace.activeLeaf. - Build DOM with
createEl,createDivandcreateSpan, and clear withel.empty(). Never useinnerHTML,outerHTMLorinsertAdjacentHTML, and never inline styles. Style with classes instyles.cssusing Obsidian CSS variables. - Narrow types, never cast.
if (f instanceof TFile). Strict TypeScript, noany. - Network via
requestUrl, notfetch. It works on mobile and avoids CORS. - Mobile by default. No Node or Electron imports unless
isDesktopOnly: true. UsePlatformto branch. No regex lookbehind, which breaks older iOS. - UI text in sentence case. Settings headings via
new Setting(el).setName(…).setHeading(), and only when there is more than one section. No default hotkeys. Command ids and names must not repeat the plugin id or name, since Obsidian prefixes them.
Where to look
| When you need… | Read |
|---|---|
| Which API for a job: Vault vs Adapter vs FileManager, Workspace and leaves, MetadataCache, Editor vs CM6, events | references/api-map.md |
| Code shape for a view, modal, suggest, settings tab (incl. 1.13 declarative settings), command, ribbon, status bar, editor extension, post-processor | references/patterns.md |
onload/onunload, the register* family, leaks, onLayoutReady, multi-window |
references/lifecycle-and-cleanup.md |
| Eval snippets, backend setup, CLI gotchas, debugging "renders blank" or "no effect" | references/runtime-inspection.md |
| Pre-submission: guidelines, eslint-plugin-obsidianmd rules, manifest, release | references/review-checklist.md |
| New plugin, build config, hot reload, version bump, releases | references/project-setup.md |
Output
Keep replies short: the spec lists, what you changed (files), what you verified and how, and anything unverified or using private API. Show code only when the user needs to see it.
04 同仓库更多 Skills
vault-recall
Answer the user's conceptual or technical question using their Obsidian vault as well as general knowledge. Use when the user asks a question (not a task) whose topic appears in the vault MOC digest from session start. Not for task instructions, not mid-task, and not for writing to the vault (that is to-vault).
ingest
Ingest one external source (an article, course lesson, doc, PDF or URL) into the user's Obsidian vault: save the original to raw/, then build wiki/ pages per the vault's § Ingest. Use when the user types /ingest, or says "ingest this", "add this source to my wiki", "put this article/lesson in the vault as a wiki page". Works from any repo. Routing rule: someone else's words go to wiki/ (this skill); the user's own learnings and decisions go to notes/ (/to-vault).
to-tickets
Breaks a source into independently-grabbable GitHub tickets. For a code feature the source is the plan (`docs/plans/<feature>.md`, from /to-plan) and every new or changed symbol lands in exactly one ticket, its signatures copied into the ticket body; a non-code feature is cut from the PRD's slices. Cuts tickets for one feature per run. If a code feature has no approved plan, offers /to-plan instead of cutting from prose. In a repo that runs command-centre, also emits `[[task]]` blocks into its config; in a plain treepad repo, emits a Batch Manifest instead so the tickets materialise as stacked worktrees.
to-seams
Records an agreed-but-unlanded cross-repo interface as a seam: the file a consumer's agent gets pasted into its prompt as ground truth, plus the `[[seam]]` block command-centre reads for the retirement pointer. Use when two repos need to build against an interface neither has landed yet — "record a seam for X", "we agreed on this schema, seam it", "add a seam so Y can build against Z's new field". Halts for approval before writing either file.
to-roadmap
Prioritises settled features into a Now / Next / Later kanban board, rendered as a self-contained ./ideas/roadmap.html. Each card is a feature, not a ticket — one card later becomes several tickets via /to-prd -> /to-plan -> /to-tickets. Boards the features in ./docs/approach.md, or the "## Accepted ideas" in ./ideas/CONTEXT.md when there is no approach doc. The approach doc is settled truth: this assigns tiers and reasons about ordering, it never re-litigates what was decided.
to-prd
Turns one feature idea into a PRD built on journeys: a one-line problem, journeys (each ending in an observable state) and delivery slices that say what is usable after each. Interviews, explores the codebase, and saves to docs/prds/<feature>.md. Covers exactly one feature: given a multi-feature source, ask which one. Reads any approach doc or ideate report as priors so it doesn't re-ask what's settled, but needs none. Starts the per-feature spine (/to-prd -> /to-plan -> /to-tickets).