AGENT SKILL

obsidian-vault-setup

Use when setting up the shared atmosphere-vault Obsidian vault on a new machine or for a new team member. Guides through cloning, installing plugins, symlinking claude_docs, and verifying the Obsidian CLI.

License 许可
Apache-2.0
最近更新
2026-11-15
Stars
★ 3.8k
Forks
765

01 前言 Front Matter

name
obsidian-vault-setup
metadata
{ "role": "specialist", "scope": "implementation", "domain": "devops", "version": "1.1.0", "triggers": "obsidian, vault, setup, onboard, atmosphere-vault", "output-format": "report" }
description
Use when setting up the shared atmosphere-vault Obsidian vault on a new machine or for a new team member. Guides through cloning, installing plugins, symlinking claude_docs, and verifying the Obsidian CLI.
user-invocable
true

02 资源文件 1

03 SKILL.md 正文

Obsidian Vault Setup

Role

DevOps assistant for setting up the shared atmosphere-vault Obsidian knowledge base on a developer machine.

When to Use

Invoke when a team member needs to:

  • Clone and open the atmosphere-vault for the first time
  • Connect their atmosphere checkout to the vault via symlink
  • Verify the Obsidian CLI and the vault's commit timer are configured correctly

Defaults

PROJECT_DIR = ~/workspace/atmosphere/atmosphere
VAULT_DIR   = ~/workspace/atmosphere/atmosphere-vault
VAULT_REPO  = git@github.com:Atmosphere/atmosphere-vault.git

Ask the user for PROJECT_DIR and VAULT_DIR if they differ from defaults. The vault is a sibling of the project directory: the routing block reaches it as ../atmosphere-vault, and the vault's scripts/sync-claude-memory.sh reaches the checkout as ../atmosphere.

Workflow

Step 1: Verify prerequisites

Check that the following are installed:

# Obsidian desktop app (required)
ls /Applications/Obsidian.app 2>/dev/null && echo "Obsidian: OK" || echo "Obsidian: MISSING — install from https://obsidian.md"

# The app's own CLI (Settings → General → enable the command line interface)
command -v obsidian   # must print /Applications/Obsidian.app/Contents/MacOS/obsidian

If command -v obsidian prints an npm path, the unrelated obsidian-cli npm package is shadowing the real CLI — npm uninstall -g obsidian-cli.

Step 2: Clone atmosphere-vault

# Only if not already present
if [ ! -d "$VAULT_DIR" ]; then
  git clone git@github.com:Atmosphere/atmosphere-vault.git "$VAULT_DIR"
fi

# Verify on main branch
cd "$VAULT_DIR" && git status

Step 3: Install plugins

Downloads obsidian-git and Templater and writes their pre-configured settings.

cd "$VAULT_DIR"
./scripts/install-plugins.sh

This script:

  • Downloads main.js + manifest.json for each plugin from GitHub releases
  • Copies the tracked settings from .obsidian/plugin-configs/ into each plugin's data.json (obsidian-git: auto-commit and auto-push every 10 minutes, pull before push; Templater: template folder Templates/, trigger on new file creation)
  • Writes .obsidian/community-plugins.json to enable both plugins

Plugin binaries are excluded from git (.obsidian/plugins/ is in .gitignore). Re-running the script is safe — it overwrites existing files idempotently.

Step 4: Create claude_docs symlink

This links atmosphere/claude_docs/ to atmosphere-vault/Claude Outputs/ so Claude Code session outputs land directly in the vault.

cd "$PROJECT_DIR"

# Safety check: do NOT overwrite a real directory
if [ -d claude_docs ] && [ ! -L claude_docs ]; then
  echo "ERROR: claude_docs/ exists as a real directory. Back it up before proceeding."
  exit 1
fi

ln -sf "$VAULT_DIR/Claude Outputs" claude_docs
ls -la claude_docs   # verify symlink resolves

Step 5: Open vault in Obsidian

Instruct the user to:

  1. Open Obsidian
  2. Click Open folder as vault
  3. Navigate to $VAULT_DIR and click Open
  4. When prompted "Trust and enable plugins?", click Trust author and enable plugins

The vault's commit timer is obsidian-git's, configured by Step 3 to commit and push every 10 minutes. Run exactly one per machine: if the machine already runs another commit timer of its own for the vault (nothing in this repo or the vault ships one), set obsidian-git's auto-commit and auto-push intervals to 0 there.

Step 6: Verify sync flow

After obsidian-git is configured:

# Create a test file in Claude Outputs
echo "# Test" > "$PROJECT_DIR/claude_docs/test.md"

# Verify it appears in the vault
ls "$VAULT_DIR/Claude Outputs/test.md"

# Clean up
rm "$PROJECT_DIR/claude_docs/test.md"

Constraints

  • NEVER overwrite an existing claude_docs/ directory that contains real files
  • ALWAYS verify atmosphere-vault is on main branch before linking
  • NEVER install the npm obsidian-cli package — it shadows the app's own obsidian CLI
  • If PROJECT_DIR or VAULT_DIR differ from defaults, ask for them before running any commands

Success Criteria

  • ls -la $PROJECT_DIR/claude_docs shows a symlink pointing to $VAULT_DIR/Claude Outputs
  • Obsidian opens the vault and shows all folders (Architecture, APIs, Methodology, Development)
  • command -v obsidian resolves to the app bundle
  • Exactly one commit timer commits into the vault on this machine (Step 5)

04 同仓库更多 Skills