obsidian-doc-organizer

Files (3)

• SKILL.md
• openai.yaml · agents/
• organizing-patterns.md · references/

SKILL.md (first lines)

# Obsidian Document Organizer

Organize notes without imposing a personal taxonomy on the vault. Treat the vault's existing folders, properties, templates, links, and naming patterns as the source of truth.

## Resolve Scope

1. Use the vault and source paths explicitly supplied by the user.
2. Otherwise, use the nearest ancestor containing `.obsidian` as the vault root.
3. If no vault root is evident, ask for it. Do not scan the home directory looking for vaults.
4. If no source folder is specified, prefer an existing folder named `Inbox`, `_inbox`, `inbox`, or an equivalent already used by the vault. Do not create or assume a personal folder name.
5. Exclude `.obsidian`, trash, attachments, templates, generated exports, and archive folders unless the user explicitly includes them.

## Safety Rules

- Treat all vault content as private. Never copy note bodies, attachments, vault configuration, or absolute vault paths into this Skill repository, external logs, or unrelated temporary directories.
- Never display or propagate credential values found in notes. Report only the affected file and credential category, then pause that file for user review.
- Preserve the author's claims, tone, code, quotations, timestamps, block IDs, and embeds. Structure and classify; do not silently rewrite meaning.
- Do not overwrite an existing destination. Resolve name collisions before moving.
- For bulk changes or any move/rename, present a dry-run plan first unless the user already approved the exact source, destination, and transformation.
- Do not modify backlinks in unrelated notes merely to make the graph denser. Add or update links only when they improve navigation and the target exists or is intentionally being created.

## Workflow

### 1. Inspect Local Conventions

Read only the minimum needed:

- vault-level instructions or README files;
- a small sample of neighboring notes;
- existing templates and property names;
- the current folder and naming patterns.

Prefer established conventions over the generic patterns in this Skill. Read [organizing-patterns.md](references/organizing-patterns.md) only when the vault has no clear convention or the task involves a large mixed inbox.

### 2. Inventory the Source

For each candidate note, capture:

- current relative path;
- title or first meaningful heading;
- existing properties and tags;
- likely note type and topic;
- existing inbound/outbound wikilinks;
- attachments or embeds that may be affected by a move;
- confidence and unresolved ambiguity.

Detect duplicate titles, path collisions, invalid frontmatter, and links that already appear broken.

### 3. Propose a Plan

Choose destinations from existing vault folders. Create a new folder only when no current category fits and the grouping will contain more than one note.

Present a compact plan:

| Source | Proposed destination | Changes | Confidence | Reason |
| --- | --- | --- | --- | --- |

Put low-confidence notes in the existing inbox or leave them in place. Do not force a classification.

### 4. Normalize Conservatively

- Keep existing property names and types consistent with neighboring notes.
- Add only useful metadata supported by the content or filesystem facts.
- Preserve `created` values; add `modified` only if the vault already uses it.
- Prefer two or three precise tags over a generated tag cloud.
- Add a clear title when absent, but avoid renaming a file solely for cosmetic consistency.
- Use Obsidian wikilinks for vault-local notes and standard Markdown links for external URLs.

Use `$obsidian-markdown` conventions when editing note syntax.

### 5. Apply Approved Changes

Work in small batches. After each batch:

1. write the normalized note;
2. move or rename it within the vault;
3. update directly affected relative links when required;
4. confirm attachments and embeds still resolve;
5. leave ambiguous notes untouched.

### 6. Verify

- Parse every changed YAML frontmatter block.
- Confirm every moved source has exactly one destination.
- Check changed wikilinks, embeds, and attachment paths.
- Confirm no destination was overwritten and no unrelated file changed.
- Summarize changed, skipped, and unresolved notes without reproducing private note content.

From JobsHwang/skills, MIT.

More from JobsHwang/skills