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/             # Plugin development skills
├── obsidian-theme-dev/       # Theme development skills
├── obsidian-ops/             # Operations & workflows
└── obsidian-ref/             # Technical references

Installation & Usage

This package can be used as a development dependency in your Obsidian project.

1. Install to your project

# Using pnpm (Recommended)
pnpm add -D obsidian-dev-skills

# Using npm
npm install --save-dev obsidian-dev-skills

# Using yarn
yarn add -D obsidian-dev-skills

2. Initialize localized skills

Run the initialization script to seed the .agent/skills/ folder and sync AGENTS.md. This also creates a project-specific skill template if one is missing.

# Using pnpm (Standard entry point)
pnpm obsidian-dev-skills

# Using npx (Universal entry point)
npx obsidian-dev-skills

# Manual execution
node node_modules/obsidian-dev-skills/scripts/init.mjs

Skills Overview

obsidian-dev

• TypeScript/JavaScript development patterns
• Obsidian API usage
• Plugin lifecycle management
• Command and settings implementation
• obsidianmd ESLint rule patterns (createDiv/createSpan, activeWindow, activeDocument, sentence case)

obsidian-theme-dev

• 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 community scorecard compliance mapping (vulnerable transitive dep handling via pnpm.overrides, duplicate CSS selector detection, ESLint rule violations)
• Release workflow with build provenance attestation (actions/attest-build-provenance@v2)
• Portable CONTRIBUTING.md template for the scorecard hygiene check

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

The update flow depends on how a project consumes this package:

• npm install (default): When this package publishes a new version, downstream projects pick up updates the next time they run pnpm obsidian-dev-skills (or the equivalent npx/manual command). The init script re-copies skill files into .agent/skills/.
• Sibling clone + symlinks (advanced): If a project symlinks .agent/skills/<name> to a sibling clone of this repository (e.g. via scripts/setup-local.ps1), updates appear instantly the moment files change here, with no per-project sync step.

Tracking Sync Status

Each project maintains its own sync-status.json file to track when reference materials were last updated.

Compatibility

• AI Agents: Compatible with any AI agent supporting the Open Cognitive Skills (OCS) Specification
• IDEs: Works across all development environments (VS Code, Cursor, JetBrains IDEs, etc.)
• Specification: Compatible with the OpenSkills format

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.