obsidian-dev-skills 1.0.0 → 1.0.2

package/obsidian-dev-plugins/references/coding-conventions.md

@@ -0,0 +1,21 @@
+<!--
+Source: Based on Obsidian Sample Plugin and TypeScript best practices
+Last synced: See sync-status.json for authoritative sync dates
+Update frequency: Check Obsidian Sample Plugin repo for updates
+Applicability: Plugin
+-->
+
+# Coding conventions
+
+**Note**: This file is specific to plugin development (TypeScript). For theme development, see CSS/SCSS best practices in other files.
+
+- TypeScript with `"strict": true` preferred.
+- **Avoid `any` type**: Use proper types, `unknown`, or type assertions instead. `any` defeats TypeScript's type safety benefits.
+- **Keep `main.ts` minimal**: Focus only on plugin lifecycle (onload, onunload, addCommand calls). Delegate all feature logic to separate modules.
+- **Split large files**: If any file exceeds ~200-300 lines, consider breaking it into smaller, focused modules.
+- **Use clear module boundaries**: Each file should have a single, well-defined responsibility.
+- Bundle everything into `main.js` (no unbundled runtime deps).
+- Avoid Node/Electron APIs if you want mobile compatibility; set `isDesktopOnly` accordingly.
+- Prefer `async/await` over promise chains; handle errors gracefully.
+
+

package/obsidian-dev-plugins/references/commands-settings.md

@@ -0,0 +1,24 @@
+<!--
+Source: Based on Obsidian Sample Plugin and community plugin guidelines
+Last synced: See sync-status.json for authoritative sync dates
+Update frequency: Check Obsidian Sample Plugin repo for updates
+Applicability: Plugin
+-->
+
+# Commands & settings
+
+**Note**: This file is specific to plugin development. Themes do not have commands or settings.
+
+- Any user-facing commands should be added via `this.addCommand(...)`.
+- If the plugin has configuration, provide a settings tab and sensible defaults.
+- Persist settings using `this.loadData()` / `this.saveData()`.
+- Use stable command IDs; avoid renaming once released.
+
+## Version Considerations
+
+When using newer API features (e.g., `SettingGroup` since API 1.11.0), consider backward compatibility:
+- **For new plugins**: You can set `minAppVersion: "1.11.0"` in `manifest.json` and use the feature directly
+- **For existing plugins**: Use version checking with `requireApiVersion()` to support both newer and older Obsidian versions
+- See [code-patterns.md](code-patterns.md) for backward compatibility patterns, including a complete example for `SettingGroup`
+
+

package/obsidian-dev-plugins/references/common-tasks.md

