obsidian-dev-skills 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 David V. Kimball
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# Obsidian Development Skills
+
+This repository contains centralized AI agent skills for Obsidian plugin and theme development. It provides a single source of truth for development guidance, patterns, and best practices.
+
+## Repository Structure
+
+```
+obsidian-dev-skills/
+├── obsidian-dev-plugins/     # Plugin development skills
+├── obsidian-dev-themes/      # Theme development skills
+├── obsidian-ops/            # Operations & workflows
+└── obsidian-ref/            # Technical references
+```
+
+## Getting Started
+
+### For Developers
+
+This repository is automatically set up by the `setup-ref-links` script in the template projects.
+
+### For Users
+
+This repository is automatically managed by the template projects. Simply run the `setup-ref-links` script in your template project to get started.
+
+### For Developers
+
+The `setup-ref-links` script clones this repository to your `.ref` folder and creates the necessary symlinks.
+
+## Skills Overview
+
+### obsidian-dev-plugins
+- TypeScript/JavaScript development patterns
+- Obsidian API usage
+- Plugin lifecycle management
+- Command and settings implementation
+
+### obsidian-dev-themes
+- CSS/SCSS development patterns
+- Obsidian CSS variables
+- Responsive design
+- Dark/light mode support
+
+### obsidian-ops
+- Build and release workflows
+- Version management
+- Sync procedures
+- Testing and quality assurance
+
+### obsidian-ref
+- API documentation
+- Manifest requirements
+- File formats
+- UI/UX guidelines
+
+## Project-Specific Skills
+
+Each project should also have a `project/` skill in `.agent/skills/project/` that contains:
+- Project-specific architecture details
+- Unique conventions and patterns
+- Maintenance tasks
+- Local workflow documentation
+
+## Maintenance
+
+### Updating Skills
+
+When skills are updated in this repository, all linked projects automatically get the updates. No manual sync required.
+
+### Tracking Sync Status
+
+Each project maintains its own `sync-status.json` file to track when reference materials were last updated.
+
+## Compatibility
+
+- **Cursor**: Primary supported AI agent
+- **Open Cognitive Skills (OCS) Specification**: [https://github.com/AI-CAMEL/Skills-Specification](https://github.com/AI-CAMEL/Skills-Specification)
+
+## Contributing
+
+Skills are maintained centrally to ensure consistency across all Obsidian projects. Updates should be made here and will automatically propagate to all linked projects.

package/obsidian-ops/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: obsidian-ops
+description: Operations, syncing, versioning, and release management for Obsidian projects. Load when running builds, syncing references, bumping versions, or preparing for release.
+---
+
+# Obsidian Operations Skill
+
+This skill covers the operational aspects of maintaining an Obsidian project, including build workflows, sync procedures, and release management.
+
+## Purpose
+
+To ensure reliable builds, consistent reference materials, and safe release processes while strictly following project policies.
+
+## When to Use
+
+Load this skill when:
+- Running build or lint commands.
+- Syncing reference documentation from external sources.
+- Bumping project versions or preparing releases.
+- Troubleshooting build or environment issues.
+
+## Core Rules
+
+- **NEVER perform automatic git operations**: AI agents must never execute `git commit`, `git push`, or any command that automatically stages or commits changes without explicit user approval for each step.
+- **Verify Build**: Always run a build/lint after significant changes to ensure compatibility.
+- **Sync Status**: Keep `sync-status.json` updated when updating reference materials.
+
+## Bundled Resources
+
+- `references/build-workflow.md`: Standard build and development commands.
+- `references/release-readiness.md`: Checklist for ensuring a project is ready for release.
+- `references/sync-procedure.md`: How to pull updates from reference repositories.
+- `references/versioning-releases.md`: Workflow for versioning and GitHub releases.
+- `references/troubleshooting.md`: Common issues and their resolutions.
+- `references/quick-reference.md`: One-page cheat sheet for common operations.

package/obsidian-ops/references/build-workflow.md

@@ -0,0 +1,75 @@
+<!--
+Source: Project-specific workflow
+Last synced: See sync-status.json for authoritative sync dates
+Update frequency: Update as build process evolves
+-->
+
+# Build Workflow
+
+**CRITICAL**: Always run the build command after making changes to catch errors early.
+
+After making any changes to theme code:
+
+### Simple CSS Themes
+
+If your theme is simple with just `theme.css` in the root and no build tools:
+
+- **No build step required** - just edit `theme.css` directly
+- Changes take effect immediately when Obsidian reloads the theme (reload Obsidian with Ctrl+R / Cmd+R)
+- **Linting**: Run `npm run lint` to check CSS quality (optional but recommended)
+
+**How to detect**: If you have `theme.css` in root and no `src/scss/` directory, you have a simple CSS theme.
+
+### Complex Themes (SCSS + Build Tools)
+
+If your theme uses build tools (Grunt, npm scripts, SCSS compiler, etc.) and has `src/scss/` directory:
+
+1. **Run the build** (assume npm is already installed):
+   ```powershell
+   # For themes using Grunt (like obsidian-oxygen)
+   npx grunt build
+   
+   # For themes using npm scripts
+   npm run build
+   
+   # For themes using Grunt watch mode (auto-rebuild on changes)
+   npx grunt
+   
+   # Or whatever build command your theme uses
+   ```
+
+2. **If the build fails with npm/node errors**, then check if npm is installed:
+   ```powershell
+   npm --version
+   ```
+   - If npm is not found, inform the user that Node.js (which includes npm) needs to be installed
+   - Do not automatically install npm - let the user handle installation
+
+3. **Check for errors** and fix any build issues before proceeding. See [troubleshooting.md](troubleshooting.md) for common build issues.
+
+4. **Linting**: Run `npm run lint` to check SCSS/CSS quality. The lint wrapper automatically detects SCSS files in `src/scss/` and lints them appropriately.
+
+**How to detect**: If you have a `src/scss/` directory, you have a complex theme with build tools. Check for `Gruntfile.js`, `package.json` scripts, or other build configuration files.
+
+**Common build tools**:
+- **Grunt**: Look for `Gruntfile.js` → Run `npx grunt build` or `npx grunt` (watch mode)
+- **npm scripts**: Check `package.json` for `build` script → Run `npm run build`
+- **Sass CLI**: Some themes use `sass` directly → Check `package.json` scripts
+
+## Why This Matters
+
+- **Catches errors early**: Build errors are easier to fix immediately after making changes
+- **Prevents broken code**: Ensures the project always builds successfully
+- **Saves time**: Fixing build errors right away is faster than discovering them later
+- **Maintains quality**: Keeps the codebase in a working state
+
+## Automated Workflow
+
+When making changes:
+1. Make the code change
+2. **Immediately run the build command**
+3. If build fails, fix errors
+4. Repeat until build succeeds
+5. Then proceed with testing or other tasks
+
+

package/obsidian-ops/references/performance.md

@@ -0,0 +1,14 @@
+<!--
+Source: Based on Obsidian community best practices
+Last synced: See sync-status.json for authoritative sync dates
+Update frequency: Check Obsidian community discussions for updates
+-->
+
+# Performance
+
+- Keep CSS file size reasonable. Large themes can slow down Obsidian startup.
+- Use CSS variables efficiently. Avoid excessive specificity.
+- Minimize use of complex selectors that require expensive DOM queries.
+- Test theme performance on lower-end devices, especially mobile.
+
+

package/obsidian-ops/references/quick-reference.md

@@ -0,0 +1,169 @@
+<!--
+Source: Condensed from all reference documentation
+Last synced: See sync-status.json for authoritative sync dates
+Update frequency: Update as workflows evolve
+-->
+
+# Quick Reference
+
+One-page cheat sheet for common Obsidian theme development tasks.
+
+## Quick Commands
+
+**One-word or short commands that trigger automatic actions:**
+
+| Command | Action |
+|---------|--------|
+| `build` | Run build command (varies by theme: `npx grunt build`, `npm run build`, etc.) |
+| `sync` or `quick sync` | Pull latest changes from all 6 core `.ref` repos |
+| `what's the latest` or `check updates` | Check what's new in reference repos (read-only, then ask to pull) |
+| `release ready?` or `is my theme ready for release?` | Run comprehensive release readiness checklist |
+| `summarize` | Generate git commit message from all changed files |
+| `summarize for release` | Generate markdown release notes for GitHub |
+| `bump the version` or `bump version` | Bump version by 0.0.1 (patch) by default, or specify: `patch`, `minor`, `major`, or exact version |
+| `add ref [name]` | Add a reference project (external URL or local path) |
+| `check API [feature]` | Look up a feature in `.ref/obsidian-api/obsidian.d.ts` |
+
+**Usage examples:**
+- `build` → Runs build command automatically
+- `sync` → Pulls latest from all core repos automatically
+- `bump the version` → Bumps version by 0.0.1 (patch) in manifest.json
+- `bump version minor` → Bumps minor version (e.g., 1.0.0 → 1.1.0)
+- `bump version major` → Bumps major version (e.g., 1.0.0 → 2.0.0)
+- `add ref my-plugin https://github.com/user/my-plugin.git` → Clones external repo
+- `add ref ../my-local-plugin` → Creates symlink to local project
+- `check API [feature]` → Searches obsidian.d.ts for feature (for theme CSS variables, etc.)
+
+**Note**: These commands are interpreted by AI agents and execute the corresponding workflows automatically. See detailed documentation in [AGENTS.md](../../AGENTS.md) for full workflows.
+
+## Build Commands
+
+**Simple CSS themes**: No build step required - just edit `theme.css` directly.
+
+**Complex themes with build tools**:
+```powershell
+npx grunt build  # For themes using Grunt
+npm run build    # For themes using npm scripts
+npx grunt        # Watch mode (auto-rebuild on changes)
+```
+
+**Always run build after making changes** to catch errors early. See [build-workflow.md](build-workflow.md).
+
+## File Paths
+
+**Theme location** (in vault):
+```
+<Vault>/.obsidian/themes/<theme-name>/
+  ├── theme.css        # Compiled theme CSS
+  └── manifest.json    # Theme manifest
+```
+
+**Build output**: Must be at top level of theme folder in vault.
+
+## CSS Patterns
+
+**CSS Variables** (for theming):
+```css
+:root {
+  --color-base-00: #ffffff;
+  --color-base-10: #f7f6f3;
+  --color-text-normal: #383a42;
+}
+```
+
+**Dark Mode**:
+```css
+.theme-dark {
+  --color-base-00: #1e1e1e;
+  --color-base-10: #252525;
+  --color-text-normal: #dcddde;
+}
+```
+
+See Obsidian's CSS variables documentation for complete variable list.
+
+## Git Workflow
+
+**Commit message format** (from [summarize-commands.md](summarize-commands.md)):
+```
+[Summary of changes]
+- [detailed item 1]
+- [detailed item 2]
+```
+
+**Release notes format** (markdown):
+```markdown
+### Release v1.2.0 - Title
+
+### Features
+- Feature description
+
+### Improvements
+- Improvement description
+```
+
+## Release Preparation
+
+**Before releasing**:
+- Run release readiness check: See [release-readiness.md](release-readiness.md)
+- Verify all checklist items (platform testing, files, policies, etc.)
+- Ensure LICENSE file exists and third-party code is properly attributed
+
+See [versioning-releases.md](versioning-releases.md) for release process.
+
+## Sync Reference Repos
+
+**Quick pull all 6 core repos** (from [quick-sync-guide.md](quick-sync-guide.md)):
+```bash
+# Navigate to central .ref location (adjust path as needed)
+cd ../.ref/obsidian-dev  # or cd ~/Development/.ref/obsidian-dev
+
+# Pull all repos
+cd obsidian-api && git pull && cd ..
+cd obsidian-sample-plugin && git pull && cd ..
+cd obsidian-developer-docs && git pull && cd ..
+cd obsidian-plugin-docs && git pull && cd ..
+cd obsidian-sample-theme && git pull && cd ..
+cd eslint-plugin && git pull && cd ..
+```
+
+**Note**: If using symlinks, navigate to the actual target location (usually `..\.ref\obsidian-dev`) before running git commands. See [quick-sync-guide.md](quick-sync-guide.md) for setup detection.
+
+## Reference Materials
+
+**Check `.ref/obsidian-api/obsidian.d.ts`** for CSS variable definitions and Obsidian's internal structure (useful for advanced theming).
+
+## Testing
+
+**Manual installation**:
+1. Build theme (if using build tools) or ensure `theme.css` is ready
+2. Copy `manifest.json` and `theme.css` to vault `.obsidian/themes/<theme-name>/`
+3. Select theme in Obsidian: **Settings → Appearance → Themes**
+4. Reload Obsidian (Ctrl+R / Cmd+R) to see changes
+
+See [testing.md](testing.md) for details.
+
+## Common File Structure
+
+**Simple CSS theme**:
+```
+theme.css          # Source CSS (edit directly)
+manifest.json
+package.json
+```
+
+**Complex theme with build tools**:
+```
+src/
+  scss/
+    index.scss
+    variables.scss
+    components/
+theme.css          # Compiled output
+manifest.json
+package.json
+Gruntfile.js       # Build configuration (if using Grunt)
+```
+
+See [file-conventions.md](file-conventions.md) for details.
+

package/obsidian-ops/references/quick-sync-guide.md

@@ -0,0 +1,166 @@
+<!--
+Source: Project-specific quick reference
+Last synced: See sync-status.json for authoritative sync dates
+Update frequency: Update as needed
+-->
+
+# Quick Sync Guide
+
+This is a quick reference for pulling the latest changes from reference repositories. For detailed sync procedures, see [sync-procedure.md](sync-procedure.md).
+
+## Determine Your Setup First
+
+**IMPORTANT**: Before syncing, check if `.ref` contains symlinks or actual repos. Git operations must be performed on the **actual target location**, not on symlinks.
+
+**Windows (PowerShell)**:
+```powershell
+Get-Item .ref/obsidian-api | Select-Object LinkType, Target
+# If LinkType shows "Junction" or "SymbolicLink", you're using symlinks
+# The Target property shows where the symlink points (usually ..\.ref\obsidian-dev)
+```
+
+**macOS/Linux**:
+```bash
+ls -la .ref/obsidian-api
+# If it shows "->" with a path, it's a symlink
+# Use readlink to see the target: readlink -f .ref/obsidian-api
+```
+
+**If using symlinks**: Navigate to the central location (usually `..\.ref\obsidian-dev` or `~/Development/.ref/obsidian-dev`) before running git commands.
+
+**If using local clones**: Run commands from project root, navigating to each `.ref/` subdirectory.
+
+## What Does `git pull` Do?
+
+When you run `git pull` in a reference repository:
+1. **Fetches** the latest commits from the remote repository (GitHub)
+2. **Merges** those changes into your local copy
+3. **Updates** all files in that repository to the latest version
+
+**Important**: This only updates the files in `.ref/` - it does NOT automatically update your `.agents/` files. You need to manually review and sync changes.
+
+## Quick Pull Commands
+
+### If Using Symlinks (Central Location)
+
+```bash
+# Navigate to your central refs directory (adjust path as needed)
+cd ../.ref/obsidian-dev  # or cd ~/Development/.ref/obsidian-dev
+
+# Pull all repos at once
+cd obsidian-api && git pull && cd ..
+cd obsidian-sample-plugin && git pull && cd ..
+cd obsidian-developer-docs && git pull && cd ..
+cd obsidian-plugin-docs && git pull && cd ..
+cd obsidian-sample-theme && git pull && cd ..
+cd eslint-plugin && git pull && cd ..
+```
+
+Or use a simple loop (bash/zsh):
+```bash
+cd ../.ref/obsidian-dev  # or cd ~/Development/.ref/obsidian-dev
+for repo in obsidian-api obsidian-sample-plugin obsidian-developer-docs obsidian-plugin-docs obsidian-sample-theme eslint-plugin; do
+    echo "Pulling $repo..."
+    cd "$repo" && git pull && cd ..
+done
+```
+
+Or PowerShell (Windows):
+```powershell
+cd ..\.ref\obsidian-dev  # Adjust path as needed
+foreach ($repo in @('obsidian-api', 'obsidian-sample-plugin', 'obsidian-developer-docs', 'obsidian-plugin-docs', 'obsidian-sample-theme', 'eslint-plugin')) {
+    Write-Host "Pulling $repo..."
+    cd $repo
+    git pull
+    cd ..
+}
+```
+
+### If Using Local Clones (In Project)
+
+```bash
+# From your project root
+cd .ref
+
+# Pull each repo (always start from project root for each command)
+cd obsidian-api && git pull && cd ../..
+cd obsidian-sample-plugin && git pull && cd ../..
+cd obsidian-developer-docs && git pull && cd ../..
+cd obsidian-plugin-docs && git pull && cd ../..
+cd obsidian-sample-theme && git pull && cd ../..
+cd eslint-plugin && git pull && cd ../..
+```
+
+## Check What Changed
+
+After pulling, see what's new:
+
+```bash
+# See recent commits in a repo
+cd .ref/obsidian-sample-plugin
+git log --oneline -10
+
+# See what files changed in the last update
+git diff HEAD~1 HEAD --name-only
+
+# See detailed changes to a specific file (e.g., AGENTS.md)
+git diff HEAD~1 HEAD -- AGENTS.md
+
+# See changes since your last pull (if you know the commit)
+git log --oneline --since="2 weeks ago"
+```
+
+## What to Look For
+
+After pulling, check these key files for changes:
+
+- **obsidian-sample-plugin/AGENTS.md** → Compare with your `.agents/` files
+- **obsidian-sample-plugin/README.md** → Check for new setup instructions
+- **obsidian-api/** → Look for new API documentation or breaking changes
+- **obsidian-developer-docs/en/** → Check for updated official documentation
+- **obsidian-plugin-docs/** → Review for new plugin guidance
+
+## Next Steps
+
+After pulling and reviewing changes:
+
+1. **Compare** relevant files from `.ref/` with your `.agents/` files
+2. **Update** `.agents/` files with new information
+3. **Update** the "Last synced" date in file headers
+4. **Commit** your changes
+
+See [sync-procedure.md](sync-procedure.md) for the complete workflow.
+
+## Example: Quick Check Workflow
+
+```bash
+# 1. Pull all repos (using symlinks - adjust path as needed)
+cd ../.ref/obsidian-dev  # or cd ~/Development/.ref/obsidian-dev
+for repo in obsidian-api obsidian-sample-plugin obsidian-developer-docs obsidian-plugin-docs obsidian-sample-theme eslint-plugin; do
+    cd "$repo" && git pull && cd ..
+done
+
+# 2. Check if Sample Plugin's AGENTS.md changed
+cd obsidian-sample-plugin
+git log --oneline -5 -- AGENTS.md
+
+# 3. If it changed, see the diff
+git diff HEAD~1 HEAD -- AGENTS.md
+
+# 4. Now you can manually update your .agents files based on what changed
+```
+
+**PowerShell version (Windows)**:
+```powershell
+# 1. Pull all repos (using symlinks - adjust path as needed)
+cd ..\.ref\obsidian-dev
+foreach ($repo in @('obsidian-api', 'obsidian-sample-plugin', 'obsidian-developer-docs', 'obsidian-plugin-docs', 'obsidian-sample-theme', 'eslint-plugin')) {
+    cd $repo
+    git pull
+    cd ..
+}
+
+# 2-4. Same as above
+```
+
+