# config

> Configuration loader and manager for Obsidian vault settings. Use when the user wants to (1) load vault configuration, (2) customize note type definitions, (3) manage frontmatter defaults, (4) merge configuration files, (5) validate configuration structure, or (6) save custom vault settings. Triggers on keywords like load config, vault settings, note type config, frontmatter defaults, merge configs, validate configuration.

- Author: Peter Weiss
- Repository: wep4you/wep4you-agent-skills
- Version: 20260105020920
- Stars: 1
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/wep4you/wep4you-agent-skills
- Web: https://mule.run/skillshub/@@wep4you/wep4you-agent-skills~config:20260105020920

---

---
name: config
version: "1.0.1"
license: MIT
description: "Configuration loader and manager for Obsidian vault settings. Use when the user wants to (1) load vault configuration, (2) customize note type definitions, (3) manage frontmatter defaults, (4) merge configuration files, (5) validate configuration structure, or (6) save custom vault settings. Triggers on keywords like load config, vault settings, note type config, frontmatter defaults, merge configs, validate configuration."
---

# Config Loader

Loads, manages, and merges YAML configuration files for Obsidian vault management with support for vault-specific overrides.

## Slash Commands (v1.0.0)

| Command | Description |
|---------|-------------|
| `obsidian:config` | Show current vault configuration |
| `obsidian:config show` | Show detailed configuration (with `--verbose`) |
| `obsidian:config edit` | Edit settings in system editor |
| `obsidian:config validate` | Validate configuration structure |
| `obsidian:config methodologies` | List available methodologies |
| `obsidian:config create --methodology para` | Create default settings |
| `obsidian:config diff` | Show difference from defaults |

## Deprecated Commands

The following commands are deprecated and will be removed in v2.0.0:
- `/config-show` → `obsidian:config show`
- `/config-create` → `obsidian:config create`
- `/config-validate` → `obsidian:config validate`
- `/config-methodologies` → `obsidian:config methodologies`

## Architecture

This skill provides three complementary modules:

### settings_loader.py (PRIMARY - Source of Truth)
- Loads `.claude/settings.yaml` as the primary configuration source
- All validation rules come from here
- Generated by init-skill or custom wizard
- Use for: validation, note type checking, UP links

### config_loader.py (UTILITY - YAML Management)
- Loads and merges additional YAML config files
- Provides fallback defaults when settings.yaml doesn't exist
- Use for: config file merging, custom YAML management

### methodology loader (config/methodologies/loader.py)
- Loads methodology definitions from YAML files
- Provides `METHODOLOGIES` proxy for dict-like access
- Used by init_vault.py to create vaults
- Use for: methodology listing, vault initialization

## Quick Start

```bash
# Load user settings (PRIMARY - use this for validation)
uv run scripts/settings_loader.py --vault /path/to/vault --show --validate

# Load YAML config files (UTILITY)
uv run scripts/config_loader.py --vault /path/to/vault --show

# Create default settings if missing
uv run scripts/settings_loader.py --vault /path/to/vault --create --show
```

## Features

- **Unified Settings**: Single `.claude/settings.yaml` as source of truth
- **Methodology Support**: LYT-ACE, PARA, Zettelkasten, Minimal, Custom
- **Type-Safe Operations**: Full type hints with dataclasses
- **Note Type Inference**: Automatically infer types from folder paths
- **UP Link Resolution**: Get expected parent MOC for any file
- **Exclusion Handling**: Inbox and system files properly excluded
- **JSONL Logging**: Audit trail support for validation operations

## Configuration Hierarchy

The config loader merges configurations in this order (later overrides earlier):

1. **DEFAULT_CONFIG** (embedded in script)
2. **Skill defaults** (`skills/config/config/{name}.yaml`)
3. **Vault overrides** (`.claude/config/{name}.yaml` in vault)

## Usage Examples

### Load Settings (PRIMARY - Recommended)

