packages/mosaic/framework/skills/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