After Handing an Agent Thousands of Notes, the Best Rules Were What It Must Not Do

What You Will Get

Hand your Obsidian vault to an Agent (Claude Code, Codex, or Grok Bot all work) to help manage it: first run a read-only health check to see the problems clearly, then define where it may and may not touch, install two ready-made Obsidian Skill sets, and finally have it help you find related notes and clean up orphan notes. This article includes 3 copy-ready prompts.

The point of this article is not to get the Agent to do more work, but to first spell out what it should not do. A heavy note-taker handed over more than five thousand notes to an Agent for over a month, and looking back, the most helpful rules were the ones that marked off forbidden zones.

Why Set Boundaries First

Agents are very good at "doing": batch-creating pages, adding links, tidying formats, and they can change thousands of files in one night. The problem is that what a vault most often lacks is not tidiness but thought-through content. If you have it tidy everything in one click, you will most likely end up with a neater batch of empty shells.

Before you start, keep three points in mind:

• Notes are files, and tools can be swapped. Your notes are ordinary .md files. The Agent is only there to help, and the vault's structure is yours to decide.
• Keep Agent-written material separate from your own writing. That way you can tell later which parts are your ideas and which are machine output.
• Ask before bulk deletes or edits. Deleting, bulk-adding links, or bulk-moving does not happen without your nod.

Step 1: Run a Read-Only Health Check First

The first time, only have it count things and change nothing. Send the following to the Agent, replacing the path with your vault's:

Please run a read-only audit of my Obsidian vault at [vault path]. Do not modify, move or create any files.

Count and report:
1. How many .md notes there are in total, and how many in each top-level folder;
2. How many "stubs" there are (notes under 50 bytes with almost no content), and which folders hold most of them;
3. How many unresolved links there are ([[links]] pointing to notes that don't exist);
4. How many orphan notes there are (nothing links to them and they link to nothing);
5. In three to five sentences, what the vault's biggest problem is, plus three suggestions. Do not act on them yet.

Save the results so you can compare them a month later. On that user's first check, of their five thousand-plus notes, nearly 40% in the root folder were almost empty, there were roughly 8,000 dangling links, and the diagnosis was "collecting disguised as thinking": a lot gathered, little actually worked out.

Step 2: Define Folders and Guardrails

This step determines how the Agent behaves from then on. Write the rules as a paragraph and store it where it will read them every time (for Claude Code, the project's CLAUDE.md; for Grok Bot, the bot's instructions). Do not count on it remembering what was said in chat.

The last two guardrails look small but matter most: the "fix" an Agent is most likely to make is creating an empty page for every broken link. The links look all fixed, but the vault now holds another batch of empty shells.

Step 3: Install Two Ready-Made Skill Sets

A Skill is a set of operating instructions written for the Agent. Once installed, it knows Obsidian's note formats and conventions without being re-taught each time (if you are unfamiliar, see the Skill handbook). Run this in the terminal:

npx skills add https://github.com/kepano/obsidian-skills
npx skills add https://github.com/Jackywine/jackywine-digital-garden-skills

• The first set comes from kepano, CEO of Obsidian. It teaches the Agent to write Obsidian Markdown, Bases and Canvas correctly, and to use Obsidian's official command-line tool (CLI).
• The second set is open-source from the user above and includes first-time setup, clipping, finding related notes (related-notes), and finding orphan notes (orphan-notes). It complements the first set and does not contain its content, so install both.

Restart the Agent after installing. At the first conversation, have it run digital-garden-onboarding: it asks one question at a time and walks you through setting your name, vault path, folder conventions and guardrails.

Then turn on Obsidian's command-line tool (enable it following the official CLI documentation). With it, the Agent can look up tags and backlinks in a single command, without scanning the whole vault every time, which is faster and uses less quota.

Step 4: Have It Do Two Things Day to Day

The most worthwhile things to hand the Agent are not "tidying" but these two:

An idea I had today: [your idea].
Use related-notes to find 3 to 5 related notes in my vault. For each, add one line on why it is worth reading alongside this idea now, plus its obsidian:// link.
Don't add links automatically and don't repeat back what I just said; if nothing is truly related, say so.

Use orphan-notes to list the orphan notes in my vault and any pairs of notes that are nearly related but not linked, and save the list in AI outputs/.
Read only: no new links, no deletions. I'll pick which ones to connect.

The key to the first prompt is "one sentence on why each": if it only rephrases what you just said, the feature has no value.

Step 5: Run the Check Again After a Month

Run the same prompt from Step 1 again and compare with the last result. That user's one-month result shows the point clearly: dangling links dropped from about 8,000 to just over 4,000, nearly half gone; but the proportion of short stubs in the root folder barely changed.

Tools can fix links, but they cannot fix ideas that were never written down. So do not hand that last part to the Agent: pull 20 to 30 short stubs and go through them yourself one by one. Flesh out the ones you can turn into complete thoughts, and delete the ones you cannot write out.

Notes

• If your vault has fewer than a thousand notes, you don't need this setup. Getting the content written matters more than organizing it.
• If you expect the Agent to tidy the vault in one click, this is not for you. The core of this method is to have it do as little as possible.
• Do not paste tokens or passwords into the conversation. That user once pasted a GitHub access token into the chat log while pushing a repository, and the only fix afterward was to revoke it and get a new one.
• This approach is for a single-person vault. A multi-person knowledge base needs its permissions designed separately.
• To first connect Obsidian with an Agent, see the tutorial Connecting Obsidian to an AI Agent, and the Obsidian handbook.

References

• kepano/obsidian-skills (GitHub)
• jackywine-digital-garden-skills (GitHub)
• Obsidian CLI official documentation
• Agent Skills specification