Use when Obsidian vault notes have poor, generic, or uninformative filenames and need clear, descriptive names. Trigger phrases - "rename notes", "fix note names", "clean up filenames", "give notes better names". Also trigger for single notes - "rename this note", "give this a better name". Trigger when the user mentions "Untitled notes", "unnamed notes", or notes that are hard to find by name.
How this skill is triggered — by the user, by Claude, or both
Slash command
/obsidian-vault-autopilot:note-renameThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Give poorly named vault notes clear, descriptive filenames. Rename and fix backlinks. No sorting, no restructuring.
Give poorly named vault notes clear, descriptive filenames. Rename and fix backlinks. No sorting, no restructuring.
references/trash-concept.md). Minimal YAML syntax repairs when already editing frontmatter. Syntactic fixes only — never add or change field values (that is property-enrich's job). Allowed repairs:
* → - in tag lists--- separators[X] to block format--- (e.g. dictation artifacts like Thx --- → ---)"type:" → type (the colon belongs to YAML syntax, not the key name)created from the Source Hierarchy (filename date > Git first-commit > filesystem birthtime) before evaluating cooldown. See docs/metadata-requirements.md. This prevents birthtime corruption on subsequent skill runs.--- repairs above are governed by Step 4a's sanity-check routing — apply them via references/yaml-edits.md recipe (f), which resolves duplicate-key collisions (identical → silent dedup; divergent → ABORT: skip + Class-A finding, no rename). Never hand-apply a key fix in a way that bypasses the recipe (f) Step 3 collision check.| Parameter | Default | Description |
|---|---|---|
cooldown_days | 3 | Skip notes created within the last N days. Grace period so the user can review recent captures before automation touches them. Date source: YAML created field in frontmatter. If missing, the skill auto-enriches created from the Source Hierarchy (filename date > Git first-commit > filesystem birthtime) before evaluating cooldown — see Nahbereich. Never use modification date. |
clone_cluster_skip | true | When true (default), Step 4b SKIPs created enrichment for files whose only available date source is filesystem birthtime AND whose birthtime falls in a detected clone-cluster window. See references/clone-cluster-detection.md. The rename flow still runs (filename change applied), but the YAML created field is left absent (recoverable, not poisoned). Set to false to disable. |
scope | inbox | Which folder to scan. inbox = inbox root only (default). inbox-tree = inbox folder including all subfolders (opt-in for bulk-mode, e.g. initial vault setup). vault = entire vault excluding root. folder:<path> = specific subfolder. User confirms before execution. |
_ are excluded from scanning (_trash/, _secret/, _test-backup/).. are excluded (.trash/, .obsidian/).00_Templates) are excluded.Never rename or process these files (see references/vault-autopilot-note.md):
_vault-autopilot.md in vault root_ in vault root (reserved for plugin management)Rename notes with uninformative filenames: Untitled, Unbenannt, New Note, Draft, Blank note, Note from iPhone, Quick Note, URL-only names, hash-only names, obvious typos (95%+ clear intent).
Never rename: Already descriptive names.
Daily Notes (YYYY-MM-DD.md): Not automatically kept. Classify by content:
YYYY-MM-DD - Context - DetailWeb captures: Apply prefix per references/web-capture-detection.md. Skip existing categorical prefixes.
Unclear cases: [Original Name] - TBD. When the original name contains a date, keep the date first: YYYY-MM-DD - TBD. The date must always lead for chronological sorting.
Soft-delete to _trash/ if ALL true: (1) generic filename, (2) no content beyond template boilerplate, (3) frontmatter has only generic tags and no real title. Add trash metadata per references/trash-concept.md. When in doubt → TBD prefix instead.
Notes matching the Daily Note pattern (YYYY-MM-DD.md) get special handling. They are NOT auto-kept — classify by content (see Rename Candidates above). Location handling:
Detection rules:
YYYY-MM-DD.md outside the vault's canonical Daily Notes folder → move there first, then classify for rename like any other note. Add skill-log with Daily action for the move.YYYY-MM-DD Some Description.md) — this is NOT a daily note. It is a regular note with a date prefix. Process as a rename candidate — the date prefix is informative context, not a daily note pattern.created date in frontmatter, use it as the correct date and rename accordingly. If a note with the corrected date already exists, resolve via naming (e.g. add a suffix). If no created date is available, flag for manual review. Always log the date correction in the skill-log action: Renamed from [original] (date corrected).inbox/Daily Notes/YYYY-MM-DD.md) — these are misplaced. The vault has ONE canonical Daily Notes folder. Move there, avoid duplicates.Detect files with multiple YAML frontmatter blocks (two or more ---/--- pairs). This happens when two notes get accidentally merged — typically an append error during sync or import. These files cannot be reliably processed.
Action: Rename with a descriptive corruption label (e.g. YYYY-MM-DD - Korrupte Datei - Zwei Notizen verschmolzen). Write skill-log. Do not attempt to split the file — that requires manual review by the user.
Detection: Count --- pairs that enclose YAML-key-like content (at least one key: value line between the pair). Body-level --- horizontal-rule separators without YAML content do NOT count. Precise heuristic: see references/yaml-sanity.md Pattern 2. Two genuine frontmatter blocks = corrupted.
Move to _secret/ if the note contains sensitive data: recovery phrases, API keys, passwords, tokens, or other credentials stored as plaintext. These notes are a security risk and must not remain in the vault unprotected. Add trash metadata with trash_source: note-rename and the original path. The _secret/ folder signals to the user that these files need manual review and secure handling — not just deletion.
Topic - Detail for two-level namesClusters: If 3+ notes share a topic, suggest a common prefix before renaming.
When renaming notes that have a date prefix, use a three-part name: YYYY-MM-DD - Context - Detail.
The Context segment answers: "What gives the reader the fastest orientation?" It can be:
Platform detection (when primary content is a link or capture):
| URL Pattern | Context Segment |
|---|---|
instagram.com | |
youtube.com, youtu.be | YouTube |
perplexity.ai | Perplexity |
chatgpt.com | ChatGPT |
grok.com | Grok |
linkedin.com | |
github.com | GitHub |
reddit.com | |
| Other recognizable domain | Domain name (capitalized) |
See also references/web-capture-detection.md for social platform detection rules.
Multiple links, same platform: One context segment. E.g. 3 Instagram links → still just "Instagram".
Multiple links, different platforms: Use the dominant platform as context, or Research if no platform dominates.
No links (pure text): Use project, life area, or activity as context.
When a note covers multiple unrelated topics, join them with & in the Detail segment:
| # | Topic Count | Platforms | Rule |
|---|---|---|---|
| 1 | 1-2 | any | All topics in the name with & |
| 2 | 3-4 | any | All topics in the name with & if it stays readable and under ~70 characters. Skill decides. |
| 3 | 5-6 | one dominant | All topics as keywords with &. One keyword per topic — enough to find the note later. |
| 4 | 5+ | multiple | YYYY-MM-DD - Mixed Content - Mixed Topics.md. Too chaotic for a meaningful name. |
| 5 | 7+ | any | YYYY-MM-DD - Mixed Content - Mixed Topics.md. Topic Override — content this fragmented cannot produce a meaningful name regardless of platform dominance. |
Examples:
2025-12-03 - Instagram - HR Interview Tipps & SaaS.md2025-12-04 - Instagram - SaaS & Dev Tools & Karpathy LLM.md2025-12-11 - Instagram - Product & Interview & Claude & AI Cases & Cursor.md2025-12-08 - Mixed Content - Mixed Topics.md2026-01-08 - Mixed Content - Mixed Topics.md (Topic Override — 7 topics, 93% Instagram, still too fragmented)Before every invocation of this skill — including resumed sessions and re-triggers within the same conversation:
references/clone-preflight.md. It detects clone-induced birthtime clusters and emits a WARN before any date-derivation runs. Cross-platform — applies on macOS, Linux, and Windows. WARN-flow only; skill execution continues.references/windows-preflight.md end-to-end (registry check, trailing-dot folder detection, Windows-aware file-enumeration pattern). The enumeration pattern in Step 6 of that preflight applies to every subsequent file-listing call this skill makes — Scan (step 2 below) and Check backlinks (step 6 below) included. On macOS or Linux, this preflight is a no-op.Run the checks freshly each time. Do not assume a previous turn's pass result still holds — registry state, folder topology, and birthtime clustering can change between invocations and previous results are not authoritative.
Discover vault — resolve ${OBSIDIAN_VAULT_PATH}. Default scope: inbox root. Confirm with user.
Scan — list .md files.
Nahbereich — detect and trash accidental notes (soft-delete to _trash/). Move misplaced Daily Notes to the Daily Notes folder. Log each.
Classify — read title, tags, first ~30 lines (skip template boilerplate). For each note:
4a. Repair corrupted quoted-key variants first (Nahbereich, sanity-check). Call references/yaml-sanity.md. Verdict-routing per references/yaml-sanity.md § "Per-skill policy":
BROKEN_KEYS_INSIDE_COLON (shape β — F26 inside-colon): normalize via references/yaml-edits.md recipe (f) — handles ALL quoted-key patterns, not just "created:"/"modified:" (broadened from v0.1.0/v0.1.2 hardcoded list). After normalization, resolve duplicate-key collisions per recipe (f) Step 3 (identical → silent dedup; divergent → ABORT, see next bullet). Re-call sanity-check (idempotent fixpoint) — verdict must now be OK, OK_QUOTED, or OK_NO_FRONTMATTER.DUPLICATE_KEYS_IDENTICAL_VALUES (v0.1.4 W4): repair via recipe (f) silent dedup, then re-run sanity-check.DUPLICATE_KEYS_DIVERGENT_VALUES (v0.1.4 W4 — F7 family): skip the file + log Class-A finding "duplicate-key-divergent-values". Do NOT rename — user may legitimately need to merge values first; rename would obscure the underlying ambiguity. Route to user.MULTIPLE_FRONTMATTER_BLOCKS: use existing Corrupted File Detection (rename file with corruption-label).OK_QUOTED: proceed normally.OK / OK_NO_FRONTMATTER: proceed normally.YAML edits MUST follow references/yaml-edits.md (recipes b + f). Without this normalization a strict YAML parser cannot read the author-intended date, falls back to the Source Hierarchy → filesystem birthtime (often fresh on cloned vaults), and the cooldown evaluation in 4c silently skips legitimate candidates. Classification regex accepts both plain and standard-quoted forms. Historical bugs: repo issue #4 (2026-04-27) for created/modified; F26 cross-skill cluster (2026-04-28) generalized the inside-colon pattern; F7 (GR-3 Cell 1, 2026-05-01) generalized duplicate-key resolution beyond first-wins-silent (v0.1.4 W4).
4b. After 4a, if YAML created is still missing: derive the value via Source Hierarchy Prio 1-3 first (filename > git, with German-date normalization in Prio 1 per references/german-date-normalization.md). If Prio 1-3 yields a value, write it to frontmatter (Nahbereich) and record the source. If Prio 1-3 yields no value, apply the clone-cluster gate per references/clone-cluster-detection.md: detect the vault-wide cluster window once per skill invocation, then invoke recipe (a) is_birthtime_in_clone_cluster_window. If recipe (a) returns 0 (in cluster) AND recipe (b) has_alternate_date_source returns 1 (no alt source), SKIP created enrichment for this note — do not write the field, log the file as Class-C "clone-cluster birthtime, no alt source" in the per-skill findings file, and store the current filesystem birthtime only for later restoration (rename-flow proceeds, but created stays absent). Otherwise (no cluster declared, or recipe (a) returns 1 = not in cluster), fall through to Prio 4 (filesystem birthtime) — write created from stat -f %SB / stat -c %W. Behavior gated by config clone_cluster_skip (default true); when false, the gate is a no-op and Prio 4 fires unconditionally.
4c. Apply cooldown (per cooldown_days parameter) using the now-trustworthy created value. Cooldown-skipped notes are reported in the Skipped section of the report (not silently dropped) — see references/report-format-note-rename.md.
4d. Mark as: rename, keep, or TBD.
Detect clusters — 3+ candidates on same topic → prepare prefix suggestion.
Check backlinks — find all [[Old Name]] references across vault.
Preview and confirm — show the preview table (see references/report-format-note-rename.md for format and bilingual templates). Match the language the user is speaking. Include a rationale section below the table explaining non-trivial decisions. Do not execute until the user explicitly confirms.
Execute — rename files, update all [[Old Name]] and [[Old Name| references.
Skill Log — for every processed note (renamed, reviewed, or trashed), write the skill log. See references/skill-log.md for the full spec. YAML tag-list edits and skill-log callout edits MUST follow references/yaml-edits.md (recipes d + e). After writing tag/callout, restore filesystem birthtime from the YAML created value read during classification. Use touch -t (see references/skill-log.md § Birthtime Preservation). After auto-enrich in step 4, YAML created is almost always available. Restore birthtime from it. In the rare case that auto-enrich found no source (no filename date, no Git, no readable birthtime), restore from the pre-write filesystem birthtime captured in step 4.
Tag (idempotent):
VaultAutopilot already exists in the tags list in YAML frontmatter.tags field exists: create one with VaultAutopilot as the first entry.Callout (append-only):
> [!info] Vault Autopilot exists at the end of the note.> [!info] Vault Autopilot
>
> | Date | Skill | Action |
> |------|-------|--------|
> | YYYY-MM-DD | note-rename | [action] |
> | YYYY-MM-DD | note-rename | [action] | row to the existing table. Never create a second callout.Action types:
Renamed from [old filename without .md]Reviewed — name already descriptiveTrashed — accidental note (soft-delete to _trash/)Secret — sensitive content (moved to _secret/)Daily — moved to Daily Notes folderWrite findings file — for any non-trivial Findings (Class A/B/C/D as defined in references/findings-file.md), append a section to <VAULT>/_vault-autopilot/findings/<YYYY-MM-DD>-note-rename.md. Create the folder chain if missing. Never edit prior findings — append-only ledger.
Report and log — write summary, append to logs/run-history.md.
See references/report-format-note-rename.md for the full preview table format (bilingual), report template, and action types for skill log.
[[]])VaultAutopilot tag in frontmatter (exactly once)references/yaml-sanity.md (broadened from hardcoded "created:"/"modified:" to all quoted-keys)OK_QUOTEDnpx claudepluginhub neckarshore-skills/obsidian-vault-autopilot --plugin obsidian-vault-autopilotGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.