obsidian-project-documentation-assistant

by @ali5ter in AI & LLM

# Install this skill:

npx skills add ali5ter/obsidian-project-assistant

Or install specific skill: npx add-skill https://github.com/ali5ter/obsidian-project-assistant/tree/main/skill/obsidian-project-documentation-assistant

# Description

Document technical projects in Obsidian vault. Use when the User mentions "document this", "close out", "wrap up", "update notes", "track progress", "where are we at", "what is the status", or discusses maintaining project documentation, experiment logs, asks for the state of the project, what next steps are, or work progress in Obsidian.

# SKILL.md

name: obsidian-project-documentation-assistant
description: Document technical projects in Obsidian vault. Use when the User mentions "document this", "close out", "wrap up", "update notes", "track progress", "where are we at", "what is the status", or discusses maintaining project documentation, experiment logs, asks for the state of the project, what next steps are, or work progress in Obsidian.
version: 2.1.0
allowed-tools: Read, Bash, AskUserQuestion, Task

Obsidian Project Documentation Assistant

This skill helps maintain project documentation in an Obsidian vault while working with Claude Code. It automatically captures project progress and insights into structured, consistent notes.

Architecture: This skill acts as a lightweight launcher that detects project context, asks clarifying questions if needed, then launches an agent to handle the documentation work in the background.

How This Works

Situation 1: When a new working session is started

This skill:

Reads the AI Context file. (this should be a normal task already performed when a working session is started)
Reads the notes for this project if they exist to augement the context of what is happening with the project, the status, decisions made, and the next steps.
Welcomes the User back, asks how they're doing, and briefly inform them of what the next steps are for this new working session.

Situation 2: When activated during a working session

This skill:

Loads configuration from ~/.claude/skills/obsidian-project-documentation-assistant/config.json
Detects project context (name, area, type) from current directory
Asks the User for clarification if context is ambiguous
Launches a documentation agent with the detected context
The agent creates/updates notes, handles git operations, and returns results

Situation 3: When a working session is about to end

This skill:

Offers to tie up the project documentation if the User has not already asked to do so.
Perform the steps in Situation 2 above.

Tasks for Situation 1 and 2

Step 1: Load Configuration

cat ~/.claude/skills/obsidian-project-assistant/config.json

Expected format:

{
  "vault_path": "/path/to/ObsidianVault",
  "areas": ["Hardware", "Software", "Woodworking", "Music Synthesis"],
  "auto_commit": false,
  "auto_push": false,
  "git_enabled": true
}

If config doesn't exist, inform the User they need to reinstall the skill:

install install /path/to/vault

Step 2: Quick Context Detection

Detect Project Name

Try these methods in order:

From the User's message - If the User explicitly mentions project name in their request
From git repository:

bash git rev-parse --is-inside-work-tree 2>/dev/null && basename $(git rev-parse --show-toplevel)

Transform kebab-case → Title Case (e.g., "obsidian-project-assistant" → "Obsidian Project Assistant")

From directory name:

bash basename $(pwd)

If none of these work or result is generic (like "src", "build", "test"), refer to step 3 below.

Detect Project Area

Run quick file pattern checks:

# Check for Hardware indicators
if find . -maxdepth 2 -type f \( -name "*.ino" -o -name "*.cpp" -o -name "platformio.ini" \) 2>/dev/null | grep -q .; then
  echo "Hardware"
# Check for Software indicators
elif find . -maxdepth 2 -type f \( -name "package.json" -o -name "*.py" -o -name "*.js" -o -name "*.ts" \) 2>/dev/null | grep -q .; then
  echo "Software"
# Check for Woodworking indicators
elif find . -maxdepth 2 -type f \( -name "*.stl" -o -name "*.blend" -o -name "*.f3d" \) 2>/dev/null | grep -q .; then
  echo "Woodworking"
# Check for Music Synthesis indicators
elif find . -maxdepth 2 -type f \( -name "*.pd" -o -name "*.maxpat" \) 2>/dev/null | grep -q .; then
  echo "Music Synthesis"
fi

If no clear match, refer to step 3 below.

Extract Description

Try to extract a brief description:

Check if README.md exists and read first paragraph
Check package.json for description field
Parse the User's message for description
See step 3 below if the previous steps fail.

Step 3: Ask Clarifying Questions

If project_name is null OR area is null, use AskUserQuestion before launching agent:

If project name is unclear:

Question: "What would you like to name this project?"
Options:
  - [Current directory name]
  - [Git repo name if available]
  - Other (custom input)

If area is unclear:

Question: "What type of project is this?"
Options:
  - Hardware
  - Software
  - Woodworking
  - Music Synthesis
  - Other (custom input)

Step 4: Launch Documentation Agent

Once you have all context, launch an obsidian-project-documentation-manager agent.

Step 5: Report Results

When the agent completes, inform the User:

✅ Project documented successfully!
📝 Updated: {path_to_note}
📋 Summary: {what_was_documented}
🔄 Git: {commit_status} {push_status}

Error Handling

If errors occur:

