# Obsidian Starter Kit - Reference - OSK Plugin
🏠 [[Obsidian Starter Kit - User Guide|User Guide]] / [[Obsidian Starter Kit - Reference|Reference]] / **OSK Plugin**
Full reference for the [[Obsidian Starter Kit plugin for Obsidian]] — the core plugin that powers OSK v4 and above. The plugin adds strong typing, automated metadata, a `.types/` export, a CLI validator, and an MCP server. This page is the canonical documentation inside the OSK user guide.
For a guided setup, see [[Obsidian Starter Kit - Tutorial - Configuring the Obsidian Starter Kit plugin]].
## Overview
The plugin solves three problems:
1. **Consistent metadata across thousands of notes** — every note of a given type has the same properties, tags, and location.
2. **Automation** — new notes are recognized and processed automatically; missing properties, tags, and folder moves can all happen without your intervention.
3. **AI-friendliness** — the plugin exports every note type as an md-base definition into `.types/`, and exposes an MCP server on `127.0.0.1:27125` so AI agents can read your schema and run commands.
All features are toggleable. You can use it as a strict enforcement engine or a gentle suggestion layer.
## Installation
Ships bundled with OSK v4 and is enabled by default. Verify in **Settings → Community plugins**.
The plugin also bundles the `osk-cli` binary used by the CLI validator and AI-friendly tooling. Native binaries are included for Linux (x64 and ARM64) and Windows (x64).
## Concepts
### Note type
A named category (e.g. "Meeting Note") with:
- **Icon** — Lucide icon shown in the file explorer and tabs
- **Properties** — frontmatter fields specific to this type
- **Tags** — mandatory tags applied to notes of this type
- **Mappings** — how the plugin recognizes a note as this type
- **Associated folder** — where new notes of this type live
- **Template** — Templater template applied on creation
- **Prefix / Suffix** — dynamic strings prepended/appended to new note names (`{{date}}`, `{{year}}`, etc.)
### Recognition
A note becomes typed via one of four mappings (priority order):
1. **Tag mapping** — the note carries a specific tag (most reliable, recommended)
2. **Folder mapping** — the note lives in a configured folder (supports wildcards)
3. **Regex mapping** — the note path matches a regex (e.g. `^journal/\d{4}/\d{2}/\d{2}
)
4. **Formula mapping (experimental)** — a formula expression (similar to Obsidian Bases formulas). Stored in settings and preserved in md-base exports under `x_osk`, but **not yet evaluated at runtime**. Safe to configure now if you want the logic carried forward, but don't rely on it for recognition yet.
If multiple types match, **tag mappings beat any non-tag match**. Among non-tag matches (folder, regex, formula), the first note type whose mapping fires wins, in declaration order. This is why tag mappings are recommended whenever you can use them.
### Global vs per-type
- **Global properties** and **global tags** apply to every note regardless of type. The plugin itself ships no global properties; the OSK starter vault preconfigures six (`created`, `updated`, `review_count`, `review_interval`, `last_reviewed`, `notes`) and no global tags.
- **Per-type properties** and **per-type tags** apply only to notes recognized as that specific type.
- **Folder-scoped global tags** apply to all notes under a configured folder (e.g. tag `#work` for everything under `work/`).
## Settings reference
**Settings → Obsidian Starter Kit**.
### Automation (all default OFF)
| Setting | Effect |
|---|---|
| Auto-move files | Move recognized notes to their type's associated folder |
| Auto-add required properties | Add missing required frontmatter properties |
| Auto-add mandatory tags | Add mandatory tags to recognized notes |
Recommended: turn Auto-add tags and Auto-add properties ON once you trust your types. Leave Auto-move OFF until you've used it for a week.
### Display
| Setting | Default | Effect |
|---|---|---|
| Enable icons in file explorer | ON | Type icons next to file names |
| Display icons in tabs | ON | Type icons in tab headers |
| Display icons in tab title bar | OFF | Type icon in the window title |
### Types folder
The folder where the plugin exports each note type as an md-base definition. Defaults to `_types`; the OSK starter vault uses `.types`. Accepts a simple name or a nested path; rejects `..` segments, leading/trailing slashes, and backslashes.
Changing the value writes new type files into the new folder on the next save. The old folder is left in place for you to move or delete. The plugin also watches `mdbase.yaml` for external changes (e.g. from `osk-cli set-types-folder`) and keeps the setting in sync automatically.
### MCP server
| Setting | Default | Notes |
|---|---|---|
| Enabled | ON | Run the MCP server inside Obsidian |
| Auto-start | ON | Start the server automatically when Obsidian loads |
| Port | 27125 | Any port in 1024–65535; restart required to change |
| Bind address | `127.0.0.1` | Localhost only by default. Switch to `0.0.0.0` to expose on all interfaces (an API key is auto-generated if none is set) |
| API key | empty | Bearer token for authentication. Generate / Regenerate buttons in the settings UI |
### Resetting the plugin
If your configuration gets into a bad state, close Obsidian, delete the plugin's `data.json` file, then reopen Obsidian. All settings return to defaults; your notes and vault content are untouched.
## Properties
### Property types
| Type | Stored as |
|---|---|
| text | Single line string |
| list | Array of strings |
| number | Numeric value |
| checkbox | Boolean |
| date | `YYYY-MM-DD` |
| datetime | `YYYY-MM-DDTHH:mm` |
| tags | Tag array |
### Configuration per property
- **Name** — lowercase, alphanumeric, hyphens/underscores allowed, no spaces, unique within scope
- **Default value** — static (e.g. `"draft"`) or dynamic expression (`{{date}}`, `{{year}}`, `{{quarter}}`, `{{month}}`, `{{week}}`)
- **Required** — auto-add creates the property if missing; UI shows required indicator
- **Allowed values** — restrict to a list (e.g. `["low", "medium", "high"]`)
- **Number constraints** — min / max for numeric properties
### Uniqueness rules
- Names must be unique within a scope (global, or within a single note type)
- A global and a per-type property cannot share the same name
### Auto-add behavior
When **Auto-add properties** is ON:
1. Note created / modified
2. Type recognized
3. Missing required properties are added with defaults
4. Changes are debounced (longer delay on creation than on modification) so the plugin lets Templater, Linter, and other automations finish their work first
## Tags
### Tag scopes
- **Global tags** — added to every note
- **Folder-scoped global tags** — added to notes under a configured folder path (supports `{{year}}`, `{{month}}` expressions in paths)
- **Per-type mandatory tags** — added beyond the recognition tag to notes of that type
### Format
- Configure tags with the `#` prefix (e.g. `#meeting`)
- Stored in `tags:` frontmatter without the `#` (e.g. `- meeting`)
- Deduplication is automatic and case-insensitive
### Hierarchical tags
OSK convention: use hierarchical tags like `type/meeting`, `zone/areas`, `project/alpha`. The plugin preserves and matches them the same way as flat tags.
## Dynamic naming
Note name prefixes and suffixes — and dynamic property defaults — support these expressions:
| Expression | Result |
|---|---|
| `{{year}}` | 2026 |
| `{{quarter}}` | 2 |
| `{{month}}` | 04 |
| `{{week}}` | 17 |
| `{{date}}` | 2026-04-22 |
Example: Prefix `{{date}} - ` produces `2026-04-22 - Meeting Title`.
## Commands
Run from the command palette (Ctrl/Cmd+P). Type "Starter Kit:" to filter.
### Working with the current note
| Command | What it does |
|---|---|
| Create new note | Create a new note of a chosen type; applies the type's template |
| Add all missing properties and tags to current note | Add every property and tag defined by the note's type |
| Add missing required properties and tags to current note | Add only the required ones |
| Move note to associated folder | Move the current note to the folder configured for its type |
### Bulk operations across the vault
| Command | What it does |
|---|---|
| Add all missing properties and tags to all notes (bulk) | Run the full add across every recognized note |
| Add missing required properties and tags to all notes (bulk) | Required-only across every recognized note |
| Move all recognized notes to their folders (bulk) | Reorganize the whole vault in one pass |
### Type and global-property management
| Command | What it does |
|---|---|
| List note types | Show the note types currently defined |
| Create note type | Add a new note type from the command palette |
| Delete note type | Remove an existing note type |
| Add global property | Define a property that applies to every note |
| Remove global property | Remove a global property |
| Set global tags | Configure tags applied to every note |
### Quick toggles
| Command | What it does |
|---|---|
| Toggle auto-move | Flip the auto-move automation on/off |
| Toggle auto-add properties | Flip the auto-add-properties automation |
| Toggle auto-add tags | Flip the auto-add-tags automation |
### Export
| Command | What it does |
|---|---|
| Export settings to clipboard | Copy the full plugin settings as JSON, useful for backup or sharing |
## md-base Type Export (`.types/`)
Every time you save plugin settings, the plugin:
1. Converts each note type to an [md-base](https://mdbase.dev/spec.html) definition (Markdown + YAML frontmatter)
2. Writes one file per type into `.types/` (default, configurable via plugin settings)
3. Updates `mdbase.yaml` at the vault root
Export is **incremental**: only changed types are rewritten. Orphaned files (from deleted types) are removed.
These md-base files are what the CLI validator reads, what `osk-cli` commands query, and what AI agents use as the source of truth for your schema.
## CLI validator (`osk-cli`)
The plugin ships an `osk-cli` binary you can call directly from your terminal, scripts, and CI. It validates notes against your type definitions, queries your schema, and exposes utility commands that AI agents and skills rely on.
| Platform | Status |
|---|---|
| Linux x64 | Native binary included |
| Linux ARM64 | Native binary included |
| Windows x64 | Native `.exe` included |
| macOS | Not currently supported |
On Linux, make sure the binary keeps its executable bit (`chmod +x`).
### Config resolution
The CLI reads `mdbase.yaml` at the vault root to find the types folder. Override precedence:
1. `--types-dir` flag (explicit)
2. `mdbase.yaml` → `settings.types_folder` (via `--vault`)
3. Default: `_types/` (OSK uses `.types/`, set via plugin settings)
### Note type commands
**`list-types`** — list all available type definitions:
```bash
osk-cli list-types --types-dir .types --format text
```
**`show-type`** — show a type's full definition:
```bash
osk-cli show-type meeting-notes --types-dir .types
```
**`validate`** — validate a single note:
```bash
osk-cli validate note.md --types-dir .types
```
Auto-detects the type from the note's tags; or pass `--type <name>` or `--type-file <path>` explicitly.
**`validate-folder`** — validate every note in a folder:
```bash
osk-cli validate-folder . --types-dir .types --parallel
```
Flags: `--parallel` (speed up), `--fail-fast` (stop on first error), `--summary-only`, `--format json|text`, `--quiet`.
**`create`** — create a new note from a type definition, pre-populated with defaults:
```bash
osk-cli create --type meeting-note --output ./meetings/new.md --types-dir .types
```
Writes YAML frontmatter with all defined fields and default values where specified. Skips auto-generated fields (`generated: now`, `generated: uuid`).
**`refresh-types`** — regenerate md-base type files + `mdbase.yaml` from the plugin's `data.json`, without opening Obsidian:
```bash
osk-cli refresh-types --vault . --plugin-id obsidian-starter-kit
```
Writes one type file per note type. Unchanged files are skipped; orphaned files are removed. Useful in CI / pre-commit hooks or on machines without Obsidian running.
**`set-types-folder`** — change the types folder in `mdbase.yaml` and rename the existing folder on disk:
```bash
osk-cli set-types-folder .types --vault .
```
Validates the new value (no `..`, no leading/trailing slashes, no backslashes; nested paths OK). Renames the current folder on disk if it exists; refuses if the target already exists. Updates `mdbase.yaml` preserving other keys. Obsidian picks up the change automatically via its file watcher.
### Type-definition query commands
Targeted single-call queries that avoid `show-type | jq` piping. Use these in scripts and skill bodies.
**`path <type> [--field <field>]`** — resolve a single path-shaped attribute of a type:
```bash
osk-cli path daily-notes # associated folder (default)
osk-cli path daily-notes --field template # Templater template path
osk-cli path daily-notes --field prefix # note name prefix
osk-cli path daily-notes --field suffix # note name suffix
osk-cli path daily-notes --field mandatory-tags # mandatory tags, one per line
```
Single-call replacement for `show-type | jq -r '.x_osk.<field>'`.
**`required-fields <type>`** — list field names where `required: true` (sorted alphabetically):
```bash
osk-cli required-fields tasks # one per line
osk-cli required-fields tasks --format json # JSON array
```
**`filename <type> --title "<title>"`** — build the canonical filename (prefix + title + suffix + ".md"):
```bash
osk-cli filename meeting-notes --title "2026-05-13 - Standup"
# → 2026-05-13 - Standup (Meeting).md
osk-cli filename daily-notes --title "2026-05-13"
# → 2026-05-13.md
```
**`show-property <type> <field> [--aspect <aspect>]`** — targeted query for a single field's metadata. Without `--aspect`, emits the full FieldDefinition as JSON (augmented with `displayName` resolved from `x_osk.property_display_names`). With `--aspect`, emits one value to stdout (empty + exit 0 if the aspect is unset):
```bash
osk-cli show-property tasks status --aspect allowedValues
# → 10 - Backlog
# 20 - This Year
# ...
osk-cli show-property tasks status --aspect required # → true
osk-cli show-property tasks status --aspect default # → 10 - Backlog
osk-cli show-property tasks status --aspect description # → Current task status
osk-cli show-property tasks status --aspect type # → enum
osk-cli show-property tasks status --aspect displayName # → (empty if not configured)
```
Available aspects: `type`, `required`, `description`, `default`, `allowedValues`, `pattern`, `deprecated`, `displayName`, `numberRange`, `lengthRange`.
`allowedValues` is populated from each type's YAML `values:` list, which `refresh-types` now writes from the plugin's `data.json` `allowedValues` (`select`-typed properties become `enum` fields in the YAML). Re-run `refresh-types` after any plugin-settings change to a property's allowed values.
**`scaffold <type> --title "<title>" [--dry-run] [--force]`** — create a new typed note at the type's canonical folder, with the canonical filename (prefix + title + suffix + ".md"), and frontmatter pre-populated:
```bash
osk-cli scaffold meeting-notes --title "2026-05-13 - Standup"
# → <vault>/<meeting-notes-folder>/2026-05-13 - Standup (Meeting).md
```
Prefix and suffix tokens (`{{year}}`, `{{quarter}}`, `{{month}}`, `{{week}}`, `{{date}}`) are substituted at scaffold time using local time. Frontmatter is generated from each non-generated field's default (when set) or a type-appropriate placeholder for required fields; mandatory tags are appended unless the type already declares a `tags` field.
`--dry-run` prints the would-be path as JSON without writing. `--force` overwrites an existing file; without it, the command refuses to clobber. For types without an `associated_folder` (rare) or when you need an ad-hoc literal path, use `create --output <path>` instead.
### Periodic-note + wiki + skill-registry commands
The CLI also exposes `daily-note-path`, `periodic-note-path`, `wikis list|path`, `capabilities resolve`, and `vault info`. See `osk-cli <command> --help` for each one's options. These are documented in depth in the OSK Assistant System reference and the `osk-vault-note-types` Claude Code skill body. Claude Code skill management commands are covered separately below.
### Vault-state query commands
Targeted queries against vault state that lives outside the type schema: filenames at user-specific paths, and user-managed config overrides. Skills query these instead of baking paths or values into their bodies.
**`search-note <query>`** — vault-wide filename search for canonically-named notes (Top of mind, Waiting for, MoCs, etc.) that live at user-specific paths. Returns vault-relative paths, one per line. Exits 1 if no match.
```
osk-cli search-note "Top of mind" # find the canonical note by filename
osk-cli search-note "Waiting for"
```
Use this when a skill needs a note that the user customarily owns at a non-canonical location.
**`config get <key>`** — read a single key from `<vault>/.osk-config.yaml` (user-managed open-schema config). Skills query this file for vault-specific values (attachments-folder override, custom subfolder names, per-vault toggles) instead of hardcoding the path.
```
osk-cli config get attachments_folder # → 50 Resources/51 Attachments
osk-cli config get publish_root # empty + exit 0 if unset
```
The file is YAML, flat key/value, and ships empty by default. Users add keys as their skills need them.
### Claude Code skill commands
The same CLI binary also ships commands for managing Claude Code skills under `<vault>/.claude/skills/`. Skills directory resolution: `--skills-dir` overrides the default `<vault>/.claude/skills`.
- **`skill-list`** — list installed skills with metadata (name, namespace, category, size). Filter via `--namespace`, `--category`; sort via `--sort name|size|namespace`.
- **`skill-search <query>`** — search skills by name or description. `--field name|description|all`, `--limit N`.
- **`skill-analytics`** — report skill usage over a time window by scanning Claude Code session logs. `--days N` (default 30), `--all` (include zero-usage), `--sessions-dir <path>`.
- **`skill-health`** — health check: broken dependencies, naming-convention mismatches, size outliers, duplicate triggers, orphans, stale categories, deep dependency chains, plus portability checks (`banned-tool`, `non-portable-shell`, `personal-machine-path`). `--fix-suggestions` for remediation hints, `--namespace` to restrict, `--categories-file` for custom category validation.
- **`skill-deps validate <skill-name>`** — verify every `$VAR` reference in the target skill's body resolves to a `VAR=` definition somewhere in its transitive dependency closure. Catches the regression where auto-injected Setup blocks get stripped without checking what each skill actually references. Exits 1 if any reference is unresolved.
- **`skills graph [--skill <name>] [--format dot|json]`** — emit the skill dependency / `composes` / `absorbs` graph. With `--skill`, scopes the graph to one skill's transitive closure (useful for impact analysis when changing a context loader). Without `--skill`, emits the full fleet graph. `--format dot` for Graphviz, `--format json` for tooling.
### Validation features
- **Type coercion** — YAML string values are coerced to the expected type before validation (`"42"` → `42` for numbers, `"true"` → `true` for booleans, `"3.14"` → float).
- **Multi-type matching** — a note can match multiple types. The CLI reports all (`matchedTypes`), merges constraints (union of fields, intersection of enum values, most-restrictive numeric bounds), and validates against the merged definition.
- **Error hints** — every error carries an actionable `hint` (e.g. `"Add a 'meeting_date' field to the frontmatter"`, `"Use one of the allowed values: a, b, c"`).
- **Generated fields** — fields marked `generated: now` / `generated: uuid` are treated as auto-populated: missing or null values don't produce errors; present values are still validated normally. The `create` command skips them.
- **List constraints** — list fields support `min_items` and `max_items` with error hints on violation.
### Output formats
- **JSON (default)** — structured output for AI/LLM systems, automation, CI
- **Text** — human-readable terminal output with indented errors, expected values, and hints
### Return codes
- `0` — all valid (or no-op)
- Non-zero — validation failures, I/O errors, or invalid arguments
Useful for CI / pre-commit hooks that run `osk-cli validate-folder` over the vault.
## MCP server
The plugin runs an MCP server inside Obsidian for AI agents. Default: `http://127.0.0.1:27125/mcp`, StreamableHTTP transport.
### Design
Rather than exposing 30+ tools (one per command), the MCP server exposes exactly **2 tools** and uses the **Code Mode pattern**:
- **`search`** — discover commands by name, description, or category
- **`execute`** — run any discovered command
This keeps the tool count fixed regardless of how many commands the plugin grows to support, minimizing token cost for AI clients.
### Authentication
- With `bindAddress: 127.0.0.1` (default): API key optional but recommended
- With `bindAddress: 0.0.0.0`: API key **required** (auto-generated on switch if not already set)
- Header format: `Authorization: Bearer <key>`
### Client configuration
**Claude Desktop / Claude Code:**
```json
{
"mcpServers": {
"obsidian-starter-kit": {
"url": "http://127.0.0.1:27125/mcp",
"headers": { "Authorization": "Bearer YOUR_API_KEY" }
}
}
}
```
Omit `headers` if no API key is set.
**Other MCP clients:** any client that supports StreamableHTTP. URL = `http://127.0.0.1:27125/mcp`, auth via Bearer token.
## Behavior when you modify a note type
Summarized from [[Obsidian Starter Kit - Tutorial - Configuring the Obsidian Starter Kit plugin]]:
- **Add / rename / remove properties** — non-destructive. Existing notes keep their frontmatter; only new notes follow the new schema. Use `osk-cli validate-folder` to find drift.
- **Change associated folder** — existing notes stay put; only new notes go to the new folder (unless Auto-move is ON).
- **Change tag/folder/regex mapping** — recognition flips immediately. Notes that no longer match lose their type association but keep their frontmatter.
- **Change template** — affects new notes only.
- **Delete a type** — removes it from the registry and removes the `.types/<name>.md` file. Notes that used the type are NOT deleted.
### Rollback
`data.json` and `.types/` are plain files. Restore from git or a backup to roll back a mistaken change.
## Tips & best practices
### Start simple
- Begin with 2–3 core types, not 48. Add more as you feel friction.
- Use unique, hierarchical recognition tags (`type/meeting`, `type/person`) to avoid conflicts.
- Lean on Auto-add tags and Auto-add properties once you trust your setup; leave Auto-move OFF until you're sure.
### Naming
- Property names: `meeting-date`, not `meetingDate`. Stay consistent across types.
- Related properties use a common prefix: `contact-email`, `contact-phone`.
- Avoid Obsidian-reserved names (`aliases`, `cssclasses`, `publish`, `tags`).
### Recognition
- Prefer **tag mappings** over folder or regex. Tags survive file moves; folders don't.
- Keep the recognition tag separate from descriptive tags: use `#type/meeting` for recognition, `#important` for description.
- Don't use generic tags (`#note`) as mappings — they collide with everything.
### Properties
- Mark only **truly essential** properties as required.
- Use dynamic expressions (`{{date}}`) for time-sensitive defaults.
- Don't duplicate the same field under different names across types (`attendees` everywhere, not `participants` in one type and `people` in another).
### Global tags
- Use sparingly — too many global tags clutter every note.
- Prefer folder-scoped tags for zone or domain separation (`zone/areas` scoped to `30 Areas/`).
## Integration with other v4 plugins
- **[[Journal Bases plugin for Obsidian]]**: uses the recognition tags for periodic notes (`type/periodic_note/daily`, etc.)
- **[[Life Tracker plugin for Obsidian]]**: reads the property definitions to build visualization cards
- **[[Obsidian CLI REST MCP plugin for Obsidian]]**: can run `osk-cli` commands remotely
## Troubleshooting
- **"Plugin fails to load"** — Obsidian must be 1.4.0 or later. Check `main.js` and `manifest.json` exist in the plugin folder.
- **"Note-type icons don't show"** — ensure `.types/` folder exists and is populated; restart Obsidian.
- **"osk-cli not executable"** — `chmod +x` the binary on Linux/macOS.
- **"Auto-add keeps fighting with Linter / Metadata Menu"** — the built-in debounce usually prevents this (the plugin waits longer on note creation than on modification so other plugins can finish first). If conflicts persist, disable one automation or change plugin load order in Obsidian's settings.
- **"Renamed a tag and lost recognition across hundreds of notes"** — mass-retag first (Tag Wrangler plugin), then update the mapping. See the tutorial for the safe procedure.
- **"MCP client can't connect"** — check `bindAddress` and port; if on `0.0.0.0`, API key is required.
## Related
- [[Obsidian Starter Kit plugin for Obsidian]] — short overview in the plugin catalog
- [[Obsidian Starter Kit - Tutorial - Configuring the Obsidian Starter Kit plugin]] — guided setup walkthrough
- [[Obsidian Starter Kit - Reference - Note Types]]
- [[Obsidian Starter Kit - Reference - Note Properties]]
- [[Obsidian Starter Kit - Reference - Special Tags]]
- [[Obsidian Starter Kit - Reference - Included plugins]]
- [[Obsidian Bases]]