```python
from pathlib import Path
from settings_loader import load_settings, get_note_type, get_validation_rules

# Load settings (creates default if create_if_missing=True)
settings = load_settings(Path("/path/to/vault"), create_if_missing=True)

# Get note type configuration
map_type = get_note_type(settings, "map")
print(map_type.description)       # "Map of Content - Overview and navigation notes"
print(map_type.required_properties)  # ["type", "up", "created", ...]

# Get validation rules
rules = get_validation_rules(settings)
print(rules.require_core_properties)  # True
print(rules.allow_empty_properties)   # ["tags", "collection", "related"]
```

### Infer Note Type and UP Link

```python
from pathlib import Path
from settings_loader import (
    load_settings,
    infer_note_type_from_path,
    get_up_link_for_path,
    should_exclude,
)

settings = load_settings(Path("/vault"))
file_path = Path("/vault/Atlas/Dots/Concept.md")

# Infer note type
note_type = infer_note_type_from_path(settings, file_path)
print(note_type)  # "dot"

# Get expected UP link
up_link = get_up_link_for_path(settings, file_path)
print(up_link)  # "[[Atlas/Maps/Dots]]"

# Check if excluded from validation
inbox_file = Path("/vault/+/new_idea.md")
print(should_exclude(settings, inbox_file))  # True
```

### Load YAML Configuration (UTILITY)

```python
from pathlib import Path
from config_loader import load_config

# Load default configuration
config = load_config(Path("/path/to/vault"))

# Load custom configuration
config = load_config(Path("/path/to/vault"), "custom.yaml")
```

### Save Custom Configuration

```python
from pathlib import Path
from config_loader import save_config

custom_config = {
    "core_properties": ["type", "up", "created", "daily", "tags", "collection", "related"],
    "note_types": {
        "custom": {
            "description": "Custom note type",
            "properties": ["type", "up", "created", "daily", "tags", "collection", "related"]
        }
    }
}

save_config(Path("/path/to/vault"), custom_config, "custom.yaml")
```

### Merge Configurations

```python
from config_loader import merge_configs

base = {
    "core_properties": ["type", "up"],
    "validation": {"strict": true}
}

override = {
    "core_properties": ["type", "up", "created"],
    "auto_fix": {"enabled": true}
}

merged = merge_configs(base, override)
# Result: All keys from both, override takes precedence for conflicts
```

### Get Note Type Configuration

```python
from config_loader import load_config, get_note_type_config

config = load_config(Path("/path/to/vault"))
map_config = get_note_type_config(config, "map")

print(map_config["description"])  # "Map of Content - Overview and navigation notes"
print(map_config["properties"])   # ["type", "up", "created", "daily", ...]
```

### Infer Note Type from Path

```python
from pathlib import Path
from config_loader import load_config, infer_note_type

config = load_config(Path("/vault"))
file_path = Path("/vault/Atlas/Maps/My Map.md")

note_type = infer_note_type(file_path, config)
print(note_type)  # "map"
```

### Validate Configuration

```python
from config_loader import load_config, validate_config

config = load_config(Path("/path/to/vault"))
errors = validate_config(config)

if errors:
    for error in errors:
        print(f"Error: {error}")
else:
    print("Configuration is valid")
```

## Configuration Files

### default.yaml

Core configuration with:
- `core_properties`: Required frontmatter properties for all notes
- `note_types`: Note type definitions with folder hints and properties
- `validation`: Validation rules
- `auto_fix`: Auto-fix toggles
- `exclude_paths`: Paths to exclude from processing
- `exclude_files`: Files to exclude from processing

### frontmatter-defaults.yaml

Default frontmatter templates for:
- New notes (minimal template)
- Each note type (map, dot, source, project, area, daily, effort)
- Date formats and link formats
- Default parent links by note type

### note-types-defaults.yaml

Extended note type configuration with:
- Detailed descriptions and aliases
- Icon assignments
- Required vs optional properties
- Type-specific validation rules
- Property type definitions with data types

