obsidian-plugin-init

name	obsidian-plugin-init
description	Use when creating or extending an Obsidian community plugin scaffold from this repository, especially when you want Codex to generate a new plugin with the local CLI, keep main.ts minimal, organize code under src/, and follow the repository's AGENTS.md conventions.

Obsidian Plugin Init

Use this skill when the task is about generating or evolving an Obsidian community plugin from this repository's scaffold.

Workflow

1. Read AGENTS.md at the repository root and keep its Obsidian plugin rules in scope.
2. Prefer the local CLI in this repo over retyping boilerplate:
   • npm install
   • node bin/create-obsidian-plugin.js <plugin-dir>
   • or, once published, npx obs-plugin-init <plugin-dir>
   • Bun users can run bunx obs-plugin-init <plugin-dir>
   • pass --plugin-author and --plugin-author-url when generating a release-ready plugin
3. Keep generated plugin source modular:
   • src/main.ts should stay minimal and re-export or delegate to another module.
   • Put commands, settings, UI, and utilities in separate files under src/.
4. For user-facing features:
   • register commands with stable IDs
   • add a settings tab for configurable behavior
   • persist settings with loadData and saveData
5. For release-ready plugins:
   • keep manifest.json, versions.json, and the Git tag version aligned
   • keep README.md, LICENSE, .github/workflows/ci.yml, and .github/workflows/release.yml present
   • ensure the release uploads manifest.json, main.js, and styles.css if present
   • generate GitHub artifact attestations for the release assets
   • commit the lock file generated by the first npm install
6. Validate the plugin with npm install, npm run check, npm run build, and a quick file-level sanity check before finishing.

Publishing this scaffold

• Keep the package bin name aligned with the package name so npx and bunx can invoke it directly.
• Prefer npm trusted publishing from GitHub Actions over long-lived npm tokens.
• Publish with provenance and attest the packed .tgz file in the GitHub release workflow.

Repository map

• bin/create-obsidian-plugin.js: main generator CLI
• bin/download-scaffold.js: optional local installer/downloader
• template/: files copied into each new plugin project

When extending the scaffold itself

1. Update the files under template/.
2. Keep placeholders intact:
   • __PLUGIN_ID__
   • __PLUGIN_NAME__
   • __PLUGIN_DESCRIPTION__
   • __PLUGIN_CLASS_NAME__
   • __PLUGIN_AUTHOR__
   • __PLUGIN_AUTHOR_URL__
3. Re-run node --test tests/*.test.js.
4. Generate a temporary plugin once to confirm the scaffold still produces a buildable project and includes release materials.