Henner M. Kruse
89 lines
4.0 KiB
Markdown
89 lines
4.0 KiB
Markdown
# 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.
|