Added git-manager, updated READMEs
This commit is contained in:
Henner M. Kruse
@@ -1,88 +1,72 @@
|
||||
# skill-repo
|
||||
|
||||
Private collection of tool-neutral Agent Skills, plus optional vendor-specific
|
||||
setup/integration adapters (currently: Claude Code).
|
||||
A collection of Claude Code plugins (Agent Skills) for working with git
|
||||
repositories and Obsidian vaults. Each plugin does one job, ships its own
|
||||
setup command, and only asks for the minimum shell access it actually
|
||||
needs.
|
||||
|
||||
## Why this structure
|
||||
> Looking for how this repo is structured internally, or how to add a new
|
||||
> plugin to it? See [ARCHITECTURE.md](ARCHITECTURE.md). This README is
|
||||
> about what's in the box and how to use it.
|
||||
|
||||
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.
|
||||
## What's in here
|
||||
|
||||
## Structure
|
||||
| Plugin | What it does |
|
||||
|---|---|
|
||||
| [`git-manager`](vendor/claude-code/plugins/git-manager/README.md) | Runs git commands (status, log, commit, push, pull, ...) across one or more repositories through a single whitelisted script — no more permission prompts breaking on `cd && git ...` chains. |
|
||||
| [`obsidian-vault-kb`](vendor/claude-code/plugins/obsidian-vault-kb/README.md) | Turns an Obsidian vault into a searchable knowledge base Claude can consult and (optionally) write back to. |
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
Click through to each plugin's own README for details, examples, and setup
|
||||
options.
|
||||
|
||||
**`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/...`.
|
||||
## Installing
|
||||
|
||||
**`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)
|
||||
From within Claude Code:
|
||||
|
||||
```
|
||||
/plugin marketplace add /absolute/path/to/skill-repo
|
||||
```
|
||||
|
||||
(or a Git URL, once this repo is hosted somewhere reachable). Then install
|
||||
whichever plugin(s) you want:
|
||||
|
||||
```
|
||||
/plugin install git-manager
|
||||
/plugin install obsidian-vault-kb
|
||||
```
|
||||
|
||||
Then run `/obsidian-vault-kb:setup` to configure the vault path/mode and the
|
||||
permissions whitelist.
|
||||
Each plugin has its own `/‹plugin-name›:setup` command — run it once after
|
||||
installing to configure paths and permissions. See the individual plugin
|
||||
READMEs for what each setup asks for.
|
||||
|
||||
## Adding a new skill to this repo
|
||||
## A shared design philosophy
|
||||
|
||||
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.
|
||||
Both plugins in this repo follow the same rules, worth knowing upfront:
|
||||
|
||||
- **Minimal permissions.** Neither plugin whitelists generic commands like
|
||||
`Bash(git:*)`, `Bash(find:*)`, or `Bash(cd:*)`. Each whitelists exactly
|
||||
one wrapper script, pinned to its exact absolute path. The wrapper script
|
||||
itself enforces what it's allowed to do (allowed git subcommands, vault
|
||||
boundaries) — the whitelist just says "this specific, self-limiting
|
||||
script may run without asking."
|
||||
- **Nothing destructive is silent.** Actions that change files — writing
|
||||
notes, pushing to a remote — either aren't whitelisted (so you still get
|
||||
a normal confirmation prompt) or are scoped tightly enough that there's
|
||||
nothing surprising they can do.
|
||||
- **Config lives outside Claude Code**, at `~/.agent-skills/<plugin-name>/config.json`.
|
||||
Both plugins follow the open [Agent Skills](https://agentskills.io)
|
||||
format for their actual skill content (`SKILL.md` + `scripts/`), so that
|
||||
part works the same if you ever run them from a different
|
||||
Agent-Skills-compatible tool — only the Claude Code-specific setup
|
||||
command and permissions live under `vendor/claude-code/`.
|
||||
|
||||
## Updating
|
||||
|
||||
After pulling changes to this repo:
|
||||
|
||||
```
|
||||
/plugin marketplace update skill-repo
|
||||
```
|
||||
|
||||
Re-run a plugin's `/‹plugin-name›:setup` if its permissions or config
|
||||
format changed (check that plugin's README/changelog).
|
||||
|
||||
Reference in New Issue
Block a user