Obsidian Data Importer

Activation Conditions

This skill activates when:

User uploads or provides CSV/JSON data files
User requests Obsidian import assistance
User mentions "Handlebars", "JSON/CSV Importer", "bulk import", or "data import"
User wants to create multiple Obsidian notes from structured data

Quick Start (3 Steps)

For immediate use:

Provide your data - Upload CSV/JSON file or paste content
Confirm mapping - Review proposed field assignments
Receive template - Get complete Handlebars template + instructions

→ Simple example: 01-task-list-csv

System Architecture

obsidian-data-importer/
├── core/              → Processing engines (5 phases + 4 modules)
├── knowledge/         → Reference documentation (syntax, types, errors)
├── templates/         → Pattern library (8 templates + partials)
└── examples/          → Complete demonstrations (12 workflows)

Component Diagram

[Data Input]
    ↓
[DataParser] ──→ [FieldAnalyzer] ──→ [TemplateGenerator] ──→ [Validator]
    ↓                ↓                      ↓                    ↓
 Parsed         Field Inventory        Template String      Validation
  Structure                                                   Report
                                           ↓
                                   [InstructionComposer]
                                           ↓
                                    Complete Package

Workflow Overview

The system executes in 5 sequential phases:

Phase	Purpose	Documentation	Output
1. Ingestion	Parse & analyze data structure	Phase 1	Field inventory
2. Strategy	Map fields & select pattern	Phase 2	Mapping decisions
3. Construction	Generate Handlebars template	Phase 3	Template string
4. Validation	Verify syntax & preview output	Phase 4	Validation report
5. Delivery	Package with instructions	Phase 5	Complete deliverable

Process Flow:

CSV/JSON → Parse → Analyze → Map → Generate → Validate → Deliver

Module Reference

Core Processing Modules

Module	Responsibility	Documentation	Key Functions
DataParser	Input format handling	data-parser.md	parseCSV(), parseJSON()
FieldAnalyzer	Type inference & analysis	field-analyzer.md	inferType(), detectIssues()
TemplateGenerator	Handlebars construction	template-generator.md	buildTemplate(), escapeYAML()
Validator	Syntax & correctness checking	validator.md	validateYAML(), testRender()

Knowledge Base

Topic	Content	Documentation
YAML Safety	Character escaping, quoting strategies	yaml-safety.md
Handlebars Syntax	Variables, conditionals, iteration	handlebars-syntax.md
Type Mapping	Detection algorithms, strategies	type-mapping.md
Error Resolution	Common problems & solutions	error-resolution.md
Best Practices	Optimization guidelines	best-practices.md

Template Library

Base Templates

base-generic.hbs - Minimal universal structure
base-full.hbs - Comprehensive with all features
base-minimal.hbs - Bare essentials only

Domain-Specific Templates

task-management.hbs - Tasks, projects, status tracking
reference-material.hbs - Books, articles, sources
people-contacts.hbs - Networking, relationships
events-timeline.hbs - Chronological data
inventory-catalog.hbs - Items, products, assets

Template Composition: All templates use modular partials from templates/partials/ for maximum reusability.

Common Tasks (Quick Recipes)

Task	Complexity	Example	Duration
Import simple CSV	⭐	01-task-list-csv	3 min
Handle special characters	⭐⭐	02-contacts-csv	5 min
Process nested JSON	⭐⭐⭐	04-nested-json-projects	10 min
Fix YAML errors	⭐⭐	10-special-chars-fix	5 min
Link entities	⭐⭐⭐	08-complex-relationships	15 min

Examples by Complexity

Simple (Start Here)

01-task-list-csv - Basic CSV with 5 fields
02-contacts-csv - Special character handling
03-books-json - Simple JSON structure

Intermediate

04-nested-json-projects - 2-level nesting
05-array-handling - Repeated elements
06-multi-source-merge - Data combination

Advanced

07-deep-nested-json - 3+ level hierarchy
08-complex-relationships - Entity linking
09-computed-fields - Derived values

Troubleshooting

10-special-chars-fix - YAML safety
11-empty-values - Conditional handling
12-type-mismatches - Type corrections

Integration & Extensions

Complementary Obsidian Plugins

Templater - Post-import transformations and computed fields
Dataview - Query and aggregate imported data
QuickAdd - Manual data entry workflows
Metadata Menu - Interactive frontmatter management
Tag Wrangler - Hierarchical tag organization

Extending This Skill

Add custom templates - Place in templates/ with metadata
Create domain patterns - Model specific industries or use cases
Build preprocessors - Transform data before import
Develop validators - Add custom validation rules
Share examples - Contribute to examples library

Graph Structure Optimization

Use [[Wikilinks]] for entities that should become nodes
Create MOCs (Maps of Content) for large imports
Apply hierarchical tags (e.g., project/alpha/task-001)
Standardize date formats (ISO 8601)
Preserve source URLs for traceability

Capabilities & Boundaries

✅ What This Skill Does

Parse CSV and JSON data structures
Analyze fields with type inference
Generate YAML-safe Handlebars templates
Validate syntax and preview output
Provide complete usage instructions
Suggest graph optimization strategies

❌ What This Skill Does NOT Do

Perform the actual import (requires user + plugin)
Modify source data files
Install or configure the plugin
Post-process notes after import
Fix corrupted YAML in existing notes
Real-time data synchronization

User Responsibilities

Install JSON/CSV Importer plugin in Obsidian
Save generated template to vault
Execute import through plugin interface
Review imported notes for accuracy
Perform any post-import cleanup

Execution Mode

When data is provided, the system automatically:

Detects format (CSV vs JSON)
Parses structure and analyzes fields
Generates field inventory with recommendations
Proposes template pattern based on data characteristics
Requests confirmation of field mappings
Constructs template with YAML safety
Validates syntax and generates preview
Delivers package with instructions

Response Format:

## 📊 Data Analysis

[Field inventory table with types and recommendations]

## 🎯 Recommended Approach

Pattern: [Selected template]
Note Names: [Field for filenames]
Target Folder: [Suggested location]

## ⚠️ Warnings

[Special character issues, data quality concerns]

## ✨ Template

[Complete Handlebars template with documentation]

## 👁️ Preview

[Sample output from first data row]

## 📋 Instructions

[Step-by-step import procedure]

## 🔧 Troubleshooting

[Common issues and solutions]

Metadata

Version: 2.0.0 (Modular Architecture) Created: October 2025 Compatibility: Obsidian + JSON/CSV Importer plugin Complexity Level: Intermediate to Advanced Skill Type: Data transformation & template generation

Prerequisites:

Obsidian (any recent version)
JSON/CSV Importer plugin by "filing 42"
Basic understanding of YAML frontmatter
Familiarity with Markdown

External Resources:

JSON/CSV Importer Plugin - Official repository
Handlebars.js Guide - Template syntax reference
YAML Specification - Format specification
Obsidian Forum - Community support

Version History

See CHANGELOG.md for detailed version history.

Support & Contribution

For Issues:

To Contribute:

Add examples to demonstrate new patterns
Submit custom templates for specific domains
Report edge cases or issues
Improve documentation clarity

Reception & Usage

Skill Activation: Simply provide your CSV or JSON data, and the system will immediately begin analysis and template generation.

No explicit invocation required - the skill recognizes data files and structured content automatically.

For best results: Include complete data samples (not fragments) so field analysis can be accurate.

Ready to import your data into Obsidian? Provide your file or paste your data to begin.