vault-cleanup-auditor

Q: How do I install vault-cleanup-auditor?

Run npx skills add https://github.com/brianrwagner/ai-marketing-claude-code-skills --skill vault-cleanup-auditor in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/vault-cleanup-auditor/ (personal) or .claude/skills/vault-cleanup-auditor/ (project).

by brianrwagnerSecurity

Audit your Obsidian vault in Claude Code — finds stale drafts, empty folders, duplicate filenames, and incomplete files. Saves a dated report.

Installs: 365
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/brianrwagner/ai-marketing-claude-code-skills --skill vault-cleanup-auditor

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads vault-cleanup-auditor automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Vault Cleanup Auditor

Runs 4 targeted checks against your Obsidian vault and saves a prioritized audit report to vault-audit/YYYY-MM-DD-audit.md. Takes under 30 seconds. No APIs, no paid services.

Run it monthly or whenever the vault starts feeling messy.

How to Use

Open Claude Code and say:

Run the Vault Cleanup Auditor skill against my vault at /path/to/vault.

Skill Instructions (for Claude Code)

When this skill is invoked, follow these phases exactly.

PHASE 1: INTAKE

Check whether the user has provided:

vault_path — absolute path to their Obsidian vault root

If missing, ask:

What's the absolute path to your Obsidian vault? (e.g. /root/obsidian-vault)

Do not proceed until confirmed.

PHASE 2: ANALYZE

Run all 4 checks. Capture raw output from each before writing the report.

Check 1 — Stale drafts (30+ days, unposted):

VAULT="VAULT_PATH_HERE"
echo "=== CHECK 1: STALE DRAFTS ==="
find "$VAULT/content/ready-to-post" -name "*.md" -mtime +30 2>/dev/null | while read f; do
  if grep -q '\*\*Posted:\*\* ❌' "$f" 2>/dev/null; then
    days=$(( ($(date +%s) - $(stat -c %Y "$f")) / 86400 ))
    echo "${days}d|${f##$VAULT/}"
  fi
done
echo "=== END CHECK 1 ==="

Check 2 — Incomplete files (no headings, 5+ lines):

VAULT="VAULT_PATH_HERE"
echo "=== CHECK 2: INCOMPLETE FILES ==="
find "$VAULT" -name "*.md" \
  -not -path "*/.git/*" \
  -not -path "*/.obsidian/*" \
  -not -path "*/.openclaw/*" | while read f; do
  if ! grep -qE '^#{1,6} ' "$f" 2>/dev/null; then
    lines=$(wc -l < "$f")
    if [ "$lines" -gt 5 ]; then
      echo "${lines}lines|${f##$VAULT/}"
    fi
  fi
done
echo "=== END CHECK 2 ==="

Check 3 — Duplicate filenames:

VAULT="VAULT_PATH_HERE"
echo "=== CHECK 3: DUPLICATE FILENAMES ==="
find "$VAULT" -name "*.md" \
  -not -path "*/.git/*" \
  -not -path "*/.obsidian/*" \
  -not -path "*/.openclaw/*" \
  -printf "%f\n" | sort | uniq -d | while read name; do
  echo "DUPE:$name"
  find "$VAULT" -name "$name" \
    -not -path "*/.git/*" \
    -not -path "*/.obsidian/*" | while read f; do
    echo "  PATH:${f##$VAULT/}"
  done
done
echo "=== END CHECK 3 ==="

Check 4 — Empty folders:

VAULT="VAULT_PATH_HERE"
echo "=== CHECK 4: EMPTY FOLDERS ==="
find "$VAULT" -type d -empty \
  -not -path "*/.git/*" \
  -not -path "*/.obsidian/*" \
  -not -path "*/.openclaw/*" | while read d; do
  echo "${d##$VAULT/}/"
done
echo "=== END CHECK 4 ==="

PHASE 3: OUTPUT

3a. Create the report directory and file:

VAULT="VAULT_PATH_HERE"
DATE=$(date +%Y-%m-%d)
mkdir -p "$VAULT/vault-audit"
REPORT="$VAULT/vault-audit/${DATE}-audit.md"
echo "Report path: $REPORT"

