obsidian-dev-skills 1.0.4 → 1.0.6

package/README.md

@@ -12,19 +12,42 @@ obsidian-dev-skills/
 └── obsidian-ref/             # Technical references
 ```
 
-## Getting Started
+## Installation & Usage
 
-### For Developers
+This package can be used as a development dependency in your Obsidian project.
 
-This repository is automatically set up by the `setup-ref-links` script in the template projects.
+### 1. Install to your project
+```bash
+# Using pnpm (Recommended)
+pnpm add -D obsidian-dev-skills
 
-### For Users
+# Using npm
+npm install --save-dev obsidian-dev-skills
 
-This repository is automatically managed by the template projects. Simply run the `setup-ref-links` script in your template project to get started.
+# Using yarn
+yarn add -D obsidian-dev-skills
+```
+
+### 2. Initialize localized skills
+Run the initialization script to seed the `.agent/skills/` folder. This also creates a project-specific skill template if one is missing.
 
-### For Developers
+```bash
+# Using pnpm (Standard entry point)
+pnpm obsidian-dev-skills
 
-The `setup-ref-links` script clones this repository to your `.ref` folder and creates the necessary symlinks.
+# Using npx (Universal entry point)
+npx obsidian-dev-skills
+
+# Manual execution
+node node_modules/obsidian-dev-skills/scripts/init.mjs
+```
+
+### 3. Sync AI Agents
+Ensure `AGENTS.md` is aligned with the localized skills.
+
+```bash
+npx openskills sync
+```
 
 ## Skills Overview
 

package/obsidian-ops/references/sync-procedure.md

@@ -61,9 +61,15 @@ if ($item.LinkType -eq "Junction" -or $item.LinkType -eq "SymbolicLink") {
 ```bash
 # Check if a specific repo is a symlink
 if [ -L .ref/obsidian-api ]; then
-    echo "Symlink detected - target: $(readlink .ref/obsidian-api)"
+    # Portable approach for macOS/BSD and Linux
+    if command -v realpath >/dev/null 2>&1; then
+        TARGET=$(realpath .ref/obsidian-api)
+    else
+        TARGET=$(readlink .ref/obsidian-api)
+    fi
+    echo "Symlink detected - target: $TARGET"
     # Navigate to the actual target location
-    cd "$(readlink -f .ref/obsidian-api)"
+    cd "$TARGET"
 else
     echo "Regular directory - can use .ref/obsidian-api directly"
     cd .ref/obsidian-api