Config missing: Instruct the User to run installation
Vault not accessible: Verify vault_path in config
Git operations fail: Report error, but still create/update note
Template missing: Use a basic template or ask the User to reinstall

Important things to remember

Use absolute paths for all file operations.
Use the current date for all timestamp operations.
Handle errors gracefully (missing templates, git failures, etc.).
When refering to the User, use their name and not 'User'. If in any doubt of the User's pronouns, ask the User but always remember them.

# README.md

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
🔗 Smart linking - Automatically links related notes and projects
📝 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

Clone the repository and run the installer:

git clone https://github.com/ali5ter/obsidian-project-assistant.git
cd obsidian-project-assistant
./install ~/Documents/MyVault

This will:

Check if the Obsidian Vault directory exists
Install note templates
Set up the Claude Code skill and agent
Optionally initialize a git repository

Usage

Just work on your project with Claude Code and mention documentation:

cd ~/projects/arduino-temperature-sensor
claude

Then in conversation trigger the skill use a prompt like this example:

I am building an Arduino based time machine. Let's document this project."

The skill will:

Detect it's a hardware project (from .ino files)
Extract the project name ("Arduino Time Machine")
Create a project note in your Obsidian vault
Track your progress as you work

Examples of other prompts

Update existing project:

I just got the I2C communication working. Update my project notes.

Exiting a working session with Claude Code:

Ok I'm tired. Let's wrap it up for today.

Ask about the vault:

"Show me my recent projects"
or 
"What's in my Hardware area?"

How It Works

The skill uses an efficient, non-blocking architecture that works in the background. It does this by using the Obsidian Project Documentation Assistant skill to detect your project context, asks any questions upfront, then triggers the Obsidian Project Documentation Manager agent which handles the documentation work asynchronously. This means you can keep working while your notes are being updated and synced.

Context Detection

The skill intelligently detects project context:

Project Name - From git repo, directory name, or asks you
Area Classification - Based on file extensions and patterns:
Hardware: .ino, .cpp, platformio.ini (Arduino, embedded)
Software: .js, .py, package.json (web, scripts)
Woodworking: .stl, .blend, .f3d (CAD files)
Music Synthesis: .pd, .maxpat (Pure Data, Max/MSP)
Description - Extracts from conversation or README.md

Vault Structure

Any project notes will be placed into a Projects directory in your Obsidian Vault folder. If you already use a Vault, no other folders will be touched. If you already use a Project folder in your existing Obsidian Vault, unless a notes file using the same name the Obsidian Project Documentation Manager agent wants to use, there will be no changes to existing content. If, conicidentally, there is a file with the name the Obsidian Project Documentation Manager agent wants to use, project updates will be appended to it.

Configuration

The skill is configured in ~/.claude/skills/obsidian-project-documentation-assistant/config.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/skills/obsidian-project-documentation-assistant/config.json:

{
  "areas": [
    "Hardware",
    "Software",
    "3D Printing",
    "Photography",
    "Custom Area"
  ]
}

Update the ~/.claude/skills/obsidian-project-documentation-assistant/area-mapping.md and ~/.claude/skills/obsidian-project-documentation-assistant/context-detection.md definitions to help detect the custom area.

Custom Template

The project note template used by the agent is located at ~/.claude/skills/obsidian-project-documentation-assistant/project-template.md. You can edit this file directly to customize the structure and content of your project notes.

Troubleshooting

Skill not activating:

Check that ~/.claude/skills/obsidian-project-documentation-assistant/ exists
Verify config.json has correct vault_path
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 for details.

Links

Made with ❤️ for makers, tinkerers, and technical explorers

# Supported AI Coding Agents

This skill is compatible with the SKILL.md standard and works with all major AI coding agents:

⚡ Amp 🚀 Antigravity 🤖 Claude Code 🦀 Clawdbot 📝 Codex ▶️ Cursor 🤖 Droid 💎 Gemini CLI 🐙 GitHub Copilot 🪿 Goose 📊 Kilo Code 🔧 Kiro CLI 💻 OpenCode 🦘 Roo Code 🌲 Trae 🏄 Windsurf

Learn more about the SKILL.md standard and how to use these skills with your preferred AI coding agent.

obsidian-project-documentation-assistant

# Description

# SKILL.md

Obsidian Project Documentation Assistant

How This Works

Situation 1: When a new working session is started

Situation 2: When activated during a working session

Situation 3: When a working session is about to end

Tasks for Situation 1 and 2

Step 1: Load Configuration

Step 2: Quick Context Detection

Detect Project Name

Detect Project Area

Extract Description

Step 3: Ask Clarifying Questions

Step 4: Launch Documentation Agent

Step 5: Report Results

Error Handling

Important things to remember

# README.md

Obsidian Project Documentation Manager

What is it?

Features

Installation

Usage

Examples of other prompts

How It Works

Context Detection

Vault Structure

Configuration

Requirements

Customization

Custom Areas

Custom Template

Troubleshooting

License

Links

# Related Skills

# Supported AI Coding Agents

Confirm

Submit a Skill