3b. Write the report using this exact structure:

# Vault Cleanup Audit — YYYY-MM-DD

Generated: YYYY-MM-DD HH:MM

**Summary:** 🔴 [N] stale | 🟡 [N] incomplete | 🟡 [N] dupes | 🟢 [N] empty

---

## 🔴 Stale Drafts (30+ days, unposted)

- [Nd old] path/to/file.md
[cap at 15 items — add "...and N more" if over]

## 🟡 Incomplete Files (no headings, 5+ lines)

- path/to/file.md (N lines)
[cap at 15]

## 🟡 Duplicate Filenames

- **filename.md**
  - path/one/filename.md
  - path/two/filename.md
[cap at 15 duplicate names]

## 🟢 Empty Folders

- path/to/folder/
[cap at 15]

---

**What to do:**
- 🔴 Stale drafts: post them, delete them, or archive to `content/posted/`
- 🟡 Incomplete files: finish or trash
- 🟡 Duplicates: merge or rename the less important one
- 🟢 Empty folders: safe to delete (or keep if you're about to use them)

3c. Print the summary to terminal:

✅ Audit saved to: vault-audit/YYYY-MM-DD-audit.md

Summary:
🔴 [N] stale drafts
🟡 [N] incomplete files
🟡 [N] duplicate filenames
🟢 [N] empty folders

PHASE 4: SELF-CRITIQUE

Before finalizing, check:

All 4 checks ran — Confirm output exists between each === CHECK N === / === END CHECK N === marker. If a check produced no output, note "0 issues found" in the report — do not skip the section.
Counts are accurate — The summary line counts must match the actual items listed in each section. Re-count if unsure.
Report saved correctly — Confirm the file exists at vault-audit/YYYY-MM-DD-audit.md. If the write failed, report the error and provide the report content inline.
No blank sections — Every section must either list items OR say "No issues found." Never leave a section header with nothing below it.

Fix any failures before delivering the final output.

Example Report

# Vault Cleanup Audit — 2026-03-01

Generated: 2026-03-01 08:14

**Summary:** 🔴 3 stale | 🟡 2 incomplete | 🟡 1 dupe | 🟢 2 empty

---

## 🔴 Stale Drafts (30+ days, unposted)

- [47d old] content/ready-to-post/linkedin/2026-01-12-ai-systems-post.md
- [38d old] content/ready-to-post/twitter/2026-01-21-founder-ops.md
- [31d old] content/ready-to-post/newsletter/2026-01-28-tools-roundup.md

## 🟡 Incomplete Files (no headings, 5+ lines)

- bambf/research/untitled-notes.md (23 lines)
- thinking/random-thoughts.md (11 lines)

## 🟡 Duplicate Filenames

- **README.md**
  - bambf/brand/README.md
  - bambf/tracking/README.md

## 🟢 Empty Folders

- content/queue/rejected/
- bambf/clients/archived/

---

**What to do:**
- 🔴 Stale drafts: post them, delete them, or archive to `content/posted/`
- 🟡 Incomplete files: finish or trash
- 🟡 Duplicates: merge or rename the less important one
- 🟢 Empty folders: safe to delete (or keep if you're about to use them)

Requirements

Claude Code with bash tool access
Bash + standard Unix tools: find, grep, wc, stat, date, awk
Read access to vault directory
Write access to vault-audit/ inside the vault (auto-created)
No APIs, no paid services, no external dependencies

FAQ

What does the vault-cleanup-auditor skill do?

Audit your Obsidian vault in Claude Code — finds stale drafts, empty folders, duplicate filenames, and incomplete files. Saves a dated report.

How do I install vault-cleanup-auditor?

Run npx skills add https://github.com/brianrwagner/ai-marketing-claude-code-skills --skill vault-cleanup-auditor in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/vault-cleanup-auditor/ (personal) or .claude/skills/vault-cleanup-auditor/ (project).

Which AI agents can use vault-cleanup-auditor?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is vault-cleanup-auditor safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains vault-cleanup-auditor?

It is published by brianrwagner in brianrwagner/ai-marketing-claude-code-skills. It has 365 recorded installs.