# Skill Symlinks

Keep your AI agent skills in an Obsidian vault and link them into the folders agents read skills from, such as `~/.claude/skills` or `~/.agents/skills`. Edit a skill in Obsidian and every agent sees the change right away.

```
vault/skills/review/           →  ~/.claude/skills/review, ~/.agents/skills/review
vault/skills/claude-only/tdd/  →  ~/.claude/skills/tdd
```

## Install

In Obsidian, open **Settings → Community plugins → Browse**, search for **Skill Symlinks**, then install and enable it.

You can also install it with [BRAT](https://obsidian.md/plugins?id=obsidian42-brat) using `v-samodelkin/obsidian-skill-symlinks`.

## How it works

- **Skills folder.** Each subfolder of the skills folder is a skill. By default a folder counts only once it contains `SKILL.md`.
- **Agent folders.** Links go into `~/.agents/skills` and `~/.claude/skills`. You can turn either off or add another folder. A missing folder is skipped until it exists.
- **Groups.** A group is a folder inside the skills folder whose subfolders are skills. For each group, and for the top level, choose which agent folders it links into.
- **Live.** Creating, renaming or deleting a skill updates the links within a second. The plugin also syncs when Obsidian starts and when you close its settings.
- **Folder renames.** Renaming or moving the skills folder, a group, or their parent folders inside the vault updates the saved paths and links. Group exclusions are preserved.
- **Vault moves.** From 1.0.1, each sync records the exact links it manages. After you rename or move the vault and reopen it, sync repairs those links if their old destinations no longer exist. Run sync once before moving the vault. Links already broken before upgrading from 1.0.0 need manual repair because that version did not record their destinations.

## Which agent folders

Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode and most other agents read `~/.agents/skills`. Claude Code reads only `~/.claude/skills`. Cursor and OpenCode read both, so they may list a skill twice. Add another folder only for an agent that reads neither: an agent that reads two linked folders lists each skill twice.

## Safety

This plugin creates and deletes symlinks **outside your vault**.

- Sync is off after install. Turning it on shows every link it will create or remove before anything is written.
- It only removes symlinks that point into this vault, or recorded links whose old destinations no longer exist after a vault move. Live links to a copied vault, links repointed outside this vault, and untracked broken links are left alone. Real folders are never replaced.
- It never deletes or moves files, in the vault or elsewhere.
- **Remove all links created by this plugin** in the command palette removes its links and turns sync off. Run it before uninstalling.

Desktop only. On Windows the links are directory junctions, which need no admin rights.

## Development

```
npm install
npm run dev      # watch build into main.js
npm test
npm run lint
```

Release: bump `version` in `manifest.json` and `package.json`, add it to `versions.json`, then push a tag with the same version. The workflow drafts a GitHub release with `main.js`, `manifest.json` and `styles.css`.