# skill-repo

Private collection of tool-neutral Agent Skills, plus optional vendor-specific
setup/integration adapters (currently: Claude Code).

## Why this structure

The `SKILL.md` format (YAML frontmatter + Markdown body + `scripts/` /
`references/` / `assets/`) is an open standard published at
[agentskills.io](https://agentskills.io), adopted by Claude Code, OpenAI
Codex, GitHub Copilot, Cursor, Gemini CLI, and others — the same skill files
work unmodified across these tools. What's *not* portable is host-specific
plumbing: slash commands, permission/allow-list syntax, plugin/marketplace
manifests. This repo keeps those two concerns physically separate.

## Structure

```
skill-repo/
├── skills/                              ← tool-neutral, single source of truth
│   └── obsidian-vault-kb/
│       ├── SKILL.md
│       ├── references/
│       └── scripts/                     ← config lives at ~/.agent-skills/<skill>/config.json
├── vendor/
│   └── claude-code/
│       ├── .claude-plugin/              ← (unused here; marketplace.json lives at repo root, see below)
│       └── plugins/
│           └── obsidian-vault-kb/
│               ├── .claude-plugin/
│               │   └── plugin.json
│               ├── skills/
│               │   └── obsidian-vault-kb -> ../../../../../skills/obsidian-vault-kb   (symlink)
│               ├── commands/
│               │   └── setup.md         ← -> /obsidian-vault-kb:setup
│               └── permissions-whitelist.template.json
└── .claude-plugin/
    └── marketplace.json                 ← must live at repo root per Claude Code's convention
```

**`skills/<name>/`** is the only place skill content actually lives —
`SKILL.md`, `scripts/`, `references/`. It assumes nothing about the host
tool: configuration is read from `~/.agent-skills/<skill-name>/config.json`,
a tool-neutral location, not `~/.claude/...`.

**`vendor/<tool>/`** holds everything specific to one host tool: for Claude
Code, that's the plugin manifest, the permissions whitelist (Claude Code's
`Bash(...)` allow-list syntax), and the `/setup` slash command. The plugin's
`skills/<name>` is a **symlink** into the top-level `skills/` directory —
there is exactly one copy of the skill content on disk, never a duplicate
that can drift out of sync.

Adding support for another tool (e.g. a future OpenAI/Codex-specific
adapter) means adding `vendor/<other-tool>/` with that tool's own
conventions, symlinked back to the same `skills/<name>/`, without touching
the skill content itself.

Symlinks assume a POSIX filesystem; this repo doesn't attempt to be
Windows-git-checkout-friendly.

## Adding this marketplace locally (Claude Code)

```
/plugin marketplace add /absolute/path/to/skill-repo
/plugin install obsidian-vault-kb
```

Then run `/obsidian-vault-kb:setup` to configure the vault path/mode and the
permissions whitelist.

## Adding a new skill to this repo

1. Create `skills/<new-skill-name>/` with `SKILL.md`, and `scripts/`
   /`references/` as needed. Keep configuration at
   `~/.agent-skills/<new-skill-name>/config.json` if the skill needs
   persistent config — don't hardcode a Claude-specific path here.
2. For Claude Code support, create
   `vendor/claude-code/plugins/<new-skill-name>/` with `.claude-plugin/plugin.json`,
   a `skills/<new-skill-name>` symlink back to the top-level `skills/`
   directory, and (if the skill needs restricted shell access) a
   `commands/setup.md` plus `permissions-whitelist.template.json` following
   the `obsidian-vault-kb` pattern — wrapper scripts that resolve their own
   scope from the config file rather than accepting raw paths as arguments,
   whitelisted only by exact absolute path, never generic tool wildcards
   like `Bash(find:*)`.
3. Add an entry for the new plugin to `.claude-plugin/marketplace.json`.
4. Bump `version` in the plugin's `plugin.json` and its `marketplace.json`
   entry on updates.