From 10401600351cc83b5614f1b80981543da15a23a4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gabor=20K=C3=B6rber?= <gab@g4b.org>
Date: Sat, 9 May 2026 22:26:09 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20add=20README=20with=20install=20?=
 =?UTF-8?q?instructions?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md | 127 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 127 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..98b5603
--- /dev/null
+++ b/README.md
@@ -0,0 +1,127 @@
+# ai_skills
+
+A small collection of personal [Claude Code](https://docs.claude.com/en/docs/claude-code) skills, packaged as a plugin so other projects can install them via a marketplace.
+
+## Skills
+
+- **workpad** — Decides *where* and *when* to put working documents (reports, plans, brainstorms, designs, research notes, specs). Steers other skills toward a single predictable location for thinking-in-markdown instead of scattering files across `/tmp`, the repo root, or per-skill scratch directories.
+- **research-tree** — Orchestrates multi-topic research as a dependency tree of parallel phases. Within a phase agents run in parallel; between phases later agents inherit earlier reports. Use it for "research X, Y and Z" / "do a deep dive on…" prompts where a single agent would skim.
+- **implementation-orchestration** — How to drive non-trivial implementation work across one or more agents: when to delegate vs. work inline, how to sequence agents, and how to handle test/compile failures without thrashing. Defaults to sequential execution; parallel only when work is genuinely independent.
+- **markdown-embedded-svg** — Rules and defaults for putting SVG into Markdown. Different renderers (GitHub, Gitea, Obsidian, VS Code) sanitize inline SVG very differently, so the default is to save SVGs as separate files and reference them via image-link syntax; inline SVG is treated as a special case.
+
+## Install as a plugin (whole repo)
+
+The repo ships a marketplace at `.claude-plugin/marketplace.json` exposing one plugin (`ai-skills`).
+
+### From `git.g4b.org`
+
+Interactive:
+
+```
+/plugin marketplace add git@git.g4b.org:g4borg/ai_skills.git
+/plugin install ai-skills@ai-skills
+```
+
+Or declaratively in a project's `.claude/settings.json`:
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "ai-skills": {
+      "source": {
+        "source": "git",
+        "url": "git@git.g4b.org:g4borg/ai_skills.git"
+      }
+    }
+  },
+  "enabledPlugins": {
+    "ai-skills@ai-skills": true
+  }
+}
+```
+
+### From a local clone
+
+If you have the repo cloned locally and want to develop against it:
+
+```
+/plugin marketplace add /path/to/ai_skills
+/plugin install ai-skills@ai-skills
+```
+
+Or in `settings.json`:
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "ai-skills": {
+      "source": { "source": "local", "path": "/path/to/ai_skills" }
+    }
+  },
+  "enabledPlugins": { "ai-skills@ai-skills": true }
+}
+```
+
+### From GitHub (mirror)
+
+If the repo is mirrored to GitHub as `<user>/ai_skills`:
+
+```
+/plugin marketplace add <user>/ai_skills
+/plugin install ai-skills@ai-skills
+```
+
+Or in `settings.json`:
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "ai-skills": {
+      "source": { "source": "github", "repo": "<user>/ai_skills" }
+    }
+  },
+  "enabledPlugins": { "ai-skills@ai-skills": true }
+}
+```
+
+## Fetch individual skills
+
+If you only want one or two skills (no plugin, no marketplace), copy them straight into a target project's or user-level skills directory.
+
+User-level (available in every project):
+
+```sh
+git clone git@git.g4b.org:g4borg/ai_skills.git /tmp/ai_skills
+mkdir -p ~/.claude/skills
+cp -r /tmp/ai_skills/skills/workpad ~/.claude/skills/
+cp -r /tmp/ai_skills/skills/research-tree ~/.claude/skills/
+```
+
+Project-level (only the current project):
+
+```sh
+mkdir -p .claude/skills
+cp -r /tmp/ai_skills/skills/workpad .claude/skills/
+```
+
+Or symlink instead of copying so the skill stays in sync with the upstream clone:
+
+```sh
+ln -s /tmp/ai_skills/skills/workpad ~/.claude/skills/workpad
+```
+
+A skill is just a directory containing a `SKILL.md` — no further wiring is needed.
+
+## Layout
+
+```
+ai_skills/
+├── .claude-plugin/
+│   ├── plugin.json        # plugin manifest
+│   └── marketplace.json   # marketplace listing
+└── skills/
+    ├── workpad/SKILL.md
+    ├── research-tree/SKILL.md
+    ├── implementation-orchestration/SKILL.md
+    └── markdown-embedded-svg/SKILL.md
+```