@@ -0,0 +1,429 @@
+<!--
+Source: Based on Obsidian Sample Plugin
+Last synced: See sync-status.json for authoritative sync dates
+Update frequency: Check Obsidian Sample Plugin repo for updates
+-->
+
+# Common tasks
+
+**Note**: The examples below are for plugin development (TypeScript).
+
+**When to use this vs [code-patterns.md](code-patterns.md)**: 
+- **common-tasks.md**: Quick snippets and basic patterns for common operations
+- **code-patterns.md**: Complete, production-ready examples with full context and error handling
+
+> **Note**: If user asks "what does the Obsidian API say about X?" or similar, check `.ref/obsidian-api/obsidian.d.ts` first. See [ref-instructions.md](ref-instructions.md) for when to check `.ref` setup.
+
+## Organize code across multiple files
+
+**main.ts** (minimal, lifecycle only):
+```ts
+import { Plugin } from "obsidian";
+import { MySettings, DEFAULT_SETTINGS } from "./settings";
+import { registerCommands } from "./commands";
+
+export default class MyPlugin extends Plugin {
+  settings: MySettings;
+
+  async onload() {
+    this.settings = Object.assign({}, DEFAULT_SETTINGS, await this.loadData());
+    registerCommands(this);
+  }
+}
+```
+
+**settings.ts**:
+```ts
+export interface MySettings {
+  enabled: boolean;
+  apiKey: string;
+}
+
+export const DEFAULT_SETTINGS: MySettings = {
+  enabled: true,
+  apiKey: "",
+};
+```
+
+**commands/index.ts**:
+```ts
+import { Plugin } from "obsidian";
+import { doSomething } from "./my-command";
+
+export function registerCommands(plugin: Plugin) {
+  plugin.addCommand({
+    id: "do-something",
+    name: "Do something",
+    callback: () => doSomething(plugin),
+  });
+}
+```
+
+## Add a command
+
+```ts
+this.addCommand({
+  id: "your-command-id",
+  name: "Do the thing",
+  callback: () => this.doTheThing(),
+});
+```
+
+## Persist settings
+
+```ts
+interface MySettings { enabled: boolean }
+const DEFAULT_SETTINGS: MySettings = { enabled: true };
+
+async onload() {
+  this.settings = Object.assign({}, DEFAULT_SETTINGS, await this.loadData());
+  await this.saveData(this.settings);
+}
+```
+
+## Register listeners safely
+
+```ts
+this.registerEvent(this.app.workspace.on("file-open", f => { /* ... */ }));
+this.registerDomEvent(window, "resize", () => { /* ... */ });
+this.registerInterval(window.setInterval(() => { /* ... */ }, 1000));
+```
+
+## Settings Tab Implementation
+
+**Source**: Based on `.ref/obsidian-sample-plugin/main.ts` and `.ref/obsidian-api/obsidian.d.ts` (API is authoritative for SettingGroup - available since 1.11.0)
+
+Basic settings tab:
+
+```ts
+import { App, PluginSettingTab, Setting } from "obsidian";
+
+class MySettingTab extends PluginSettingTab {
+  plugin: MyPlugin;
+
+  constructor(app: App, plugin: MyPlugin) {
+    super(app, plugin);
+    this.plugin = plugin;
+  }
+
+  display(): void {
+    const { containerEl } = this;
+    containerEl.empty();
+
+    new Setting(containerEl)
+      .setName("Setting name")
+      .setDesc("Setting description")
+      .addText((text) =>
+        text
+          .setPlaceholder("Enter value")
+          .setValue(this.plugin.settings.mySetting)
+          .onChange(async (value) => {
+            this.plugin.settings.mySetting = value;
+            await this.plugin.saveSettings();
+          })
+      );
+  }
+}
+
+// In main plugin class:
+this.addSettingTab(new MySettingTab(this.app, this));
+```
+
+**Note**: For settings groups (available since API 1.11.0), use `SettingGroup` from the API. Plugin docs may not yet document this feature - always check `.ref/obsidian-api/obsidian.d.ts` for the latest API.
+
+**SettingGroup Methods** (available since 1.11.0):
+- `setHeading(heading: string)` - Set the group heading
+- `addSetting(cb: (setting: Setting) => void)` - Add a setting to the group
+- `addSearch(cb: (component: SearchComponent) => any)` - Add a search input at the beginning of the group (useful for filtering)
+- `addExtraButton(cb: (component: ExtraButtonComponent) => any)` - Add an extra button to the group
+
+**Backward Compatibility**: To support users on both Obsidian 1.11.0+ and older versions, use a compatibility utility. See [code-patterns.md](code-patterns.md) for the complete implementation with `createSettingsGroup()` utility. Alternatively, you can force `minAppVersion: "1.11.0"` in `manifest.json` if you don't need to support older versions.
+
+## Secret Storage
+
+**Source**: Based on [SecretStorage and SecretComponent guide](https://docs.obsidian.md/plugins/guides/secret-storage) (available since Obsidian 1.11.4)
+
+**Important**: Always use `SecretStorage` and `SecretComponent` for storing sensitive data like API keys, tokens, or passwords. Never store secrets directly in your plugin's `data.json` file.
+
+### Using SecretComponent in Settings
+
+Store only the secret *name* (ID) in your settings, not the actual secret value:
+
+```ts
+import { App, PluginSettingTab, SecretComponent, Setting } from "obsidian";
+
+export interface MyPluginSettings {
+  apiKeySecretId: string; // Store the secret name, not the value
+}
+
+export class MySettingTab extends PluginSettingTab {
+  plugin: MyPlugin;
+
+  constructor(app: App, plugin: MyPlugin) {
+    super(app, plugin);
+    this.plugin = plugin;
+  }
+
+  display(): void {
+    const { containerEl } = this;
+    containerEl.empty();
+
+    new Setting(containerEl)
+      .setName("API key")
+      .setDesc("Select a secret from SecretStorage")
+      .addComponent((el) =>
+        new SecretComponent(this.app, el)
+          .setValue(this.plugin.settings.apiKeySecretId)
+          .onChange(async (value) => {
+            this.plugin.settings.apiKeySecretId = value;
+            await this.plugin.saveSettings();
+          })
+      );
+  }
+}
+```
+
+**Note**: `SecretComponent` requires the `App` instance in its constructor, so it must be used with `Setting#addComponent()` rather than methods like `addText()`.
+
+### Retrieving Secrets
+
+When you need the actual secret value, retrieve it from `SecretStorage`:
+
+```ts
+// Get a secret by its ID (name)
+const secret = this.app.secretStorage.getSecret(this.settings.apiKeySecretId);
+
+if (secret) {
+  // Use the secret value
+  console.log("API key retrieved");
+} else {
+  // Secret not found - handle gracefully
+  console.warn("API key secret not found");
+}
+```
+
+### Managing Secrets Programmatically
+
+You can also manage secrets programmatically (though typically users manage them through the UI):
+
+```ts
+// Set a secret
+this.app.secretStorage.setSecret("my-api-key", "actual-secret-value");
+
+// List all secrets
+const allSecrets = this.app.secretStorage.listSecrets();
+// Returns: ["my-api-key", "another-secret", ...]
+
+// Get a secret
+const value = this.app.secretStorage.getSecret("my-api-key");
+// Returns: "actual-secret-value" or null if not found
+```
+
+**Important**: Secret IDs must be lowercase alphanumeric with optional dashes (e.g., `my-plugin-api-key`). Invalid IDs will throw an error.
+
+See [security-privacy.md](security-privacy.md) for security best practices and [code-patterns.md](code-patterns.md) for comprehensive examples with error handling.
+
+## Modal Patterns
+
+**Source**: Based on `.ref/obsidian-sample-plugin/main.ts` and `.ref/obsidian-plugin-docs/docs/guides/modals.md`
+
+Simple modal:
+
+```ts
+import { App, Modal } from "obsidian";
+
+class MyModal extends Modal {
+  constructor(app: App) {
+    super(app);
+  }
+
+  onOpen() {
+    const { contentEl } = this;
+    contentEl.setText("Modal content");
+  }
+
+  onClose() {
+    const { contentEl } = this;
+    contentEl.empty();
+  }
+}
+
+// Open modal:
+new MyModal(this.app).open();
+```
+
+Modal with user input:
+
+```ts
+import { App, Modal, Setting } from "obsidian";
+
+class InputModal extends Modal {
+  result: string;
+  onSubmit: (result: string) => void;
+
+  constructor(app: App, onSubmit: (result: string) => void) {
+    super(app);
+    this.onSubmit = onSubmit;
+  }
+
+  onOpen() {
+    const { contentEl } = this;
+    contentEl.createEl("h1", { text: "Enter value" });
+
+    new Setting(contentEl)
+      .setName("Name")
+      .addText((text) =>
+        text.onChange((value) => {
+          this.result = value;
+        })
+      );
+
+    new Setting(contentEl)
+      .addButton((btn) =>
+        btn
+          .setButtonText("Submit")
+          .setCta()
+          .onClick(() => {
+            this.close();
+            this.onSubmit(this.result);
+          })
+      );
+  }
+
+  onClose() {
+    const { contentEl } = this;
+    contentEl.empty();
+  }
+}
+```
+
+## Custom Views
+
+**Source**: Based on `.ref/obsidian-plugin-docs/docs/guides/custom-views.md`
+
+```ts
+import { ItemView, WorkspaceLeaf } from "obsidian";
+
+export const VIEW_TYPE_MY_VIEW = "my-view";
+
+export class MyView extends ItemView {
+  constructor(leaf: WorkspaceLeaf) {
+    super(leaf);
+  }
+
+  getViewType() {
+    return VIEW_TYPE_MY_VIEW;
+  }
+
+  getDisplayText() {
+    return "My View";
+  }
+
+  async onOpen() {
+    const container = this.containerEl.children[1];
+    container.empty();
+    container.createEl("h4", { text: "My View Content" });
+  }
+
+  async onClose() {
+    // Clean up resources
+  }
+}
+
+// In main plugin class:
+async onload() {
+  this.registerView(VIEW_TYPE_MY_VIEW, (leaf) => new MyView(leaf));
+  
+  // Activate view:
+  await this.activateView();
+}
+
+async activateView() {
+  const { workspace } = this.app;
+  let leaf = workspace.getLeavesOfType(VIEW_TYPE_MY_VIEW)[0];
+  
+  if (!leaf) {
+    leaf = workspace.getRightLeaf(false);
+    await leaf.setViewState({ type: VIEW_TYPE_MY_VIEW, active: true });
+  }
+  
+  workspace.revealLeaf(leaf);
+}
+
+async onunload() {
+  this.app.workspace.detachLeavesOfType(VIEW_TYPE_MY_VIEW);
+}
+```
+
+**Warning**: Never store references to views. Use `getLeavesOfType()` to access view instances.
+
+## Status Bar Items
+
+**Source**: Based on `.ref/obsidian-sample-plugin/main.ts` and `.ref/obsidian-plugin-docs/docs/guides/status-bar.md`
+
+```ts
+// Add status bar item (not supported on mobile)
+const statusBarItemEl = this.addStatusBarItem();
+statusBarItemEl.setText("Status text");
+
+// Or create custom elements:
+const statusBarItemEl = this.addStatusBarItem();
+statusBarItemEl.createEl("span", { text: "Status: " });
+statusBarItemEl.createEl("span", { text: "Active" });
+```
+
+## Ribbon Icons
+
+**Source**: Based on `.ref/obsidian-sample-plugin/main.ts` and `.ref/obsidian-plugin-docs/docs/guides/ribbon-actions.md`
+
+```ts
+const ribbonIconEl = this.addRibbonIcon("dice", "My Plugin", (evt: MouseEvent) => {
+  new Notice("Ribbon clicked!");
+});
+
+// Add CSS class for styling:
+ribbonIconEl.addClass("my-plugin-ribbon-class");
+```
+
+## Editor Commands
+
+**Source**: Based on `.ref/obsidian-sample-plugin/main.ts`
+
+```ts
+this.addCommand({
+  id: "editor-command",
+  name: "Editor command",
+  editorCallback: (editor: Editor, view: MarkdownView) => {
+    const selection = editor.getSelection();
+    editor.replaceSelection("Replaced text");
+  },
+});
+```
+
+## Complex Commands with Conditions
+
+**Source**: Based on `.ref/obsidian-sample-plugin/main.ts`
+
+```ts
+this.addCommand({
+  id: "conditional-command",
+  name: "Conditional command",
+  checkCallback: (checking: boolean) => {
+    const markdownView = this.app.workspace.getActiveViewOfType(MarkdownView);
+    if (markdownView) {
+      if (!checking) {
+        // Execute command
+        this.doAction();
+      }
+      return true; // Command is available
+    }
+    return false; // Command is not available
+  },
+});
+```
+
+The `checkCallback` receives a `checking` boolean:
+- When `true`: Only check if command can run (don't execute)
+- When `false`: Actually execute the command
+
+

package/obsidian-dev-themes/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: obsidian-dev-themes
+description: CSS/SCSS development patterns for Obsidian themes. Load when working with theme.css, SCSS variables, or CSS selectors.
+---
+
+# Obsidian Theme Development Skill
+
+This skill provides patterns and rules for developing Obsidian themes, focusing on CSS/SCSS development, styling conventions, and theme-specific coding practices.
+
+## Purpose
+
+To ensure consistent theme development, proper CSS organization, and adherence to Obsidian's theming patterns and CSS variable usage.
+
+## When to Use
+
+Load this skill when:
+- Writing or modifying CSS/SCSS for `theme.css`
+- Working with Obsidian's CSS variables and theming system
+- Implementing responsive design or dark/light mode support
+- Debugging CSS layout or styling issues
+- Following CSS/SCSS coding conventions
+
+## Core Rules
+
+- **Use Obsidian CSS Variables**: Always prefer Obsidian's built-in CSS variables over hardcoded values
+- **Follow BEM Methodology**: Use Block-Element-Modifier naming for CSS classes
+- **Mobile-First**: Consider mobile layouts and responsive design
+- **Dark/Light Mode Support**: Test themes in both light and dark modes
+- **Performance**: Minimize CSS complexity and avoid expensive selectors
+
+## Bundled Resources
+
+- `references/theme-best-practices.md`: Essential CSS patterns and Obsidian variable usage
+- `references/theme-coding-conventions.md`: CSS/SCSS style guidelines and naming conventions

package/obsidian-dev-themes/references/theme-best-practices.md

@@ -0,0 +1,50 @@
+# Theme Development Best Practices
+
+## CSS Organization
+- Group related styles together (Editor, UI, Sidebar, etc.)
+- Use comments to separate major sections
+- Keep specificity low for easy customization
+
+## Obsidian CSS Variables
+Always prefer Obsidian's built-in CSS variables over hardcoded values:
+
+```css
+/* Good */
+.theme-dark {
+  --my-accent: var(--interactive-accent);
+  background-color: var(--background-primary);
+  color: var(--text-normal);
+}
+
+/* Avoid */
+.theme-dark {
+  background-color: #2d2d30;
+  color: #cccccc;
+}
+```
+
+## Responsive Design
+```css
+/* Mobile-first approach */
+.my-component {
+  width: 100%;
+}
+
+@media (min-width: 768px) {
+  .my-component {
+    width: 50%;
+  }
+}
+```
+
+## Dark/Light Mode Support
+```css
+/* Support both themes */
+.theme-dark .my-element {
+  background: var(--background-primary);
+}
+
+.theme-light .my-element {
+  background: var(--background-secondary);
+}
+```

package/obsidian-dev-themes/references/theme-coding-conventions.md

@@ -0,0 +1,45 @@
+# Theme Coding Conventions
+
+## CSS/SCSS Guidelines
+
+### Naming Conventions
+- Use lowercase with hyphens for class names: `.my-component`
+- Follow BEM methodology: `.block__element--modifier`
+- Prefix custom classes: `.obsidian-my-theme-`
+
+### Structure
+```scss
+// Variables at top
+:root {
+  --my-theme-primary: #007acc;
+  --my-theme-secondary: #cccccc;
+}
+
+// Component styles
+.obsidian-my-theme {
+  &__header {
+    background: var(--my-theme-primary);
+
+    &--dark {
+      background: darken(var(--my-theme-primary), 20%);
+    }
+  }
+
+  &__content {
+    color: var(--text-normal);
+  }
+}
+```
+
+### Best Practices
+- Use SCSS nesting sparingly (max 3 levels)
+- Always use Obsidian CSS variables when available
+- Comment complex selectors and their purpose
+- Group related styles together
+- Test in both light and dark themes
+
+### Performance
+- Avoid universal selectors (`*`)
+- Minimize CSS specificity
+- Use efficient selectors (prefer classes over complex selectors)
+- Keep CSS bundle size reasonable

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "obsidian-dev-skills",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Agent skills for Obsidian plugin and theme development",
   "keywords": [
     "obsidian",
@@ -19,10 +19,18 @@
   "license": "MIT",
   "author": "David V. Kimball",
   "files": [
-    "obsidian-dev/",
+    "obsidian-dev-plugins/",
+    "obsidian-dev-themes/",
     "obsidian-ops/",
-    "obsidian-ref/"
+    "obsidian-ref/",
+    "scripts/"
   ],
+  "bin": {
+    "obsidian-dev-skills": "./scripts/init.mjs"
+  },
+  "scripts": {
+    "postinstall": "node ./scripts/init.mjs"
+  },
   "engines": {
     "node": ">=16.0.0"
   }