# Obsidian Project Documentation Manager
A Claude Code skill that automatically triggers an agent to document your technical projects in Obsidian as you work.
## What is it?
As you work on projects with Claude Code, this skill and agent captures your progress and insights into a structured
Obsidian vault. No more forgetting what you tried, why you made certain decisions, or what worked and what didn't.
Perfect for makers, engineers, and tinkerers who work across multiple technical domains.
## Features
- 🤖 **Auto-documents projects** - Captures progress as you work with Claude Code
- 📁 **Organized by area** - Classifies projects including Hardware, Software, Woodworking, or Music Synthesis
- 🔗 **Relationship analysis** - Scores and links related projects using shared technologies and context signals
- 📝 **Template-based** - Uses consistent, customizable templates
- 🎯 **Context-aware** - Infers project details from your working directory
- 🔄 **Git integration** - Optionally commits and pushes changes to your vault repository
- 🚀 **Auto-backup** - Automatically push to remote GitHub repo for seamless backup
- 🌍 **Cross-project** - Works from any directory, updates central vault
## Installation
Install via the Claude Code plugin system — no cloning or bash scripts needed.
Run these two commands inside Claude Code:
```text
/plugin marketplace add ali5ter/claude-plugins
/plugin install obsidian-project-documentation@ali5ter
```
The first time you trigger the skill it will ask for your Obsidian vault path. No separate setup step is needed.
### Upgrading from v2.x
If you previously used the bash installer, run the migration script once to preserve your config and remove the old
files:
```bash
git clone https://github.com/ali5ter/obsidian-project-assistant.git
cd obsidian-project-assistant
./migrate
```
Then install via the two `/plugin` commands above.
### Uninstall
```text
/plugin uninstall obsidian-project-documentation@ali5ter
```
## Usage
Just work on your project with Claude Code and mention documentation:
```bash
cd ~/projects/arduino-temperature-sensor
claude
```
Then in conversation trigger the skill use a prompt like this example:
```text
I am building an Arduino based time machine. Let's document this project."
```
The skill will:
1. Detect it's a hardware project (from `.ino` files)
2. Extract the project name ("Arduino Time Machine")
3. Create a project note in your Obsidian vault
4. Track your progress as you work
### Examples of other prompts
Update existing project:
```text
I just got the I2C communication working. Update my project notes.
```
Exiting a working session with Claude Code:
```text
Ok I'm tired. Let's wrap it up for today.
```
Ask about the vault:
```text
"Show me my recent projects"
or
"What's in my Hardware area?"
```
## How It Works
The skill has two execution paths:
**Session start (read-only):** When you open a project, the skill reads your vault note and `CLAUDE.md`, then
briefly orients you — current phase, status, and the next steps from last time. No writes, no agent.
**Documentation run:** When you ask to document, wrap up, or update notes, the skill detects project context, asks
any questions upfront, then launches the documentation agent in the background. You can keep working while your
notes are updated and synced.
The agent also performs cross-project relationship analysis each session, scanning your vault to find genuinely
related projects based on shared technologies and explicit context signals, and writes scored wiki-links into each
note's frontmatter and body automatically.
### Context Detection
The skill intelligently detects project context:
1. **Project Name** - From git repo, directory name, or asks you
2. **Area Classification** - Based on file extensions and patterns (all areas counted in parallel; clear winner
wins, ties escalate to a question):
- **Hardware**: `.ino`, `.pcb`, `.sch`, `platformio.ini` (Arduino, embedded)
- **Software**: `.js`, `.ts`, `.py`, `.go`, `.rs`, `package.json`, `Cargo.toml`, `go.mod` (web, scripts, systems)
- **Woodworking**: `.stl`, `.blend`, `.f3d`, `.skp`, `cut-list.md` (CAD, shop files)
- **Music Synthesis**: `.pd`, `.maxpat`, `.syx`, `.amxd`, `patch-notes.md` (Pure Data, Max/MSP, Ableton)
3. **Description** - Extracts from conversation or README.md
### Vault Structure
Project notes are placed into a `Projects` directory in your Obsidian vault. No other folders are touched. If a
`Projects` folder already exists, only files managed by this skill are modified. If a note with the same name already
exists, project updates are appended to it rather than overwriting existing content.
## Configuration
The skill is configured in `~/.claude/obsidian-project-assistant-config.json` (created automatically on first use):
```json
{
"vault_path": "/Users/you/Documents/ObsidianVault",
"areas": ["Hardware", "Software", "Woodworking", "Music Synthesis"],
"auto_commit": false,
"auto_push": false,
"git_enabled": true
}
```
**Options:**
- `vault_path` - Absolute path to your Obsidian vault
- `areas` - List of project areas (customize as needed)
- `auto_commit` - Auto-commit changes without asking (default: false)
- `auto_push` - Auto-push commits to remote repository (default: false)
- `git_enabled` - Enable git integration (default: true)
## Requirements
- **Claude Code** - The official Claude CLI
- **Obsidian** - For viewing your notes - you can view the markdown notes files without Obsidian of course
- **Git** - If you version control your vault content in a private remote git repository (recommended)
## Customization
### Custom Areas
Edit `~/.claude/obsidian-project-assistant-config.json`:
```json
{
"areas": [
"Hardware",
"Software",
"3D Printing",
"Photography",
"Custom Area"
]
}
```
Update the `area-mapping.md` and `context-detection.md` files in the plugin cache at
`~/.claude/plugins/cache/ali5ter/obsidian-project-documentation/<version>/skills/obsidian-project-documentation/`
to help detect the custom area.
### Custom Template
The project note template used by the agent is located at `project-template.md` inside the plugin cache directory
`~/.claude/plugins/cache/ali5ter/obsidian-project-documentation/<version>/skills/obsidian-project-documentation/`.
You can edit this file directly to customize the structure and content of your project notes.
## Troubleshooting
**Skill not activating:**
- Check the plugin is installed: `/plugin list` in Claude Code
- Verify config has correct vault_path: `cat ~/.claude/obsidian-project-assistant-config.json`
- Restart Claude Code
**Wrong area detected:**
- Specify area in conversation: "This is a hardware project"
- Update config.json with project directory mappings
**Git commits failing:**
- Ensure git is installed and vault is a git repo
- Set `git_enabled: false` to disable git integration
## License
MIT License - see [LICENSE](LICENSE) for details.
## Links
- [GitHub](https://github.com/ali5ter/obsidian-project-assistant)
- [Issues](https://github.com/ali5ter/obsidian-project-assistant/issues)
- [Claude Code](https://code.claude.com)
- [Obsidian](https://obsidian.md)
---
Made with ❤️ for makers, tinkerers, and technical explorers