Skip to content
Back to search

obsidian-plugin-skill

Agent SKILL for Obsidian.md plugin development

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/gapmiss/obsidian-plugin-skill with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/gapmiss/obsidian-plugin-skill'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gapmiss--obsidian-plugin-skill/badge.svg)](/listings/gapmiss--obsidian-plugin-skill)

HTML

<a href="/listings/gapmiss--obsidian-plugin-skill"><img src="/api/listings/gapmiss--obsidian-plugin-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Quick Install

npx skills add https://github.com/gapmiss/obsidian-plugin-skill --skill obsidian

Setup

Option 1: Installer Script (Recommended)

1. Clone this repository:

   git clone https://github.com/gapmiss/obsidian-plugin-skill.git
   cd obsidian-plugin-skill

2. Run the installer:

   ./install-skill.sh

3. Select your provider(s): - **All providers** — installs to both `.agents/skills/` and `.claude/skills/` - **Claude Code** — installs to `.claude/skills/` with slash commands - **Codex (OpenAI)** — installs to `.agents/skills/` - **Windsurf** — installs to `.agents/skills/`

4. Choose installation target (current directory or custom path)

Option 2: Manual Install

<details> <summary>Claude Code</summary>

git clone https://github.com/gapmiss/obsidian-plugin-skill.git
cd obsidian-plugin-skill

