Obsidian Plugin Development

Create and develop Obsidian plugins from scratch. Use when building a new Obsidian plugin, scaffolding from the sample-plugin-plus template, or developing plugin features. Covers project setup, manifest configuration, TypeScript development, settings UI, commands, ribbons, modals, and Obsidian API patterns.

Security Scan

The skill is a coherent Obsidian plugin development guide, but the runtime instructions reference external tools and template scripts (and an unclear 'pnpm obsidian-dev-skills' step) that are not declared in the metadata — review templates and scripts before running anything.

Purpose & Capability

The name/description match the content: an instruction-only skill for building Obsidian plugins. However, the SKILL.md expects tools like git, gh (GitHub CLI), pnpm, and standard Unix commands (cp, ln) but the registry metadata declares no required binaries — a mismatch that should be clarified.

Instruction Scope

Instructions legitimately cover cloning a GitHub template, running pnpm install, executing template scripts (e.g., ./scripts/setup-ref-links.sh), building, and copying output into ~/.obsidian/plugins. These are expected for plugin development, but running template scripts and package install scripts can execute arbitrary code — the skill does not include or show those scripts, so users should inspect them first.

Install Mechanism

No install spec and no code files are provided; the skill is instruction-only and does not itself write files or download archives. This reduces surface area compared to skills that install remote binaries.

Credentials

The skill requests no environment variables or credentials and does not declare access to unrelated services. That matches the declared metadata.

Persistence & Privilege

The skill is not forced-always or otherwise privileged. It is user-invocable and can be called autonomously (platform default), which is expected for a dev helper and is not by itself a red flag.

What to consider before installing

This skill is an instruction-only guide for building Obsidian plugins and is mostly coherent, but before you follow its steps: - Expect to need git, the GitHub CLI (gh) or at least git + GitHub access, and pnpm; the metadata did not list these binaries — install or verify them yourself. - The workflow instructs cloning a template repo and running pnpm install and template scripts (e.g., ./scripts/setup-ref-links.sh). Inspect the template repository, package.json, and any scripts referenced before running them — npm/pnpm install can run arbitrary lifecycle scripts. - Review any scripts and the generated main.js/manifest.json before copying them into your ~/.obsidian/plugins folder and enabling the plugin in Obsidian. Treat the template repo as untrusted until audited. - If you want to be extra safe, run pnpm install in an isolated environment (container or VM), or review dependencies and lockfiles first. If you want, I can: list the exact commands the skill will run, parse the remote template's package.json/scripts (if you provide it or allow me to fetch the repo), or critique a plugin produced from this template for suspicious code or network calls.

Build production-ready Obsidian plugins using the obsidian-sample-plugin-plus template.

Quick Start: New Plugin

1. Create from Template

# Clone the template (or use GitHub's "Use this template" button)
gh repo create my-plugin --template davidvkimball/obsidian-sample-plugin-plus --public --clone
cd my-plugin

# Or clone directly
git clone https://github.com/davidvkimball/obsidian-sample-plugin-plus.git my-plugin
cd my-plugin
rm -rf .git && git init

2. Configure Plugin Identity

Update these files with your plugin's info:

manifest.json:

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "0.0.1",
  "minAppVersion": "1.5.0",
  "description": "What your plugin does",
  "author": "Your Name",
  "authorUrl": "https://yoursite.com",
  "isDesktopOnly": false
}

package.json: Update name, description, author, license.

README.md: Replace template content with your plugin's documentation.

3. Initialize Development Environment

pnpm install
pnpm obsidian-dev-skills          # Initialize AI skills
./scripts/setup-ref-links.sh      # Unix
# or: scripts\setup-ref-links.bat  # Windows

4. Clean Boilerplate

In src/main.ts:

• Remove sample ribbon icon, status bar, commands, modal, and DOM event
• Keep the settings tab if needed, or remove it
• Rename MyPlugin class to your plugin name

Delete styles.css if your plugin doesn't need custom styles.

Development Workflow

Build & Test

pnpm dev      # Watch mode — rebuilds on changes
pnpm build    # Production build
pnpm lint     # Check for issues
pnpm lint:fix # Auto-fix issues
pnpm test     # Run unit tests

Install in Obsidian

Copy build output to your vault:

# Unix
cp main.js manifest.json styles.css ~/.obsidian/plugins/my-plugin/

# Or create a symlink for development
ln -s $(pwd) ~/.obsidian/plugins/my-plugin

Enable the plugin in Obsidian Settings → Community Plugins.

Use Hot Reload plugin for automatic reloading during development.

Plugin Architecture

Entry Point (src/main.ts)

import { Plugin } from 'obsidian';

export default class MyPlugin extends Plugin {
  settings: MyPluginSettings;

  async onload() {
    await this.loadSettings();
    // Register commands, ribbons, events, views
  }

  onunload() {
    // Cleanup: remove event listeners, views, DOM elements
  }

  async loadSettings() {
    this.settings = Object.assign({}, DEFAULT_SETTINGS, await this.loadData());
  }

  async saveSettings() {
    await this.saveData(this.settings);
  }
}

Settings Pattern

See references/settings.md for the complete settings UI pattern.

Common Patterns

See references/patterns.md for:

• Commands (simple, editor, check callbacks)
• Ribbon icons
• Modals
• Events and lifecycle
• File operations
• Editor manipulation

Constraints

• No auto-git: Never run git commit or git push without explicit approval
• No eslint-disable: Fix lint issues properly, don't suppress them
• No any types: Use proper TypeScript types
• Sentence case: UI text uses sentence case (ESLint may false-positive on this — ignore if so)

Release Checklist

1. Update version in manifest.json and package.json
2. Update versions.json with "version": "minAppVersion"
3. Run pnpm build — zero errors
4. Run pnpm lint — zero issues
5. Create GitHub release with tag matching version (no v prefix)
6. Upload: main.js, manifest.json, styles.css (if used)

References

• Settings UI — Complete settings tab implementation
• Common Patterns — Commands, modals, events, file operations
• Obsidian API Docs — Official documentation