mathias
90a58f0b9e
The repo distributes three ways — the Claude Code plugin, the symlinked library for Crush/Pi/OpenCode, and claude.ai, which has no fetch path at all — and treated every skill as belonging to all of them. claude.ai is not a fourth host to mirror: gitea-ci, playwright and web-shot have no shell and no cluster there, so a flat mirror installs skills that can never fire and degrades selection for the ones that can. Every SKILL.md now carries `surfaces:`, defaulting to [claude-code, library]; dream, own-the-task and grill-me add `chat`, matching what is actually installed on claude.ai today. Claude Code accepts the extra key — `claude plugin validate` passes and the skills still load. bin/check-surfaces validates values, not just presence, because the failure mode here is silent: a wrong surface removes a skill from a harness rather than erroring. install.sh links only skills whose surfaces include `library`, and a source that declares nothing at all is treated as foreign and linked as-is — Anthropic's official set has no reason to know this convention. doctor's missing-link check skips non-library skills for the same reason. Refs #29 Bump-Type: minor
233 lines
8.7 KiB
Bash
Executable File
233 lines
8.7 KiB
Bash
Executable File
#!/usr/bin/env bash
|
|
# install.sh — bootstrap installer for the skills library.
|
|
#
|
|
# Usage (one-liner, hosts without Task):
|
|
# curl -fsSL https://git.d-ma.be/mathias/skills/raw/branch/main/install.sh | bash
|
|
#
|
|
# Pinned to a specific tag:
|
|
# SKILLS_REF=v0.4.0 bash install.sh
|
|
#
|
|
# Idempotent: re-running pulls the latest changes for the configured ref
|
|
# (default: main) and re-wires the links.
|
|
#
|
|
# Claude Code is NOT wired here. It installs this repo as a plugin from the
|
|
# marketplace this repo also hosts:
|
|
#
|
|
# /plugin marketplace add https://git.d-ma.be/mathias/skills.git
|
|
# /plugin install skills@mathias
|
|
#
|
|
# That path carries the hooks and MCP server definitions too, which symlinks
|
|
# cannot. This script covers the harnesses with no plugin system: Crush, Pi
|
|
# and OpenCode.
|
|
#
|
|
# Wiring model — one managed directory, one link per harness:
|
|
#
|
|
# ~/.agents/skills/tdd -> $CHECKOUT_DIR/skills/tdd (canonical; Pi reads the dir directly)
|
|
# ~/.agents/skills/xlsx -> $OTHER_SOURCE/xlsx
|
|
# ~/.config/crush/skills -> ~/.agents/skills
|
|
# ~/.config/opencode/skills -> ~/.agents/skills
|
|
#
|
|
# ~/.agents/skills was itself a link to this checkout until #27. That encoded
|
|
# an assumption nobody had stated — that this checkout is the ONLY source of
|
|
# skills on the host — and on flamingo the only way to install this library
|
|
# was to displace Anthropic's official set, which lived in Crush's directory.
|
|
# A real directory of per-skill links serves several sources at once: total
|
|
# links are N + one per harness, still not N x harnesses (#23's actual point).
|
|
#
|
|
# Extra sources come from SKILLS_EXTRA_SOURCES, a colon-separated list of
|
|
# directories each holding <skill>/SKILL.md. The checkout is always first and
|
|
# always wins a name collision — but the collision is logged, never resolved
|
|
# in silence, because quietly picking one is how stale content wins.
|
|
#
|
|
# CHECKOUT_DIR deliberately defaults OUTSIDE any file-synced or
|
|
# cross-platform-shared directory. Do not "fix" it to point into ~/dev: on a
|
|
# fleet whose workspace is shared between macOS (/Users/...) and Linux
|
|
# (/home/...), an absolute link stored there is broken on one side by
|
|
# construction. See mathias/skills#23.
|
|
|
|
set -euo pipefail
|
|
|
|
REPO_URL="${SKILLS_REPO_URL:-https://git.d-ma.be/mathias/skills.git}"
|
|
REF="${SKILLS_REF:-main}"
|
|
CHECKOUT_DIR="${SKILLS_CHECKOUT_DIR:-$HOME/.local/share/skills}"
|
|
AGENTS_DIR="${AGENTS_SKILLS_DIR:-$HOME/.agents/skills}"
|
|
CRUSH_DIR="${CRUSH_SKILLS_DIR:-$HOME/.config/crush/skills}"
|
|
OPENCODE_DIR="${OPENCODE_SKILLS_DIR:-$HOME/.config/opencode/skills}"
|
|
EXTRA_SOURCES="${SKILLS_EXTRA_SOURCES:-}"
|
|
# Recorded beside the managed directory rather than inside it: a stray file in
|
|
# there would look like a skill to every harness reading the dir.
|
|
SOURCES_MANIFEST="$(dirname "$AGENTS_DIR")/$(basename "$AGENTS_DIR")-sources"
|
|
|
|
log() { printf '[skills] %s\n' "$*"; }
|
|
|
|
ensure_checkout() {
|
|
# Wiring an existing working checkout (task install) must not fetch or
|
|
# move HEAD — that would discard in-progress work.
|
|
if [ "${SKILLS_SKIP_FETCH:-}" = "1" ]; then
|
|
[ -d "$CHECKOUT_DIR/skills" ] || { log "no skills/ under $CHECKOUT_DIR"; exit 1; }
|
|
log "using $CHECKOUT_DIR as-is (SKILLS_SKIP_FETCH=1)"
|
|
return
|
|
fi
|
|
if [ -d "$CHECKOUT_DIR/.git" ]; then
|
|
log "updating $CHECKOUT_DIR"
|
|
git -C "$CHECKOUT_DIR" fetch --tags --quiet
|
|
git -C "$CHECKOUT_DIR" checkout --quiet "$REF"
|
|
if git -C "$CHECKOUT_DIR" symbolic-ref -q HEAD >/dev/null; then
|
|
# on a branch — fast-forward
|
|
git -C "$CHECKOUT_DIR" pull --ff-only --quiet
|
|
fi
|
|
else
|
|
log "cloning $REPO_URL into $CHECKOUT_DIR (ref=$REF)"
|
|
mkdir -p "$(dirname "$CHECKOUT_DIR")"
|
|
git clone --quiet "$REPO_URL" "$CHECKOUT_DIR"
|
|
git -C "$CHECKOUT_DIR" checkout --quiet "$REF"
|
|
fi
|
|
}
|
|
|
|
count_skills() {
|
|
find "$CHECKOUT_DIR/skills" -mindepth 2 -maxdepth 2 -name SKILL.md 2>/dev/null | wc -l | tr -d ' '
|
|
}
|
|
|
|
# sources — every configured source directory, primary first, one per line.
|
|
sources() {
|
|
printf '%s\n' "$CHECKOUT_DIR/skills"
|
|
[ -n "$EXTRA_SOURCES" ] || return 0
|
|
# printf '%s\n' deliberately: without the trailing newline `read` hits EOF
|
|
# on the final entry and the loop body never runs for it.
|
|
printf '%s\n' "$EXTRA_SOURCES" | tr ':' '\n' | while IFS= read -r src; do
|
|
[ -n "$src" ] || continue
|
|
if [ -d "$src" ]; then
|
|
printf '%s\n' "$src"
|
|
else
|
|
log "extra source $src does not exist — skipping"
|
|
fi
|
|
done
|
|
}
|
|
|
|
# prepare_agents_dir — the canonical location is a real directory now. A host
|
|
# still on the single-link wiring is migrated in place.
|
|
prepare_agents_dir() {
|
|
if [ -L "$AGENTS_DIR" ]; then
|
|
log "migrating $AGENTS_DIR from the single-link wiring to a per-skill directory"
|
|
rm -f "$AGENTS_DIR"
|
|
elif [ -e "$AGENTS_DIR" ] && [ ! -d "$AGENTS_DIR" ]; then
|
|
log "REFUSING to replace $AGENTS_DIR — it exists and is not a directory"
|
|
return 1
|
|
fi
|
|
mkdir -p "$AGENTS_DIR"
|
|
}
|
|
|
|
# wire_skills — one symlink per skill, from every configured source.
|
|
wire_skills() {
|
|
local src_list desired name src dir link target
|
|
src_list="$(mktemp)"
|
|
sources > "$src_list"
|
|
|
|
desired=""
|
|
while IFS= read -r src; do
|
|
[ -d "$src" ] || continue
|
|
for dir in "$src"/*/; do
|
|
[ -f "$dir/SKILL.md" ] || continue
|
|
name="$(basename "$dir")"
|
|
target="${dir%/}"
|
|
|
|
# A skill declares its surfaces; this installer serves exactly one of
|
|
# them. A chat-only skill linked into Crush can never fire and competes
|
|
# for selection with ones that can (#29). A source with no declaration
|
|
# is foreign — Anthropic's official set has no reason to know this
|
|
# convention — so silence means "link it".
|
|
surfaces="$(sed -n 's/^surfaces:[[:space:]]*//p' "$dir/SKILL.md" | head -1)"
|
|
if [ -n "$surfaces" ] && ! printf '%s' "$surfaces" | tr -d '[]' | tr ',' ' ' | grep -qw library; then
|
|
log "skipping $name — surfaces: $surfaces does not include the library"
|
|
continue
|
|
fi
|
|
|
|
if printf '%s' "$desired" | grep -qx -- "$name"; then
|
|
log "COLLISION: $name is offered by $target too; keeping $AGENTS_DIR/$name -> $(readlink "$AGENTS_DIR/$name" 2>/dev/null || echo '?')"
|
|
continue
|
|
fi
|
|
|
|
link="$AGENTS_DIR/$name"
|
|
if [ -L "$link" ]; then
|
|
if [ "$(readlink "$link")" = "$target" ]; then
|
|
desired="$desired$name
|
|
"
|
|
continue
|
|
fi
|
|
rm -f "$link"
|
|
elif [ -e "$link" ]; then
|
|
log "unmanaged: $link is not a symlink — left in place; move it aside to let $target take the name"
|
|
continue
|
|
fi
|
|
ln -s "$target" "$link"
|
|
desired="$desired$name
|
|
"
|
|
done
|
|
done < "$src_list"
|
|
rm -f "$src_list"
|
|
|
|
# Removing a skill from a source must remove its link, or the previous
|
|
# generation's problem (links resolving to nothing, invisible to git)
|
|
# returns in a new shape.
|
|
for link in "$AGENTS_DIR"/*; do
|
|
[ -e "$link" ] || [ -L "$link" ] || continue
|
|
name="$(basename "$link")"
|
|
if [ ! -L "$link" ]; then
|
|
log "unmanaged: $link is not a symlink and no source offers it — left in place"
|
|
continue
|
|
fi
|
|
printf '%s' "$desired" | grep -qx -- "$name" && continue
|
|
rm -f "$link"
|
|
log "pruned $name — no configured source offers it any more"
|
|
done
|
|
|
|
sources > "$SOURCES_MANIFEST"
|
|
# Reported through a global, not stdout: wire_skills logs collisions and
|
|
# unmanaged entries as it goes, and capturing its stdout for a count would
|
|
# swallow exactly the warnings this change exists to surface.
|
|
LINKED_COUNT=$(printf '%s' "$desired" | grep -c . || true)
|
|
}
|
|
|
|
# link_dir <link_path> <target_path>
|
|
# Replaces whatever is there — including a directory left behind by the old
|
|
# per-skill wiring — with a single symlink.
|
|
link_dir() {
|
|
local link="$1" target="$2"
|
|
if [ -L "$link" ]; then
|
|
[ "$(readlink "$link")" = "$target" ] && return
|
|
rm -f "$link"
|
|
elif [ -d "$link" ]; then
|
|
# Refuse to discard a directory holding anything but symlinks: that
|
|
# would be someone's real skills, not our old wiring.
|
|
if find "$link" -mindepth 1 -maxdepth 1 ! -type l | grep -q .; then
|
|
log "REFUSING to replace $link — it holds non-symlink entries; move them and re-run"
|
|
return 1
|
|
fi
|
|
find "$link" -mindepth 1 -maxdepth 1 -type l -delete
|
|
rmdir "$link"
|
|
elif [ -e "$link" ]; then
|
|
rm -f "$link"
|
|
fi
|
|
mkdir -p "$(dirname "$link")"
|
|
ln -s "$target" "$link"
|
|
log "linked $link → $target"
|
|
}
|
|
|
|
main() {
|
|
ensure_checkout
|
|
|
|
# Canonical location. Pi reads ~/.agents/skills directly, so it needs no
|
|
# harness-specific link of its own.
|
|
prepare_agents_dir
|
|
LINKED_COUNT=0
|
|
wire_skills
|
|
|
|
link_dir "$CRUSH_DIR" "$AGENTS_DIR"
|
|
link_dir "$OPENCODE_DIR" "$AGENTS_DIR"
|
|
|
|
log "done — $LINKED_COUNT skill(s) linked from $(sources | wc -l | tr -d ' ') source(s), ref=$REF"
|
|
log "Claude Code: install the plugin instead — /plugin marketplace add $REPO_URL"
|
|
}
|
|
|
|
main "$@"
|