obsidian-data-importer
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:
- Check examples/troubleshooting/ first
- Review knowledge/error-resolution.md
- Consult knowledge/best-practices.md
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.
More from zpankz/mcp-skillset
network-meta-analysis-appraisal
Systematically appraise network meta-analysis papers using integrated 200-point checklist (PRISMA-NMA, NICE DSU TSD 7, ISPOR-AMCP-NPC, CINeMA) with triple-validation methodology, automated PDF extraction, semantic evidence matching, and concordance analysis. Use when evaluating NMA quality for peer review, guideline development, HTA, or reimbursement decisions.
16software-architecture
Guide for quality focused software architecture. This skill should be used when users want to write code, design architecture, analyze code, in any case that relates to software development.
13cursor-skills
Cursor is an AI-powered code editor and development environment that combines intelligent coding assistance with enterprise-grade features and workflow automation. It extends beyond basic AI code comp...
13textbook-grounding
Orthogonally-integrated Hegelian syntopical analysis for SAQ/VIVA/concept grounding with systematic textbook citations. Implements thesis extraction → antithesis identification → abductive synthesis across multiple authoritative sources. Tensor-integrated with /m command: activates S×T×L synergies (textbook-grounding × pdf-search × qmd = 0.95). Triggers on requests for model SAQ responses, VIVA preparation, concept explanations requiring textbook evidence, or any PEX exam content needing systematic cross-reference validation.
12obsidian-process
This skill should be used when batch processing Obsidian markdown vaults. Handles wikilink extraction, tag normalization, frontmatter CRUD operations, and vault analysis. Use for vault-wide transformations, link auditing, tag standardization, metadata management, and migration workflows. Integrates with obsidian-markdown for syntax validation and obsidian-data-importer for structured imports.
12terminal-ui-design
Create distinctive, production-grade terminal user interfaces with high design quality. Use this skill when the user asks to build CLI tools, TUI applications, or terminal-based interfaces. Generates creative, polished code that avoids generic terminal aesthetics.
10