---
name: obsidian-plugin-scaffold
description: >-
  Bootstrap a new Obsidian community plugin from the sample plugin or a proven
  layout. Use when creating a new plugin repo, renaming the sample plugin,
  wiring esbuild/manifest/scripts, or /obsidian-plugin-scaffold.
---

# Scaffold an Obsidian plugin

Goal: a repo that builds `main.js`, has a valid `manifest.json`, and can deploy into a throwaway vault. Do not start features until identity and scripts are locked.

This skill owns identity, layout, esbuild, and day-one scripts. Cloud/AGENTS.md text lives in [obsidian-plugin-verify/references/cloud-agents.md](../obsidian-plugin-verify/references/cloud-agents.md).

## 1. Identity first

Write these before copying files:

| Field | Rules |
| --- | --- |
| `id` | Lowercase kebab-case. No `obsidian` substring. Must not end with `plugin`. Becomes the install folder name. |
| `name` | Unique display name. No `Obsidian` / `Plugin`. No emoji. |
| `minAppVersion` | Oldest Obsidian you support without feature-detecting every call. |
| `isDesktopOnly` | `true` only if you need Node or Electron APIs. Prefer `false`. |
| `author` / `authorUrl` | `authorUrl` is the GitHub **profile**, not the plugin repo. |

Repo name and plugin `id` may differ. Keep them distinct if you want.

## 2. Bootstrap sources

Start from [obsidianmd/obsidian-sample-plugin](https://github.com/obsidianmd/obsidian-sample-plugin), then rename placeholders (`MyPlugin`, `SampleSettingTab`, …). Move code under `src/`, add Node tests with `--experimental-strip-types`, Selenium e2e, and review-ban unit tests. Use [project-layout.md](references/project-layout.md) as the on-disk target.

Develop in a **throwaway vault**, never the user's main vault.

## 3. Required root files

```text
manifest.json      # id, name, version, minAppVersion, description, author, …
styles.css         # optional but expected by most plugins
main.js            # production bundle (committed or release-only — pick one and document it)
versions.json      # { "<plugin version>": "<minAppVersion>" }
package.json
esbuild.config.mjs # or equivalent
tsconfig.json
src/main.ts        # Plugin subclass entry
```

See [references/project-layout.md](references/project-layout.md) for the `src/` tree, `manifest.json` skeleton, and esbuild `external` list.

## 4. Bundle contract

esbuild (or rollup) must:

- Entry: `src/main.ts`
- Output: repo-root `main.js` as **CJS**
- Target roughly `es2020`
- **Externalize** `obsidian`, `electron`, `@codemirror/*`, `@lezer/*` (full list in [project-layout.md](references/project-layout.md))

Optional: when `OBSIDIAN_PLUGIN_OUT` points at a vault plugin folder, copy `main.js`, `manifest.json`, and `styles.css` there after build.

Typecheck is a separate `tsc --noEmit`. Do not hide type errors inside a silent bundle.

## 5. Scripts to create on day one

```json
{
  "scripts": {
    "dev": "node esbuild.config.mjs",
    "build": "node esbuild.config.mjs production",
    "typecheck": "tsc --noEmit",
    "test": "node --experimental-strip-types --test tests/*.mjs",
    "test:e2e": "npm run build && node --test --test-timeout=180000 e2e/*.test.mjs"
  }
}
```

Node 22+ for `--experimental-strip-types`. Add `test:e2e` before shipping UI even if the first suite only asserts "plugin enabled".

## 6. AGENTS.md

Copy the Cloud section from [cloud-agents.md](../obsidian-plugin-verify/references/cloud-agents.md) into the new repo's `AGENTS.md`. Do not invent a second copy here.

## 7. First commit checklist

- [ ] `manifest.json` identity passes directory rules
- [ ] Sample class names renamed
- [ ] `npm run typecheck && npm run build` succeed
- [ ] Plugin loads in a throwaway vault (manual or e2e)
- [ ] README states privacy defaults (local-only unless you have a real network need)
- [ ] LICENSE chosen

Then move to [obsidian-plugin-architecture](../obsidian-plugin-architecture/SKILL.md) for layering and data layout.