@@ -97,7 +103,12 @@ cd eslint-plugin; git pull; cd ..
 **macOS/Linux**:
 ```bash
 # First, check where symlinks point (usually ../.ref/obsidian-dev)
-TARGET=$(readlink -f .ref/obsidian-api | sed 's|/obsidian-api$||')
+if command -v realpath >/dev/null 2>&1; then
+    TARGET_REPO=$(realpath .ref/obsidian-api)
+else
+    TARGET_REPO=$(readlink .ref/obsidian-api)
+fi
+TARGET=$(echo "$TARGET_REPO" | sed 's|/obsidian-api$||')
 echo "Symlinks point to: $TARGET"
 
 # Navigate to central location and update all repos

package/obsidian-ops/references/troubleshooting.md

@@ -25,7 +25,7 @@ Update frequency: Update as common issues are identified
 - Use `list_dir` with the project root to see hidden directories
 - Use `glob_file_search` with pattern `.ref/**` to search recursively
 - Try direct paths like `.ref/obsidian-api/README.md`
-- See [ref-instructions.md](ref-instructions.md) for detailed search strategies
+- See [sync-procedure.md](sync-procedure.md) for detailed search strategies
 
 **For AI agents**: When user asks about `.ref`, actively search using multiple methods. Don't assume it doesn't exist if first search fails.
 

package/obsidian-ops/references/versioning-releases.md

@@ -6,11 +6,19 @@ Update frequency: Check Obsidian Sample Theme repo for updates
 
 # Versioning & releases
 
-**Before releasing**: Use the comprehensive [release-readiness.md](release-readiness.md) checklist to verify your theme is ready for release.
+**Before releasing**: Use the comprehensive [release-readiness.md](release-readiness.md) checklist to verify your project is ready for release.
 
 - Bump `version` in `manifest.json` (SemVer).
 - Create a GitHub release whose tag exactly matches `manifest.json`'s `version`. Do not use a leading `v`.
+### Theme Releases
 - Attach `manifest.json` and `theme.css` to the release as individual assets.
 - After the initial release, follow the process to add/update your theme in the community catalog as required.
 
+### Plugin Releases
+- Attach `main.js`, `manifest.json`, and `styles.css` to the release as individual assets.
+- Follow the plugin submission process to add/update your plugin in the community catalog.
+
+> [!NOTE]
+> Themes and plugins have different asset requirements and submission paths. Ensure you follow the correct flow for your project type.
+
 

package/obsidian-ref/references/file-conventions.md

@@ -12,7 +12,7 @@ Update frequency: Check Obsidian Sample Theme repo for updates
   - **Complex theme with build tools** (for themes using SCSS, Grunt, etc.): `src/scss/` directory with SCSS source files that compile to `theme.css`
   - **CRITICAL**: Never have both `theme.css` as source AND `src/scss/` - choose one pattern
 
-### Simple CSS Theme Structure
+## Simple CSS Theme Structure
 
 **Recommended for simple themes** (like the sample theme template):
 ```
@@ -25,7 +25,7 @@ package.json
 - Changes take effect when Obsidian reloads the theme
 - Perfect for learning and simple themes
 
-### Complex Theme Structure (SCSS + Build Tools)
+## Complex Theme Structure (SCSS + Build Tools)
 
 **For themes using SCSS, Grunt, npm scripts, or other build tools**:
 ```
@@ -47,7 +47,7 @@ package.json
 - Run build command after making changes (see [build-workflow.md](build-workflow.md))
 - **Example**: The `obsidian-oxygen` theme uses this pattern with Grunt
 
-### Wrong Structure (Common Mistakes)
+## Wrong Structure (Common Mistakes)
 
 ```
 theme.css         # ❌ DON'T have both

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "obsidian-dev-skills",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Agent skills for Obsidian plugin and theme development",
   "keywords": [
     "obsidian",

package/scripts/init.mjs

@@ -109,6 +109,88 @@ function detectProjectType(root) {
   return isPlugin ? 'plugin' : 'theme';
 }
 
+/**
+ * Updates AGENTS.md in the project root to include the installed skills in the openskills format.
+ */
+function updateAgentsMarkdown(root, installedSkills) {
+  const agentsPath = path.join(root, 'AGENTS.md');
+  const agentDirName = path.basename(agentDir); // .agent or .agents
+
+  const skillDetails = {
+    'obsidian-dev': 'Core development patterns for Obsidian plugins. Load when editing src/main.ts, implementing features, handling API calls, or managing plugin lifecycle.',
+    'obsidian-theme-dev': 'CSS/SCSS development patterns for Obsidian themes. Load when working with theme.css, SCSS variables, or CSS selectors.',
+    'obsidian-ops': 'Operations, syncing, versioning, and release management for Obsidian projects. Load when running builds, syncing references, bumping versions, or preparing for release.',
+    'obsidian-ref': 'Technical references, manifest rules, file formats, and UX guidelines for Obsidian. Load when checking API details, manifest requirements, or UI/UX standards.',
+    'project': 'Project-specific architecture, maintenance tasks, and unique conventions for this repository. Load when performing project-wide maintenance or working with the core architecture.'
+  };
+
+  const skillTags = installedSkills
+    .map(skill => {
+      const description = skillDetails[skill] || 'Specialized skill for this project.';
+      return `<skill>
+<name>${skill}</name>
+<description>${description}</description>
+<location>project</location>
+</skill>`;
+    })
+    .join('\n\n');
+
+  const xmlSection = `<skills_system priority="1">
+
+## Available Skills
+
+<!-- SKILLS_TABLE_START -->
+<usage>
+When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge.
+
+How to use skills:
+- Read skill: \`cat ./${agentDirName}/skills/<skill-name>/SKILL.md\`
+- The skill content will load with detailed instructions on how to complete the task
+- Skills are stored locally in ./${agentDirName}/skills/ directory
+
+Usage notes:
+- Only use skills listed in <available_skills> below
+- Do not invoke a skill that is already loaded in your context
+- Each skill invocation is stateless
+</usage>
+
+<available_skills>
+
+${skillTags}
+
+</available_skills>
+<!-- SKILLS_TABLE_END -->
+
+</skills_system>`;
+
+  let content = '';
+  if (fs.existsSync(agentsPath)) {
+    content = fs.readFileSync(agentsPath, 'utf8');
+
+    const startMarker = '<skills_system';
+    const endMarker = '</skills_system>';
+    const htmlStartMarker = '<!-- SKILLS_TABLE_START -->';
+    const htmlEndMarker = '<!-- SKILLS_TABLE_END -->';
+
+    if (content.includes(startMarker)) {
+      const regex = /<skills_system[^>]*>[\s\S]*?<\/skills_system>/;
+      content = content.replace(regex, xmlSection);
+    } else if (content.includes(htmlStartMarker)) {
+      // Logic parity with openskills: replace content between HTML markers if XML tag is missing
+      const innerContent = xmlSection.replace(/<skills_system[^>]*>|<\/skills_system>/g, '').trim();
+      const regex = new RegExp(`${htmlStartMarker}[\\s\\S]*?${htmlEndMarker}`, 'g');
+      content = content.replace(regex, `${htmlStartMarker}\n${innerContent}\n${htmlEndMarker}`);
+    } else {
+      content = content.trimEnd() + '\n\n' + xmlSection + '\n';
+    }
+  } else {
+    content = '# AGENTS\n\nThis project uses specialized AI agent skills for development.\n\n' + xmlSection + '\n';
+  }
+
+  fs.writeFileSync(agentsPath, content, 'utf8');
+  console.log('📝 Updated AGENTS.md (openskills format)');
+}
+
 /**
  * Ensures a project-specific skill exists, creating a template if it doesn't.
  */