# Copy skill
mkdir -p your-project/.claude/skills/obsidian
cp -r .agents/skills/obsidian/* your-project/.claude/skills/obsidian/

# Copy slash commands
mkdir -p your-project/.claude/commands
cp .claude/commands/obsidian.md your-project/.claude/commands/
cp .claude/commands/create-plugin.md your-project/.claude/commands/

</details>

<details> <summary>Codex (OpenAI) / Windsurf</summary>

git clone https://github.com/gapmiss/obsidian-plugin-skill.git
cd obsidian-plugin-skill

# Copy skill
mkdir -p your-project/.agents/skills/obsidian
cp -r .agents/skills/obsidian/* your-project/.agents/skills/obsidian/

</details>

Option 3: Use as Standalone

Just open this directory with your coding agent — no installation needed!

Skill Structure

The skill uses **progressive disclosure** for optimal performance:

.agents/skills/obsidian/
├── SKILL.md                          # Main overview (~325 lines)
└── reference/                        # Detailed documentation
    ├── memory-management.md          # Lifecycle & cleanup patterns
    ├── type-safety.md                # Type narrowing & safety
    ├── ui-ux.md                      # UI standards & commands
    ├── file-operations.md            # Vault & file API
    ├── css-styling.md                # Theming & styling
    ├── accessibility.md              # A11y requirements (MANDATORY)
    ├── code-quality.md               # Best practices & security
    ├── submission.md                 # Publishing guidelines
    ├── community-scanner.md          # Scanner behavior & Scorecard (version-stamped)
    └── eslint-setup.md               # Complete ESLint config guide

SKILL.md provides a concise overview with ESLint rules and Scorecard guidance, while reference files contain comprehensive details on specific topics.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 600 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Obsidian Plugin Development - Agent Skill
  2. A comprehensive agent skill for developing high-quality Obsidian plugins that follow best practices, pass code review, and adhere to official submission guidelines.
  3. ## Overview
  4. This skill provides your coding agent with deep knowledge of Obsidian plugin development standards, including:
  5. - ESLint rules from `eslint-plugin-obsidianmd` v0.6.0
  6. - Declarative settings (`getSettingDefinitions()`), the Obsidian 1.13 settings API
  7. - Official Plugin Guidelines from Obsidian documentation
  8. - Submission via community.obsidian.md and Scorecard optimization
  9. - Memory management and lifecycle best practices
  10. - Security guidelines and XSS prevention
  11. - Platform compatibility (including iOS considerations)
  12. - Network request best practices (requestUrl vs fetch)
  13. ## Prerequisites
  14. - A coding agent supporting the [Agent Skills standard](https://agentskills.io) (Claude Code, OpenAI Codex, or Windsurf)
  15. - An Obsidian plugin project (or starting a new one)
  16. ## Installation
  17. ### Quick Install
  18. ```bash
  19. npx skills add https://github.com/gapmiss/obsidian-plugin-skill --skill obsidian
  20. ```
  21. ### Setup
  22. #### Option 1: Installer Script (Recommended)
  23. 1. Clone this repository:
  24. ```bash
  25. git clone https://github.com/gapmiss/obsidian-plugin-skill.git
  26. cd obsidian-plugin-skill
  27. ```
  28. 2. Run the installer:
  29. ```bash
  30. ./install-skill.sh
  31. ```
  32. 3. Select your provider(s):
  33. - **All providers** — installs to both `.agents/skills/` and `.claude/skills/`
  34. - **Claude Code** — installs to `.claude/skills/` with slash commands
  35. - **Codex (OpenAI)** — installs to `.agents/skills/`
  36. - **Windsurf** — installs to `.agents/skills/`
  37. 4. Choose installation target (current directory or custom path)
  38. #### Option 2: Manual Install
  39. <details>
  40. <summary>Claude Code</summary>
  41. ```bash
  42. git clone https://github.com/gapmiss/obsidian-plugin-skill.git
  43. cd obsidian-plugin-skill
  44. # Copy skill
  45. mkdir -p your-project/.claude/skills/obsidian
  46. cp -r .agents/skills/obsidian/* your-project/.claude/skills/obsidian/
  47. # Copy slash commands
  48. mkdir -p your-project/.claude/commands
  49. cp .claude/commands/obsidian.md your-project/.claude/commands/
  50. cp .claude/commands/create-plugin.md your-project/.claude/commands/
  51. ```
  52. </details>
  53. <details>
  54. <summary>Codex (OpenAI) / Windsurf</summary>
  55. ```bash
  56. git clone https://github.com/gapmiss/obsidian-plugin-skill.git
  57. cd obsidian-plugin-skill
  58. # Copy skill
  59. mkdir -p your-project/.agents/skills/obsidian
  60. cp -r .agents/skills/obsidian/* your-project/.agents/skills/obsidian/
  61. ```
  62. </details>
  63. #### Option 3: Use as Standalone
  64. Just open this directory with your coding agent — no installation needed!
  65. ### Skill Structure
  66. The skill uses **progressive disclosure** for optimal performance:
  67. ```
  68. .agents/skills/obsidian/
  69. ├── SKILL.md # Main overview (~325 lines)
  70. └── reference/ # Detailed documentation
  71. ├── memory-management.md # Lifecycle & cleanup patterns
  72. ├── type-safety.md # Type narrowing & safety
  73. ├── ui-ux.md # UI standards & commands
  74. ├── file-operations.md # Vault & file API
  75. ├── css-styling.md # Theming & styling
  76. ├── accessibility.md # A11y requirements (MANDATORY)
  77. ├── code-quality.md # Best practices & security
  78. ├── submission.md # Publishing guidelines
  79. ├── community-scanner.md # Scanner behavior & Scorecard (version-stamped)
  80. └── eslint-setup.md # Complete ESLint config guide
  81. ```
  82. SKILL.md provides a concise overview with ESLint rules and Scorecard guidance, while reference files contain comprehensive details on specific topics.
  83. ## Quick Start: Creating a New Plugin
  84. ### Interactive Boilerplate Generator
  85. The fastest way to start a new Obsidian plugin with all best practices built-in:
  86. ```bash
  87. node /path/to/obsidian-plugin-skill/tools/create-plugin.js
  88. ```
  89. **Features:**
  90. - Generates clean TypeScript boilerplate with **no sample code**
  91. - Creates `src/` directory structure with `main.ts` and `settings.ts`
  92. - Settings tab uses the **declarative API** (`getSettingDefinitions()`), so it's lint-clean and searchable on Obsidian 1.13+. To target older Obsidian, lower `minAppVersion` and add a `display()` fallback — see [Path B](.agents/skills/obsidian/reference/ui-ux.md#path-b-dual-support)
  93. - **Validates plugin metadata in real-time** against Obsidian's submission bot rules
  94. - Prompts for target directory to avoid overwriting existing files
  95. - Detects existing projects and only adds missing files
  96. - All generated code follows the skill's best practices automatically
  97. - `package.json` overrides `minimatch` to `^11.0.5`, so `npm audit` reports 0 vulnerabilities — see [below](#minimatch-override)
  98. **What it creates:**
  99. ```
  100. your-plugin/
  101. ├── src/
  102. │ ├── main.ts # Plugin class with settings integration
  103. │ └── settings.ts # Settings interface, defaults, and declarative tab
  104. ├── manifest.json # Validated plugin metadata
  105. ├── styles.css # CSS with Obsidian variables
  106. ├── tsconfig.json # TypeScript configuration
  107. ├── package.json # Dependencies, plus a temporary minimatch override
  108. ├── esbuild.config.mjs # Build configuration
  109. ├── eslint.config.mjs # ESLint configuration
  110. ├── version-bump.mjs # Version management script
  111. ├── versions.json # Version tracking
  112. ├── .gitignore # Git ignore rules
  113. └── LICENSE # MIT license
  114. ```
  115. **Interactive prompts:**
  116. 1. Target directory (default: current directory)
  117. 2. Plugin name (validates: no "Obsidian" or parts of it, no "Plugin")
  118. 3. Plugin ID (validates: no "obsidian", can't end with "plugin", lowercase only)
  119. 4. Description (validates: no "Obsidian", no self-reference, 10–250 chars, ends with `.`, `!`, or `?`, doesn't start with the name)
  120. 5. Author name
  121. 6. GitHub username (optional, auto-generates authorUrl)
  122. 7. Minimum Obsidian version (default `1.13.0`)
  123. **Real-time validation catches common mistakes:**
  124. ```
  125. ❌ Validation Errors:
  126. • Plugin ID cannot contain "obsidian"
  127. • Plugin name cannot contain "Plugin"
  128. • Description must end with punctuation: . ! or ?
  129. ```
  130. #### minimatch override
  131. `minimatch` before 11.0.1 has a denial-of-service advisory ([GHSA-g3hv-75wg-m249](https://github.com/advisories/GHSA-g3hv-75wg-m249)). The lint toolchain still depends on vulnerable versions — `typescript-eslint` on `minimatch ^10`, and `eslint-plugin-obsidianmd` via `@microsoft/eslint-plugin-sdl` → `eslint-plugin-n` on `^9` — so a plain install reports about 10 moderate vulnerabilities. The generated `package.json` forces the patched version:
  132. ```json
  133. "overrides": {
  134. "minimatch@>=7 <11.0.1": "^11.0.5"
  135. }
  136. ```
  137. It is dev-only (nothing reaches `main.js`), but the community scanner's Review lists "No known vulnerable dependencies". Linting and type-aware rules are verified to work with it. A `"//"` key in the generated `package.json` (npm ignores it) explains the override in the project itself. Remove both once upstream moves to `minimatch` 11 — see the [troubleshooting entry](.agents/skills/obsidian/reference/eslint-setup.md#npm-audit-moderate-vulnerabilities-in-minimatch-ghsa-g3hv-75wg-m249) for how to check. Don't run `npm audit fix --force`: it downgrades `eslint-plugin-obsidianmd` to 0.0.2.
  138. The remaining install warning, `npm warn deprecated eslint@9.39.5`, is expected: ESLint 10 currently adds peer-dependency warnings from bundled plugins instead.
  139. ---
  140. ## Usage
  141. ### Invoking the Skill
  142. | Provider | Load skill | Create plugin |
  143. |----------|-----------|---------------|
  144. | Claude Code | `/obsidian` | `/create-plugin` |
  145. | Codex (OpenAI) | `$obsidian` | — |
  146. | Windsurf | `@obsidian` | — |
  147. Skills are automatically discovered by your agent when present in the project directory. You can also invoke them explicitly using the commands above.
  148. Just ask your agent naturally:
  149. ```
  150. Help me implement a new command for my Obsidian plugin
  151. ```
  152. Your agent will automatically use the Obsidian skill guidelines while helping you write code.
  153. ### What the Skill Helps With
  154. #### Code Quality
  155. - Prevents common memory leaks
  156. - Enforces type safety (no unsafe casts)
  157. - Ensures proper resource cleanup
  158. - Follows Obsidian's API patterns
  159. #### UI/UX Standards
  160. - Enforces sentence case for all UI text
  161. - Prevents redundant naming patterns
  162. - Ensures consistent settings UI
  163. #### Accessibility (A11y)
  164. - **MANDATORY keyboard navigation** for all interactive elements
  165. - **MANDATORY ARIA labels** for icon buttons and controls
  166. - **MANDATORY focus indicators** with proper CSS styling
  167. - Touch target size requirements (44×44px minimum)
  168. - Screen reader support and announcements
  169. - Tooltip positioning with `data-tooltip-position`
  170. #### Security
  171. - Prevents XSS vulnerabilities (no innerHTML/outerHTML)
  172. - Validates manifest structure
  173. - Ensures proper path handling
  174. #### Platform Compatibility
  175. - iOS compatibility checks (no regex lookbehind)
  176. - Cross-platform path handling
  177. - Mobile-friendly API usage
  178. #### Submission Ready
  179. - Removes template/sample code
  180. - Validates manifest.json
  181. - Ensures LICENSE compliance
  182. - Follows submission requirements
  183. ## What's Covered
  184. ### Most Critical Rules (eslint-plugin-obsidianmd v0.6.0)
  185. The main SKILL.md file highlights the most important rules organized by category:
  186. **Submission & Naming:**
  187. 1. Plugin ID: no "obsidian", can't end with "plugin" (checked with `validate-manifest`'s `checkId: true` — turn it on before first submission)
  188. 2. Plugin name: no "Obsidian", no "Plugin"
  189. 3. Plugin name: no parts of "Obsidian" ("obsi", "sidian", or a leading "ob")
  190. 4. Description: no "Obsidian", "This plugin", "A plugin that", etc.; doesn't start with the name
  191. 5. Description: 10–250 characters, ends with `.`, `!`, or `?`
  192. **Memory & Lifecycle:**
  193. 6. Use `registerEvent()` for automatic cleanup
  194. 7. Don't store view references in plugin
  195. 8. Don't call `detachLeavesOfType()` in `onunload`
  196. **Type Safety:**
  197. 9. Use `instanceof` instead of type casting for TFile/TFolder
  198. 10. Use `.instanceOf(T)` for cross-window DOM checks, and `e.targetNode?.instanceOf(T)` for event targets
  199. **UI/UX:**
  200. 11. Use sentence case for all UI text (`ui/sentence-case` is off by default since v0.5.0 — opt in; `acronyms` adds to the built-in list since v0.6.0)
  201. 12. Sentence case in locale JSON files
  202. 13. Sentence case in TS/JS locale modules
  203. 14. No "command" as a redundant label in command names/IDs
  204. 15. No plugin ID/name in command IDs/names
  205. 16. No default hotkeys; a `checkCallback` must read `checking` (`commands/check-callback-uses-checking`, v0.6.0)
  206. 17. Use `.setHeading()` for settings headings; never `await` a `Setting` or UI component — it never settles (`no-await-chainable`, v0.6.0)
  207. **Declarative Settings (Obsidian 1.13+):**
  208. - Keep `display()` while `minAppVersion < 1.13.0` (`settings-tab/require-display`)
  209. - Implement `getSettingDefinitions()` so settings appear in global search (`settings-tab/prefer-setting-definitions`)
  210. - Refresh with `this.update()`, not `this.display()` (`settings-tab/prefer-update-over-display`)
  211. - Drop `display()` once `minAppVersion >= 1.13.0` and definitions exist (`settings-tab/no-deprecated-display`)
  212. **API Best Practices:**
  213. 18. Use Editor API for active file edits
  214. 19. Use `Vault.process()` for background file mods
  215. 20. Use `FileManager.trashFile()` for file deletion
  216. 21. Use `Vault.getAbstractFileByPath()` instead of iterating files
  217. 22. Use `normalizePath()` for user paths
  218. 23. Use `Platform` API for OS detection
  219. 24. Use `requestUrl()` instead of `fetch()`; parse `response.text` and cast once at the API boundary (`response.json` is `any`)
  220. 25. No console.log in onload/onunload in production
  221. 26. Use built-in `AbstractInputSuggest`; use built-in `ConfirmationModal` (1.13.0+) and `FileManager.promptForDeletion()` instead of custom confirm modals
  222. 27. Check `minAppVersion` for API compatibility
  223. **Popout Window Compatibility:**
  224. 28. Use `activeDocument`/`activeWindow` instead of globals (`prefer-active-doc`, `warn` since v0.5.0); apply window-wide `<body>` classes and styles in every window's document
  225. 29. Use `window.setTimeout()` for timers — not bare `setTimeout()` or `activeWindow.setTimeout()` (`prefer-window-timers`)
  226. **Event Handling:**
  227. 30. Check `evt.defaultPrevented` and call `evt.preventDefault()` in editor-drop/paste handlers that write to the editor
  228. **Styling:**
  229. 31. Use Obsidian CSS variables
  230. 32. Scope CSS to plugin containers
  231. 33. Don't create `<link>` or `<style>` elements
  232. **Accessibility (MANDATORY):**
  233. 34. Make all interactive elements keyboard accessible
  234. 35. Provide ARIA labels for icon buttons
  235. 36. Define clear focus indicators
  236. **Security & Compatibility:**
  237. - Don't use `innerHTML`/`outerHTML`
  238. - Avoid regex lookbehind
  239. **Code Quality:**
  240. - Remove all sample/template code
  241. - Don't mutate defaults with `Object.assign`
  242. - Validate LICENSE copyright holder and year
  243. ### Detailed Coverage by Topic
  244. **[Memory Management & Lifecycle](.agents/skills/obsidian/reference/memory-management.md)**
  245. - Using `registerEvent()`, `addCommand()`, `registerDomEvent()`, `registerInterval()`
  246. - Avoiding view references in plugin
  247. - Not using plugin as component
  248. - Proper leaf cleanup
  249. **[Type Safety](.agents/skills/obsidian/reference/type-safety.md)**
  250. - Using `instanceof` instead of type casting
  251. - Avoiding `any` type
  252. - Using `const` and `let` over `var`
  253. **[UI/UX Standards](.agents/skills/obsidian/reference/ui-ux.md)**
  254. - Sentence case enforcement
  255. - Command naming conventions
  256. - Settings and configuration best practices
  257. - Confirmation dialogs (`ConfirmationModal`, `promptForDeletion()`)
  258. **[File & Vault Operations](.agents/skills/obsidian/reference/file-operations.md)**
  259. - View access patterns
  260. - Editor vs Vault API
  261. - Atomic file operations (Vault.process, processFrontMatter)
  262. - File management and path handling
  263. **[CSS Styling Best Practices](.agents/skills/obsidian/reference/css-styling.md)**
  264. - Avoiding inline styles
  265. - Using Obsidian CSS variables
  266. - Scoping plugin styles
  267. - Theme support (light/dark)
  268. - Spacing and layout (4px grid)
  269. **[Accessibility (A11y)](.agents/skills/obsidian/reference/accessibility.md)** - MANDATORY
  270. - Keyboard navigation for all interactive elements
  271. - ARIA labels and roles
  272. - Tooltips with proper positioning
  273. - Focus management
  274. - Focus visible styles (`:focus-visible`)
  275. - Screen reader support
  276. - Mobile and touch accessibility (44×44px minimum)
  277. **[Code Quality & Best Practices](.agents/skills/obsidian/reference/code-quality.md)**
  278. - Removing sample code
  279. - Security best practices (XSS prevention)
  280. - Platform compatibility (iOS, mobile)
  281. - API usage patterns
  282. - Async/await patterns
  283. - DOM helpers
  284. **[Plugin Submission Requirements](.agents/skills/obsidian/reference/submission.md)**
  285. - **Naming and description validation rules** (enforced by automated review)
  286. - Plugin ID, name, and description requirements
  287. - Repository structure and manifest synchronization
  288. - Submission via **community.obsidian.md** portal
  289. - Semantic versioning
  290. - Testing checklist
  291. **[Community Plugin Scanner](.agents/skills/obsidian/reference/community-scanner.md)**
  292. - What the scanner runs (ESLint rule sets + checks beyond ESLint)
  293. - **Scorecard system** (Health, Review, Disclosures)
  294. - Version-stamped — single place to update as the scanner evolves
  295. ## Examples
  296. ### Before (Incorrect)
  297. ```typescript
  298. // Multiple issues
  299. class MyPlugin extends Plugin {
  300. view: CustomView;
  301. async onload() {
  302. this.registerView(VIEW_TYPE, (leaf) => {
  303. this.view = new CustomView(leaf); // Memory leak!
  304. return this.view;
  305. });
  306. this.addCommand({
  307. id: 'my-plugin-show-command', // Redundant naming
  308. name: 'Show Command', // Title Case
  309. hotkeys: [{ modifiers: ['Mod'], key: 's' }], // Default hotkey
  310. });
  311. const file = abstractFile as TFile; // Unsafe cast
  312. }
  313. onunload() {
  314. this.app.workspace.detachLeavesOfType(VIEW_TYPE); // Don't do this
  315. }
  316. }
  317. ```
  318. ### After (Correct)
  319. ```typescript
  320. // Following all guidelines
  321. class TodoPlugin extends Plugin {
  322. async onload() {
  323. this.registerView(VIEW_TYPE, (leaf) => {
  324. return new CustomView(leaf); // Create and return directly
  325. });
  326. this.addCommand({
  327. id: 'show', // Clean naming
  328. name: 'Show todo', // Sentence case
  329. // Let users set their own hotkeys
  330. checkCallback: (checking: boolean) => {
  331. const view = this.app.workspace.getActiveViewOfType(MarkdownView);
  332. if (view) {
  333. if (!checking) {
  334. // Perform action
  335. }
  336. return true;
  337. }
  338. return false;
  339. }
  340. });
  341. if (abstractFile instanceof TFile) {
  342. // Safe type narrowing
  343. const file = abstractFile;
  344. }
  345. }
  346. onunload() {
  347. // Let Obsidian handle cleanup
  348. }
  349. }
  350. ```
  351. ## Checklist for Plugin Review
  352. Use this checklist before submitting your plugin:
  353. **Submission Validation (will fail bot checks if incorrect):**
  354. - [ ] Plugin ID: no "obsidian", doesn't end with "plugin", lowercase only
  355. - [ ] Plugin name: no "Obsidian", no "Plugin"
  356. - [ ] Plugin name: no parts of "Obsidian" ("obsi", "sidian", or a leading "ob")
  357. - [ ] Description: no "Obsidian" or self-reference ("This plugin", "A plugin that")
  358. - [ ] Description ends with `.`, `!`, or `?`
  359. - [ ] Description is 10–250 characters and doesn't start with the plugin name
  360. - [ ] `npx eslint .` from the project root is clean (checks `manifest.json` and `LICENSE` too)
  361. - [ ] manifest.json ID, name, description match submission entry
  362. **Code Quality:**
  363. - [ ] No memory leaks (views/components properly managed)
  364. - [ ] Type safety (using `instanceof` instead of casts)
  365. - [ ] All UI text in sentence case
  366. - [ ] No redundant words in command names
  367. - [ ] Using preferred APIs (Editor API, Vault.process, etc.)
  368. - [ ] No iOS-incompatible features (regex lookbehind)
  369. - [ ] All sample code removed (MyPlugin, SampleModal, etc.)
  370. - [ ] No security issues (innerHTML, XSS vulnerabilities)
  371. **Accessibility (MANDATORY):**
  372. - [ ] **All interactive elements keyboard accessible (Tab, Enter, Space)**
  373. - [ ] **ARIA labels on all icon buttons (`aria-label`)**
  374. - [ ] **Clear focus indicators (`:focus-visible` with proper CSS)**
  375. - [ ] **Touch targets at least 44×44px (mobile)**
  376. - [ ] **Tooltips positioned with `data-tooltip-position`**
  377. **Release Requirements:**
  378. - [ ] manifest.json valid and version correct
  379. - [ ] LICENSE file included
  380. - [ ] Mobile tested (if not desktop-only)
  381. - [ ] Repository has issues enabled
  382. ## ESLint Integration
  383. For automatic checking, install the official ESLint plugin:
  384. ```bash
  385. npm install --save-dev eslint typescript typescript-eslint obsidian eslint-plugin-obsidianmd
  386. ```
  387. v0.5.0 and later require Node.js 20.19+, 22.13+, or 24+, and don't install `obsidian` for you. Upgrading from v0.5.1? See [Upgrading from v0.5.1](.agents/skills/obsidian/reference/eslint-setup.md#upgrading-from-v051). From v0.5.0? See [Upgrading from v0.5.0](.agents/skills/obsidian/reference/eslint-setup.md#upgrading-from-v050). From v0.4.x? See [Upgrading from v0.4.x](.agents/skills/obsidian/reference/eslint-setup.md#upgrading-from-v04x).
  388. The `recommended` config bundles `typescript-eslint` (type-checked), security plugins, and all Obsidian rules — no separate typescript-eslint setup needed.
  389. See the **[complete ESLint setup guide](.agents/skills/obsidian/reference/eslint-setup.md)** for:
  390. - Full `eslint.config.mjs` that matches the community scanner
  391. - How `recommended` bundles the type-checked rules
  392. - Common violations and how to fix them
  393. Quick config example (`recommended` bundles `typescript-eslint` recommendedTypeChecked plus security and import rules):
  394. ```javascript
  395. // eslint.config.mjs
  396. import { defineConfig, globalIgnores } from "eslint/config";
  397. import obsidianmd from "eslint-plugin-obsidianmd";
  398. export default defineConfig([
  399. globalIgnores(["node_modules", "dist", "main.js", "esbuild.config.mjs", "version-bump.mjs"]),
  400. ...obsidianmd.configs.recommended,
  401. {
  402. languageOptions: {
  403. parserOptions: {
  404. projectService: {
  405. allowDefaultProject: ["eslint.config.*"],
  406. },
  407. },
  408. },
  409. },
  410. ]);
  411. ```
  412. Run it from the project root (`eslint .`, not `eslint src`) so `manifest.json`, `LICENSE`, and `package.json` are checked too.
  413. Many rules are auto-fixable with:
  414. ```bash
  415. npx eslint --fix .
  416. ```
  417. Since v0.5.0, rewrites that could break type-checking are offered as editor suggestions instead of `--fix` autofixes. v0.6.0 moves more rewrites to suggestions (timers set and cleared on `activeWindow`, `instanceof` on a value that may be `null`), so run `npx eslint .` again after `--fix` and resolve what's left.
  418. ## Resources
  419. - Obsidian API Docs: https://docs.obsidian.md
  420. - **Community Portal**: https://community.obsidian.md
  421. - ESLint Plugin: https://github.com/obsidianmd/eslint-plugin
  422. - Sample Plugin: https://github.com/obsidianmd/obsidian-sample-plugin
  423. - Plugin Guidelines: https://docs.obsidian.md/Plugins/Releasing/Plugin+guidelines
  424. - Submission Guide: https://docs.obsidian.md/Plugins/Releasing/Submit+your+plugin
  425. - Agent Skills Standard: https://agentskills.io
  426. ## Contributing
  427. Found a missing guideline or rule? Please contribute!
  428. 1. Fork this repository
  429. 2. Add the guideline to the appropriate file:
  430. - Main overview: `.agents/skills/obsidian/SKILL.md`
  431. - Detailed coverage: `.agents/skills/obsidian/reference/*.md`
  432. 3. Update this README if needed
  433. 4. Submit a pull request
  434. ### Adding New Guidelines
  435. When adding new content:
  436. - Keep SKILL.md under 500 lines (progressive disclosure principle)
  437. - Add detailed content to appropriate reference files
  438. - Use consistent formatting and examples
  439. - Include both incorrect and correct examples
  440. ## Migration from `.claude/skills/`
  441. If you previously installed this skill to `.claude/skills/obsidian/`, you can migrate:
  442. ```bash
  443. # Move skill files to the new location
  444. mv .claude/skills/obsidian .agents/skills/obsidian
  445. # Keep .claude/commands/ as-is (Claude Code only)
  446. ```
  447. The `.claude/skills/` path still works for Claude Code, but `.agents/skills/` is the standard location recognized by all providers.
  448. ## License
  449. MIT License - See LICENSE file for details
  450. ## Acknowledgments
  451. This skill is based on:
  452. - The official Obsidian Plugin Guidelines
  453. - The `eslint-plugin-obsidianmd` package
  454. - Community best practices from plugin developers
  455. - Agent Skills standard best practices (progressive disclosure pattern)
  456. ---
  457. ## Design Philosophy
  458. This skill follows **Agent Skills standard best practices**:
  459. - **Progressive Disclosure**: Main SKILL.md (~370 lines) provides overview; reference files contain details
  460. - **Context Window Efficiency**: "The context window is a public good" - optimized token usage
  461. - **One-Level-Deep References**: All reference files directly under `reference/` (no nesting)
  462. - **Topic-Based Organization**: Each reference file focuses on a specific domain
  463. - **Consistent Terminology**: Same terms used throughout for clarity
  464. This structure allows your coding agent to load the essential information quickly while having access to comprehensive details when needed.
  465. ---
  466. Note: Guidelines in this skill are based on `eslint-plugin-obsidianmd` v0.6.0 and the community.obsidian.md Scorecard system. The plugin and scanner are under active development and may evolve.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.