Agent Skills: Obsidian Install & Auth

Obsidian Install & Auth

Overview

Set up a complete Obsidian plugin development environment: clone the official sample plugin, install TypeScript + esbuild, configure a dev vault with symlink, verify the build pipeline, and establish the manifest.json / versions.json contract.

Prerequisites

• Node.js 18+ (LTS recommended)
• npm or pnpm package manager
• Obsidian desktop app installed (download from https://obsidian.md)
• Git for version control

Instructions

Step 1: Clone the Official Sample Plugin

set -euo pipefail
# Clone the maintained template — includes esbuild, tsconfig, and a working main.ts
git clone https://github.com/obsidianmd/obsidian-sample-plugin.git my-obsidian-plugin
cd my-obsidian-plugin

# Start fresh git history
rm -rf .git
git init
git add -A
git commit -m "initial scaffold from obsidian-sample-plugin"

The sample plugin includes these key files:

• esbuild.config.mjs — bundler with watch mode and external handling
• tsconfig.json — TypeScript config targeting ES2018 with strict null checks
• manifest.json — plugin metadata Obsidian reads at load time
• src/main.ts — Plugin subclass with commands, settings, modal

Step 2: Install Dependencies

set -euo pipefail
npm install

# What gets installed:
# - obsidian (type definitions only — the runtime is provided by the Obsidian app)
# - typescript
# - esbuild (fast bundler, <50ms builds)
# - @types/node
# - tslib (TypeScript helper library)

Step 3: Configure manifest.json

Every Obsidian plugin requires a manifest.json at the project root:

{
  "id": "my-obsidian-plugin",
  "name": "My Obsidian Plugin",
  "version": "1.0.0",
  "minAppVersion": "1.5.0",
  "description": "What your plugin does in one sentence.",
  "author": "Your Name",
  "authorUrl": "https://github.com/yourname",
  "isDesktopOnly": false
}

Required fields: id, name, version, minAppVersion, description, author.

Rules:

• id must be lowercase kebab-case, match the folder name under .obsidian/plugins/
• minAppVersion should be 1.5.0 or higher (supports modern APIs like processFrontMatter)
• isDesktopOnly: false unless you use Electron-only APIs (child_process, fs, shell)

Step 4: Create versions.json

Maps each plugin version to the minimum Obsidian version it requires:

{
  "1.0.0": "1.5.0"
}

Obsidian uses this to warn users on older versions that they cannot install your plugin. Update it every time you bump version in manifest.json.

Step 5: Create a Development Vault

set -euo pipefail
DEV_VAULT="$HOME/ObsidianDev"
mkdir -p "$DEV_VAULT/.obsidian/plugins"
mkdir -p "$DEV_VAULT/Test Notes"

# Create a sample note for testing
cat > "$DEV_VAULT/Test Notes/Sample.md" << 'EOF'
---
tags: [test, sample]
status: draft
---
# Sample Note

Test note for plugin development. Has [[wikilinks]], #tags, and frontmatter.

## Section A
Some content with **bold** and `inline code`.

## Section B
- [ ] Task one
- [x] Task two
- [ ] Task three
EOF

echo "Dev vault created at $DEV_VAULT"

Open this vault in Obsidian: File > Open vault > select ~/ObsidianDev.

Step 6: Symlink Plugin into Dev Vault

set -euo pipefail
DEV_VAULT="$HOME/ObsidianDev"
PLUGIN_DIR="$(pwd)"
PLUGIN_ID=$(node -e "console.log(require('./manifest.json').id)")

# Symlink project root into vault plugins folder
ln -sfn "$PLUGIN_DIR" "$DEV_VAULT/.obsidian/plugins/$PLUGIN_ID"

# Verify
ls -la "$DEV_VAULT/.obsidian/plugins/$PLUGIN_ID/manifest.json"
echo "Symlinked $PLUGIN_ID into dev vault"

On Windows (admin terminal):

mklink /D "%USERPROFILE%\ObsidianDev\.obsidian\plugins\my-obsidian-plugin" "%cd%"

Step 7: Build and Verify

set -euo pipefail
# Production build
npm run build
ls -la main.js manifest.json
echo "Build output: $(wc -c < main.js) bytes"

# Start dev mode with file watching
npm run dev
# esbuild watches src/ and rebuilds main.js on every save (~30ms)

In Obsidian:

1. Settings > Community plugins > Enable community plugins
2. Find your plugin in the list, toggle it on
3. Open Developer Console (Ctrl+Shift+I) — look for your plugin's load message
4. Press Ctrl+R to reload after any code change

Step 8: Verify the Obsidian API is Available

// src/main.ts — minimal verification
import { Plugin, Notice } from 'obsidian';

export default class MyPlugin extends Plugin {
  async onload() {
    // Verify core APIs are accessible
    const vaultName = this.app.vault.getName();
    const fileCount = this.app.vault.getMarkdownFiles().length;
    console.log(`[${this.manifest.id}] Loaded in vault "${vaultName}" with ${fileCount} notes`);

    this.addCommand({
      id: 'verify-setup',
      name: 'Verify Plugin Setup',
      callback: () => {
        new Notice(`Plugin working! Vault: ${vaultName}, Files: ${fileCount}`);
      },
    });
  }
}

Output

• Cloned and configured plugin project with all dependencies
• manifest.json and versions.json with correct metadata
• Development vault at ~/ObsidianDev with test notes
• Plugin symlinked into vault (no manual copying after builds)
• Working build pipeline: npm run build (production) and npm run dev (watch mode)
• Verified plugin loads and can access Vault API

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | Cannot find module 'obsidian' | Types not installed | npm install — obsidian is a devDependency | | Plugin not in Obsidian's list | Symlink broken or id mismatch | Verify symlink target exists, id matches folder name | | Build fails with TypeScript errors | Strict null checks | Add null guards: if (file instanceof TFile) | | Hot-reload not working | Need to reload manually | Install Hot Reload plugin or press Ctrl+R | | Permission denied on symlink | Windows requires admin | Run terminal as Administrator | | main.js not generated | Wrong esbuild entrypoint | Check entryPoints: ["src/main.ts"] in esbuild config |

Examples

Project Structure After Setup

my-obsidian-plugin/
├── src/
│   └── main.ts           # Plugin entry point (default export)
├── styles.css            # Optional: custom CSS (auto-loaded by Obsidian)
├── manifest.json         # Plugin metadata (required)
├── versions.json         # Version-to-minAppVersion mapping
├── package.json          # Node dependencies
├── tsconfig.json         # TypeScript config
├── esbuild.config.mjs    # Build configuration
└── main.js               # Build output (gitignored)

Vault Plugin Directory Structure

~/ObsidianDev/
├── .obsidian/
│   ├── app.json
│   ├── community-plugins.json   # ["my-obsidian-plugin"]
│   └── plugins/
│       └── my-obsidian-plugin -> /path/to/your/project  # symlink
├── Test Notes/
│   └── Sample.md

Quick Environment Check Script

set -euo pipefail
echo "Node: $(node --version)"
echo "npm: $(npm --version)"
echo "Git: $(git --version)"
echo "Obsidian vault: $(ls ~/ObsidianDev/.obsidian/app.json 2>/dev/null && echo 'found' || echo 'NOT FOUND')"
echo "Plugin symlink: $(ls -la ~/ObsidianDev/.obsidian/plugins/*/manifest.json 2>/dev/null || echo 'none')"

Resources

• Obsidian Sample Plugin — official starter template
• Build a Plugin — official getting started guide
• Obsidian API Reference — full TypeScript API
• BRAT Plugin — beta testing distribution
• Hot Reload Plugin — auto-reload on rebuild

Next Steps

After successful setup, proceed to obsidian-hello-world for your first plugin feature, or obsidian-local-dev-loop for hot-reload development workflow.