From b794d0ad6bba77680e7c6acc53510d2516cb3051 Mon Sep 17 00:00:00 2001
From: Jason Woltje <jason.woltje@uscllc.com>
Date: Mon, 16 Feb 2026 16:09:05 -0600
Subject: [PATCH] docs: Add npx install commands and clone instructions

- Add npx skills add commands for single, all, and non-interactive install
- Document .git suffix requirement for Gitea-hosted repos
- Add git clone step to manual installation
- Use ln -sf for idempotent symlinks

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 README.md | 30 +++++++++++++++++++++++++-----
 1 file changed, 25 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index ed6a953..ea7b472 100644
--- a/README.md
+++ b/README.md
@@ -13,14 +13,34 @@ Custom agent skills for Mosaic Stack and USC projects. Platform-aware — works
 
 ## Installation
 
-### Manual (symlink into Claude Code)
+### Via npx (recommended)
+
+Install individual skills into any agent:
 
 ```bash
+# Install a single skill
+npx skills add https://git.mosaicstack.dev/mosaic/agent-skills.git --skill pr-reviewer --agent claude-code
+
+# Install all skills
+npx skills add https://git.mosaicstack.dev/mosaic/agent-skills.git --agent claude-code
+
+# Non-interactive (CI/scripting)
+npx skills add https://git.mosaicstack.dev/mosaic/agent-skills.git --skill pr-reviewer --yes --agent claude-code
+```
+
+**Note:** The `.git` suffix on the URL is required for Gitea-hosted repos (forces git clone instead of well-known endpoint discovery).
+
+### Manual (symlink from local clone)
+
+```bash
+# Clone the repo
+git clone https://git.mosaicstack.dev/mosaic/agent-skills.git ~/src/agent-skills
+
 # Symlink individual skills
-ln -s ~/src/agent-skills/skills/pr-reviewer ~/.claude/skills/pr-reviewer
-ln -s ~/src/agent-skills/skills/code-review-excellence ~/.claude/skills/code-review-excellence
-ln -s ~/src/agent-skills/skills/vercel-react-best-practices ~/.claude/skills/vercel-react-best-practices
-ln -s ~/src/agent-skills/skills/tailwind-design-system ~/.claude/skills/tailwind-design-system
+ln -sf ~/src/agent-skills/skills/pr-reviewer ~/.claude/skills/pr-reviewer
+ln -sf ~/src/agent-skills/skills/code-review-excellence ~/.claude/skills/code-review-excellence
+ln -sf ~/src/agent-skills/skills/vercel-react-best-practices ~/.claude/skills/vercel-react-best-practices
+ln -sf ~/src/agent-skills/skills/tailwind-design-system ~/.claude/skills/tailwind-design-system
 ```
 
 ### Per-Project