skill-repo/ARCHITECTURE.md

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, 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.