## Note Types

The default configuration includes these note types:

| Type | Description | Folder Hints |
|------|-------------|--------------|
| **map** | Map of Content - Overview and navigation notes | `Atlas/Maps/`, `Maps/` |
| **dot** | Dot notes - Atomic concepts and ideas | `Atlas/Dots/`, `Dots/` |
| **source** | Source notes - External references | `Atlas/Sources/`, `Sources/` |
| **effort** | Effort notes - Work and tasks | `Efforts/` |
| **project** | Project notes - Defined outcomes | `Efforts/Projects/`, `Projects/` |
| **area** | Area notes - Ongoing responsibilities | `Efforts/Areas/`, `Areas/` |
| **daily** | Daily notes - Date-based journal entries | `Calendar/daily/`, `daily/` |

## Core Properties

All notes require these 7 properties (per vault standards):

```yaml
type: dot           # Note type
up: "[[Parent]]"    # Parent note link (quoted)
created: 2025-01-15 # Creation date (YYYY-MM-DD)
daily: "[[2025-01-15]]"  # Daily note link (quoted)
tags:               # Tags for categorization (can be empty)
collection:         # Collection classification (can be empty)
related:            # Related notes (can be empty)
```

## Vault-Specific Overrides

To customize configuration for a specific vault:

1. Create `.claude/config/` directory in vault root
2. Add YAML file (e.g., `custom.yaml`)
3. Define only the properties you want to override

Example `.claude/config/custom.yaml`:

```yaml
# Override just the note types
note_types:
  blog:
    description: "Blog post notes"
    folder_hints:
      - "Blog/"
    properties:
      - type
      - up
      - created
      - daily
      - published
      - tags

# Keep all other defaults from skill config
```

## API Reference

### load_config(vault_path, config_name)

Load configuration with hierarchical merging.

**Parameters:**
- `vault_path` (Path): Path to Obsidian vault root
- `config_name` (str): Config file name (default: "default.yaml")

**Returns:** dict[str, Any] - Merged configuration

**Raises:**
- ValueError: If vault path invalid
- yaml.YAMLError: If YAML parsing fails

### save_config(vault_path, config, config_name)

Save configuration to vault-specific location.

**Parameters:**
- `vault_path` (Path): Path to vault root
- `config` (dict): Configuration to save
- `config_name` (str): Config file name (default: "custom.yaml")

**Raises:**
- ValueError: If vault path invalid
- OSError: If file cannot be written

### merge_configs(base, override)

Deep merge two configuration dictionaries.

**Parameters:**
- `base` (dict): Base configuration
- `override` (dict): Override configuration

**Returns:** dict[str, Any] - Merged configuration

### get_note_type_config(config, note_type)

Get configuration for specific note type.

**Parameters:**
- `config` (dict): Configuration dictionary
- `note_type` (str): Note type identifier

**Returns:** dict[str, Any] | None - Note type config or None

### infer_note_type(file_path, config)

Infer note type from file path using folder hints.

**Parameters:**
- `file_path` (Path): Path to markdown file
- `config` (dict): Configuration dictionary

**Returns:** str | None - Inferred note type or None

### validate_config(config)

Validate configuration structure.

**Parameters:**
- `config` (dict): Configuration to validate

**Returns:** list[str] - Validation errors (empty if valid)

## Integration with Claude Code

When user requests configuration management:

1. Determine vault path (usually current directory or user-specified)
2. Load configuration with appropriate hierarchy
3. Perform requested operation (load, save, merge, validate)
4. Report results and configuration details

## Exit Codes

- `0`: Success
- `1`: Error (invalid vault, YAML error, validation failed)

## Dependencies

- Python 3.10+
- PyYAML >= 6.0 (via PEP 723 inline dependencies)

## Quality Standards

- Type hints on all functions (MyPy strict)
- Ruff-compliant (100 char line length)
- Full docstrings with examples
- Error handling with descriptive messages