The CEO of the company that makes Obsidian has released a free AI instruction manual.
You can find it here:
https://github.com/kepano/obsidian-skills
It contains only 5 text files. It takes just 5 minutes to install, and it won't break any of your existing notes.
By adding these, the AI will understand Obsidian-specific formatting. This is the official answer to the problem of "AI messing up my notes."
When I saw this becoming a hot topic and opened my own environment to install it, I realized it was already there...
The file date was April 26th. I had installed it three and a half months ago and completely forgotten about it (lol).
So, what changed in my Obsidian over those three and a half months? I was curious, but the results were quite disappointing.
To jump to the conclusion: the official instructions alone are not enough. There is one more page you need to write yourself.
What AI Doesn't Know is Obsidian-Specific Syntax
Obsidian has several unique features that differ from standard memo apps.
To link notes, you surround them with [[ ]]. (Links)
To make a note stand out, you use a specific syntax to create a colored box. (Callouts)
The very top of a file has a section for dates and tags. (Properties)
AI writes without knowing these. So while the text might be fine, when you open it in Obsidian, the links aren't connected, or the boxes don't appear.
The 5 files I linked at the beginning fill that gap. They are divided as follows:
- obsidian-markdown (Correct syntax for links and boxes)
- obsidian-bases (Arranging notes like a database table)
- json-canvas (Creating diagrams connecting notes with lines)
- obsidian-cli (Searching the entire vault via commands)
- defuddle (Importing web pages as clean notes)
You can get them for free from the link above.
They aren't specific to any one AI tool, so they work the same with Claude Code or Codex.
Almost Nothing Changed After 3.5 Months of Having Them Installed
I honestly laughed when I found them. I already had the famous instructions... and I didn't even realize it (lol).
However, since they were only functioning in Claude Code, I copied the same 5 files to Codex on August 9th so I could use them from either.
Now, here is the main point.
What changed in my Obsidian after three and a half months?
- Notes using callouts: 32 out of 1,387
- Database views: 1
- Canvas: 1
Almost nothing changed.
This isn't to say the official instructions are bad. Naturally, the content is well-made.
When I first installed them, I tried them out, thought "Oh, that's handy," and that was it. Because I hadn't decided when to use them, this was the natural result.
The reason nothing changed is clear: the official instructions teach the "how to write."
Knowing how to write doesn't increase the content you write. It also doesn't decide where to put things.
There Are Two Types of Instructions to Give AI
I think this is very important.
There are two types of instruction manuals to give to an AI.
- The correct Obsidian syntax. This is the same for everyone's Obsidian, so the official team provides it.
- Your own internal rules. Where to put what. Which areas are okay to touch. Where finished products should go.
The official team only provides the former.
And the cause of a messy vault is usually the latter. It's more problematic to have something written correctly but placed in the wrong location than to have a syntax error.
This is where you run into trouble without "internal rules":
- Finished articles are saved in a different folder every time.
- AI adds text to a diary you wanted to keep as read-only.
- Even though you changed a folder name, new notes keep appearing under the old name.
In all these cases, the syntax is perfect. Only the placement and handling are wrong.
For example, the official instructions say, "Connect related notes with links." That is correct.
But my rule is the opposite: only link notes that I will "definitely open later." If I increase links too much, I can't find anything.
It's not about which is right; it's just that the official guide can't account for my specific circumstances.
No matter how much you use AI, your assets won't increase on their own. You already have the materials; you just lack the "container."
The official instructions teach you the "shape" of the container, but you have to decide what to put where.
━━━━━━━━━━━━
For those who use AI but find that content creation isn't getting easier:
Stop starting from zero every time by keeping your materials in one place.
I've started the "Minami's Obsidian x AI Agent Implementation Log."
Read for free here ↓
https://lifebaselab-m.com/p/r/j8MTvDdP?free1=x
━━━━━━━━━━━━
The 4 Minimum Items Needed for Your Internal Rules
I created a single file in Obsidian called "Operation Rules" and wrote everything there. Both Claude and Codex read this before starting work.
Here are the 4 items that will get things running at a minimum:
- Areas to touch vs. Read-only areas. In my case, diaries, web clips, and unsorted notes are read-only. This is the most important part.
- Destination for finished work. Fix the locations: X posts go here, Note articles go there. This stops the AI from asking every time.
- Escape route for when undecided. If you're unsure for 3 seconds, put it in "Unsorted." This prevents getting stuck on classification.
- Decide on one place to fix rules. Don't write operational rules in random notes. Fix the master file.
Especially the 4th one. Without this, rules scatter everywhere, and you lose track of which is the latest version.
I Do Weekly Checks to Ensure It Doesn't Just End with Installation
Among the 5 files mentioned earlier is obsidian-cli, which lets you inspect the entire vault with commands. It finds orphaned notes, tag usage counts, and broken links.
It's useful, but it doesn't work unless you run it.
So, I set up this "inspection" to run automatically as a weekly check. It runs on its own every Sunday morning and produces a report of broken link candidates and neglected notes.
The biggest benefit is not having to remember to do it.
Having it installed and having it running are two different things.
I'm saying this as someone who had it installed for three and a half months without anything changing, so I'm probably right (lol).
In Conclusion
Installing the official instructions takes 5 minutes. It's free, and it won't break your notes. There's no harm in doing it.
But that only changes the syntax.
The reason Obsidian gets messy when left to AI isn't because you're bad at using it. It's just that you don't have a single "internal rule" file that the AI can read yet.
So, don't feel like you have to memorize everything before delegating. The official team provides the syntax; you only need to write one page.
If you're going to do it today, start by writing one line to separate where the AI can touch and where it can't. "The diary folder is read-only. Do not rewrite it" is enough.
Even that will significantly reduce the amount of fixing you have to do after the AI is done.
━━━━━━━━━━━━
Thank you for reading to the end!
Announcement 📢
I'm running an Open Chat!
With the goal of increasing "Obsidians," I share daily stories about Obsidian x AI Agents that I don't post on X.
I also distribute gifts, so if you're interested, take a look ↓
