AGENT SKILL

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

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.

  1. An Obsidian MCP server. List the connected tools and match on purpose, not exact names. Names differ between servers (obsidian_eval, obsidian_execute_js, …).
  2. The official Obsidian CLI (installer 1.12.7+, Settings → General → Command line interface). Check with obsidian version in Bash. It covers every capability itself, and the best-maintained MCP server is a thin wrapper around it.
  3. 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

  1. npm run build. Fix type errors before anything else.
  2. Deploy and reload. Use scripts/deploy.sh <vault-path> when the project is outside the vault, or plugin:reload when it already lives in <vault>/.obsidian/plugins/<id>/.
  3. 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.
  4. Query the DOM for the elements the spec promised, and screenshot the affected UI.
  5. 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.

  1. Register everything. registerEvent, registerDomEvent, registerInterval, addCommand, registerView, registerEditorExtension. Then onunload has nothing to do. Never detach leaves in onunload.
  2. Never hold a view reference on the plugin. Find views with workspace.getLeavesOfType(TYPE).
  3. Defer startup work to this.app.workspace.onLayoutReady(...). onload must stay fast.
  4. Files through the Vault and FileManager APIs. Use vault.process for background edits, fileManager.processFrontMatter for frontmatter, the Editor for the open note, and fileManager.trashFile for deletes. Look files up with vault.getFileByPath, never by looping all files. Pass user paths through normalizePath. Use vault.adapter only for files outside the vault index.
  5. Active view via workspace.getActiveViewOfType(MarkdownView) or workspace.activeEditor?.editor, never workspace.activeLeaf.
  6. Build DOM with createEl, createDiv and createSpan, and clear with el.empty(). Never use innerHTML, outerHTML or insertAdjacentHTML, and never inline styles. Style with classes in styles.css using Obsidian CSS variables.
  7. Narrow types, never cast. if (f instanceof TFile). Strict TypeScript, no any.
  8. Network via requestUrl, not fetch. It works on mobile and avoids CORS.
  9. Mobile by default. No Node or Electron imports unless isDesktopOnly: true. Use Platform to branch. No regex lookbehind, which breaks older iOS.
  10. 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

O-Marsters-1997
O-Marsters-1997/my-claude-code

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).

★ 0
O-Marsters-1997
O-Marsters-1997/my-claude-code

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).

★ 0
O-Marsters-1997
O-Marsters-1997/my-claude-code

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.

★ 0
O-Marsters-1997
O-Marsters-1997/my-claude-code

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.

Skill与智能体开发
★ 0
O-Marsters-1997
O-Marsters-1997/my-claude-code

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.

产品经理
★ 0
O-Marsters-1997
O-Marsters-1997/my-claude-code

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).

产品经理
★ 0