From 72d625a557b807f18d04830607895d15aa8fad13 Mon Sep 17 00:00:00 2001
From: Nico Ritschel <ritschel@gmail.com>
Date: Sat, 21 Feb 2026 12:57:56 -0800
Subject: [PATCH] Add agent skill with install script and documentation

Introduces the sidemantic-modeler skill for Claude Code and compatible agents.
Includes a one-liner installer script and install instructions for both curl and npx/bunx methods.
---
 README.md         | 20 ++++++++++++++++++++
 skills/install.sh | 37 +++++++++++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+)
 create mode 100755 skills/install.sh

diff --git a/README.md b/README.md
index 32caa2de..e63d832f 100644
--- a/README.md
+++ b/README.md
@@ -9,6 +9,26 @@ A universal metrics layer for consistent metrics across your data stack. Compati
 
 ![Jupyter Widget Preview](preview.png)
 
+## Agent Skill
+
+Sidemantic ships an [agent skill](skills/sidemantic-modeler/) that teaches Claude Code, Codex, and other `SKILL.md`-compatible agents to build, validate, and query semantic models.
+
+**One-liner install (no clone required):**
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/sidequery/sidemantic/main/skills/install.sh | bash
+```
+
+**npx / bunx:**
+
+```bash
+npx skills add https://github.com/sidequery/sidemantic --skill sidemantic-modeler
+# or
+bunx skills add https://github.com/sidequery/sidemantic --skill sidemantic-modeler
+```
+
+The installer downloads the skill to `~/.agents/skills/sidemantic-modeler` and symlinks it into `~/.claude/skills/`.
+
 ## How mature is Sidemantic?
 
 Sidemantic is a very ambitious and young semantic layer project. You may encounter rough patches, especially with the more exotic features like converting between semantic model formats or serving semantic layers via the included Postgres protocol server.
diff --git a/skills/install.sh b/skills/install.sh
new file mode 100755
index 00000000..153b660d
--- /dev/null
+++ b/skills/install.sh
@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SKILL_NAME="sidemantic-modeler"
+REPO="sidequery/sidemantic"
+BRANCH="main"
+REMOTE_DIR="skills/$SKILL_NAME"
+BASE_URL="https://raw.githubusercontent.com/$REPO/$BRANCH/$REMOTE_DIR"
+
+AGENTS_DIR="$HOME/.agents/skills/$SKILL_NAME"
+CLAUDE_DIR="$HOME/.claude/skills/$SKILL_NAME"
+
+echo "Installing $SKILL_NAME skill..."
+
+# Create target directory
+mkdir -p "$AGENTS_DIR/references"
+
+# Download SKILL.md and reference files
+curl -fsSL "$BASE_URL/SKILL.md" -o "$AGENTS_DIR/SKILL.md"
+for ref in generation.md migration.md patterns.md validation.md yaml-schema.md; do
+  curl -fsSL "$BASE_URL/references/$ref" -o "$AGENTS_DIR/references/$ref"
+done
+
+# Symlink into Claude skills
+mkdir -p "$HOME/.claude/skills"
+if [ -L "$CLAUDE_DIR" ]; then
+  rm "$CLAUDE_DIR"
+elif [ -d "$CLAUDE_DIR" ]; then
+  echo "Warning: $CLAUDE_DIR exists and is not a symlink. Skipping symlink creation."
+  echo "Skill files installed to $AGENTS_DIR"
+  exit 0
+fi
+ln -s "$AGENTS_DIR" "$CLAUDE_DIR"
+
+echo "Installed to $AGENTS_DIR"
+echo "Symlinked to $CLAUDE_DIR"
+echo "Done. The skill is now available in Claude Code and compatible agents."