@@ -127,27 +209,51 @@ name: project
 description: Project-specific architecture, maintenance tasks, and unique conventions. Load when performing project-wide maintenance or working with the core architecture.
 ---
 
-# Project Skill
+# Project Context
+
+This skill provides the unique context and architectural details for this repository.
 
-Provide a high-level overview of this project's specific goals and architecture here.
+## Purpose
+
+To provide guidance on project-specific structures and tasks that differ from general Obsidian development patterns.
+
+## When to Use
+
+Load this skill when:
+- Understanding the repository's unique architecture.
+- Performing recurring maintenance tasks.
+- Following project-specific coding conventions.
+
+## Project Overview
+
+<!-- 
+TIP: Update this section with your project's high-level architecture.
+Example:
+- **Architecture**: Organized structure with main code in \`src/main.ts\` and settings in \`src/settings.ts\`.
+- **Reference Management**: Uses a \`.ref\` folder with symlinks to centralized Obsidian repositories.
+-->
+
+- **Primary Stack**: [e.g., TypeScript, Svelte, Lucide icons]
+- **Key Directories**: [e.g., src/, styles/, scripts/]
 
 ## Core Architecture
 
-- Detail the primary technical stack and how components interact.
+- [Detail how primary components interact here]
 
 ## Project-Specific Conventions
 
-- **Naming**: Describe any specific naming patterns used in this repo.
-- **Patterns**: Document unique implementation patterns (e.g., custom hooks, specific state management).
+- **Naming**: [e.g., class names use PascalCase, private methods prefixed with _]
+- **Patterns**: [e.g., use of custom stores, specific state management]
 
 ## Key Files
 
-- \`src/main.ts\`: [Description]
-- \`manifest.json\`: [Description]
+- \`manifest.json\`: Plugin/theme manifest
+- \`package.json\`: Build scripts and dependencies
 
 ## Maintenance Tasks
 
-- List recurring tasks like version bumping, CSS testing, or dependency updates.
+- [e.g., npm run dev to start development server]
+- [e.g., npm run version-bump to release new version]
 `;
     fs.writeFileSync(projectSkillFile, template, 'utf8');
   }
@@ -202,6 +308,15 @@ async function init() {
     // Ensure project-specific skill exists
     initializeProjectSkill(skillsDir);
 
+    // Update AGENTS.md
+    const installedSkills = Object.keys(skillMappings).filter(name => {
+      if (projectType === 'plugin' && name === 'obsidian-theme-dev') return false;
+      if (projectType === 'theme' && name === 'obsidian-dev') return false;
+      return true;
+    });
+    installedSkills.push('project'); // Always include project skill
+    updateAgentsMarkdown(projectRoot, installedSkills);
+
     // Update or create sync-status.json
     const syncStatusPath = path.join(agentDir, 'sync-status.json');
     const today = new Date().toISOString().split('T')[0];

package/scripts/setup-local.ps1

@@ -1,4 +1,4 @@
-# Setup skills symlinks for Obsidian Sample Plugin Plus
+# Setup skills symlinks for this repository
 # This script creates symlinks to the obsidian-dev-skills repository
 
 param(