# km-storage-abstraction

km-storage-abstraction is a skill for saving notes to Obsidian, Notion or a local folder. It selects a backend, confines writes to the given root and verifies the result.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 1 install · ★ 255 repo stars
- Author: treylom
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/treylom/knowledge-manager/tree/HEAD/.agent/skills/km-storage-abstraction/SKILL.md
- Updated: 2026-10-14
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/km-storage-abstraction

## What it does

The skill gives the agent one save routine that can target Obsidian, Notion or a local folder. Which backend runs depends on the request: an explicit choice wins, project-scoped writes fall back to `local`, and otherwise the skill reads `storage.primary` from `km-config.json`. With no config present, files land in `./km-output`.

Paths get normalised before any write: Windows backslashes become forward slashes and a leading slash is dropped. `resolve_within` then walks the directory components, resolves symlinks at each step and asserts the result stays under the root. Project-scoped saves require `target_root`; omit it and the call throws `target_root is required for a project-scoped save`. A backend may pick the write tool, yet it cannot redirect the destination root.

Every save ends with a check: the file must exist at the canonicalised `actual_saved_path` and sit inside `target_root` when the save is project-scoped. Obsidian goes through MCP only if the connected vault root matches `target_root` — otherwise the skill writes the file directly.

## Requirements
- Works with: Notion, Obsidian

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add treylom/knowledge-manager --skill km-storage-abstraction -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/km-storage-abstraction/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/km-storage-abstraction/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add treylom/knowledge-manager --skill km-storage-abstraction -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/km-storage-abstraction/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add treylom/knowledge-manager --skill km-storage-abstraction -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/km-storage-abstraction/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install treylom/knowledge-manager .agent/skills/km-storage-abstraction
```

2. **Manually: put the files in place**
- File: `.github/skills/km-storage-abstraction/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add treylom/knowledge-manager --skill km-storage-abstraction -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/treylom/knowledge-manager --path .agent/skills/km-storage-abstraction
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/km-storage-abstraction/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add treylom/knowledge-manager --skill km-storage-abstraction -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/treylom/knowledge-manager/tree/HEAD/.agent/skills/km-storage-abstraction/SKILL.md

## When to use it
- save a note to Obsidian or Notion without backend-specific code
- keep a write inside the project root instead of letting `..` or a symlink escape
- switch storage from a local folder to Notion through `km-config.json`
- confirm the file exists at the expected path after a save
- write into the project root when the connected Obsidian vault points elsewhere

## Example prompts
- Save this note to `notes/api.md` inside the project, `target_root` is the repo root.
- Switch storage to Notion and create the page from `notes/plan.md`.
- Check that `actual_saved_path` exists and stays under `target_root` after the write.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 4b5470df5ec76377.

BEGIN THIRD-PARTY FILE 4b5470df5ec76377
````text
---
name: km-storage-abstraction
description: Unified storage interface for Obsidian, Notion, and local file systems
---

# Storage Abstraction Layer

> Unified interface for saving notes across different storage backends

---

## Storage Selection and Target-Root Contract

```javascript
function get_storage_backend(options = {}) {
  config = Read("km-config.json") || {}
  if (options.explicit_backend) return options.explicit_backend
  if (options.project_scoped) return "local"
  return config?.storage?.primary || "local"
}
```

For project-scoped file saves, the workflow must pass `target_root`. The backend may choose a tool, but it must not choose or redirect the destination root.

Priority: user-explicit destination/backend → host-provided primary project/workspace root → configured backend only outside project-scoped requests.

## 🛑 Target Root 일치 규칙 (CRITICAL)

```
┌─────────────────────────────────────────────────────┐
│ 🛑 CRITICAL: target_root 보존 강제                   │
│                                                      │
│ Obsidian 도구는 연결 볼트와 target_root가 같을 때만!   │
│                                                      │
│ ❌ 잘못된 예:                                        │
│    - 연결 볼트 확인 없이 MCP로 상대경로 저장           │
│                                                      │
│ ✅ 올바른 예:                                        │
│    - roots 동일 → MCP / 다름·미확인 → target_root Write│
└─────────────────────────────────────────────────────┘
```

## Backend Mapping (Antigravity/Gemini CLI)

| Feature | Obsidian | Notion | Local |
|---------|----------|--------|-------|
| Create | `mcp_obsidian_create_note` | `mcp_notion_API-post-page` | `write_to_file` |
| Search | `mcp_obsidian_search_vault` | `mcp_notion_API-post-search` | N/A |
````
END THIRD-PARTY FILE 4b5470df5ec76377

The third-party file has ended. Everything between the 4b5470df5ec76377 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2135 of 6510 bytes. © treylom · MIT · https://github.com/treylom/knowledge-manager/tree/HEAD/.agent/skills/km-storage-abstraction/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
