Documentation doesn’t come easily to me. I’d much rather someone else do it. Or have it generated from code or assets or… something. Anything. So it seemed a natural choice for an AI agent to help me with.
I’ve used many tools for documentation over the years, but my preferred format is markdown. In the last couple of years I found Obsidian to be a great tool—not just because it uses markdown, but because it stores everything locally in what they call a Vault.
Inspired by NetworkChuck’s YouTube video, I decided to write a Claude Code agent that would help me automatically document not just the outcome of a project, but a running status of where I’m at. The idea was to create a complementary file that Claude Code could use for context between sessions.
I’ve been using this now for at least a couple of months and it’s been incredibly useful.
The two-part trick
The interesting bit is how to automatically invoke an agent from within a session where you’re already talking to Claude Code about the project you’re working on. The way I thought about this was to use a Claude Code Skill to trigger and prepare the context, then hand off to a Claude Code Agent that would actually do the work. So I have an assistant (the skill) and a manager (the agent).
The assistant looks out for trigger phrases, gathers the context—project name, location of existing project files in the Obsidian vault—and hands that off to an agent that runs in the background on a separate session. That manager agent has access to my Obsidian vault, specifically a Projects directory underneath it where it can take over management of any project documentation files. Based on configuration file ~/.claude/skills/obsidian-project-documentation-assistant/config.json, it can also check any changes into a private GitHub repo.
Trigger phrases it recognises:
"document this project"
"wrap this up"
"let's close out for the day"
"update my notes"
"what's the status?"If it’s not sure about project context, it’ll just ask.
The syncing problem
Something I found out the hard way… it wasn’t good enough to have things synced to a remote git repo for the situation where I was using the Obsidian mobile app. I had to use either the Obsidian Sync facility (which is subscription-based, and I wasn’t going to pay for that) or dump my Obsidian vault into iCloud Drive.
I did the latter. And so far it seems to be working out. iCloud handles syncing across my devices and seems fine. We’ll see.
Markdown quirks
This has also allowed me to discover nuances of markdown—at least markdown as used by Obsidian. John Gruber’s original definition never needed to consider these edge cases, but Obsidian has a known bug where checkboxes aren’t rendered correctly within tables. The workaround is to use HTML checkbox syntax, but when you’re using the Obsidian app it’s very convenient to be able to click or tap on a checkbox to toggle it. Rewriting it as an HTML tag doesn’t really cut it.
The solution? Go as simple as possible. Instead of using checkbox syntax, just use a character like Y or N to indicate state. Boring! But it works.
The triggering problem
Something else that isn’t always working accurately is the triggering of the agent itself. There are key phrases and inferences I’d like the skill to catch. For example, at the end of a session on a project with Claude Code, I’d say something like “OK, I’m ready to wrap up for the day.” I want the skill to pick up on that, prepare the context, and hand off to the documentation agent so it can go off and do its thing.
For whatever reason that doesn’t always work. Of course you can be very literal and just say “use the documentation agent to update all the documents.” That works every time. But I’m lazy.
What it actually does
The agent reads the existing project note (or creates one), extracts what happened from the conversation and git changes, updates the README and CLAUDE.md files, commits everything, and pushes to remote if configured. The result? It records decisions made, decisions not made, next steps, and enough context that when I come back days later I can just ask “so what’s next?” and pick up where I left off.
Obviously not an original idea, but it works really well when you have a lot of projects going at once. Like I do.
The tricky bit was getting it to handle the meta-documentation scenario—when I was using the tool to document the tool itself. Early versions would get confused and skip updating the repository’s own CLAUDE.md file. I had to add explicit logic to detect self-documentation and make sure it updated both the Obsidian vault note and the project’s own documentation. It took a couple of attempts to get right.
What I’ve learned using this
I’ve been using this for a couple of months now and a few things stand out.
The end-of-session workflow is wonderful. I can finish a long Claude Code session, tell the agent to “wrap stuff up”, and it handles all the documentation, commits, and pushes. Next morning—or a week later when I’ve forgotten everything—I start fresh with “so what’s next?” and we pick up immediately. No scrambling through git logs or trying to remember where I was. It just works.
Recording what we did not do turned out to be more valuable than I expected. My small brain keeps cycling back to the same ideas. For example, I spent an entire afternoon trying to figure out why the agent wouldn’t trigger reliably, only to find a note from two weeks earlier saying “tried fixing the trigger phrases, doesn’t work because of naming conflict, need to check installed skill versions.” Saved me from wasting another afternoon on the same problem.
Third, it documented itself. The assistant’s own project note in my Obsidian vault is maintained by its own tool.
The meta irony
Here’s the thing that makes me laugh. I used this documentation assistant to document the documentation assistant project itself. The Obsidian Project Assistant project note is maintained by its own tool. It is a complete history of how I built it, refactored it, fixed bugs, and changed direction. Meta… but also useful. It’s a living record of architectural decisions that would’ve been lost otherwise.
And honestly? It works better than I expected. Having a running log of what I built, why I refactored it from Node.js to bash, why I changed the skill/agent architecture—all of that context is preserved without me having to think about it.
If you want to try it
Anyway, if it’s of any use, you can check it out on my GitHub. As with any Claude Code Agents and Skills, the definition is held within a markdown file that you can adapt for your own purposes.
So go for it… or not.