From 302ea5592a382d2c0172a69ce97ac5ac1d043fbf Mon Sep 17 00:00:00 2001 From: Matt Bruce Date: Wed, 11 Feb 2026 11:32:41 -0600 Subject: [PATCH] docs: unify skills install path --- Agents.md | 4 ++-- docs/ai/skills.md | 37 +++++++++++++++---------------------- scripts/sync-skills.sh | 37 +++++++++---------------------------- skills.yaml | 7 +++---- 4 files changed, 29 insertions(+), 56 deletions(-) diff --git a/Agents.md b/Agents.md index cac44c3..eac11a8 100644 --- a/Agents.md +++ b/Agents.md @@ -75,8 +75,8 @@ If you update any file in this repo, commit and push right away so other develop ## Skills Sync This repo uses a skills manifest to standardize skills across developers. -1. Review skills.yaml for required skills. -2. Run ./scripts/sync-skills.sh to sync skills locally. +1. Review skills.yaml for the approved install list. +2. Run ./scripts/sync-skills.sh (uses the `npx skills` CLI). 3. Restart your editor if needed. ## Suggested Agent Request Template diff --git a/docs/ai/skills.md b/docs/ai/skills.md index 75850ab..87ad52e 100644 --- a/docs/ai/skills.md +++ b/docs/ai/skills.md @@ -5,8 +5,7 @@ You are here: [AI Docs Home](index.md) > Skills Library ## Contents - Skills vs Agents vs Instructions - Skills Governance And Sync -- skills.sh (Optional Skills Installer) -- skills CLI Commands +- Skills CLI (Single Path) - How To Connect Skills - Central Assets Repo - Next Steps @@ -39,7 +38,7 @@ To keep skills consistent across teams, use a central skills registry plus a per ### Recommended Pattern - Central skills registry repo (single source of truth) - Project-level manifest that pins required skills and versions -- Sync script that pulls the approved set to each developer's laptop +- Sync script that installs the approved set to each developer's laptop - Agents.md points to the manifest and sync command ### Proposed Curated Repo Structure @@ -60,17 +59,16 @@ Use a small manifest to declare the approved skills and versions for the project ```yaml version: 1 -registry: git@:org/mobile-ai-skills.git skills: - name: swiftui-expert-skill - version: 1.2.0 + install: "https://github.com/avdlee/swiftui-agent-skill --skill swiftui-expert-skill" - name: onboarding-cro - version: 1.0.0 + install: "vercel-labs/agent-skills" ``` ### Sync Workflow 1. Run the sync script. -2. The script pulls the registry and copies required skills to your local skills directory. +2. The script installs each skill using the `npx skills` CLI. 3. Restart your editor if required. ### Example Sync Command @@ -78,10 +76,8 @@ skills: ./scripts/sync-skills.sh ``` -## skills.sh (Optional Skills Installer) -skills.sh provides a public skills catalog and a CLI to install skills by name. Use this only if your team allows it and you understand the source of the skills you install. - -If you have a curated repo, treat skills.sh as a discovery tool only. The source of truth should remain your curated lists. +## Skills CLI (Single Path) +We use a single, approved path: update skills.yaml and run the sync script. The sync script calls `npx skills add` for each entry. ### Where To Find Skills - Homepage: https://skills.sh/ @@ -89,21 +85,18 @@ If you have a curated repo, treat skills.sh as a discovery tool only. The source - CLI reference: https://skills.sh/docs/cli ### How It Works (High-Level) -1. You run the `skills` CLI via `npx`. -2. The CLI downloads the skill and configures it for your agent environment. -3. The skill becomes available to your AI agent. +1. You update skills.yaml with the approved install entries. +2. Run ./scripts/sync-skills.sh. +3. The script uses `npx skills` to install each skill. ### Install The CLI (No Global Install Required) The CLI runs via `npx`, so you do not need a global install. -### Example Install Command -```bash -npx skills add vercel-labs/agent-skills -``` - -### Example Install From A Repo URL -```bash -npx skills add https://github.com/avdlee/swiftui-agent-skill --skill swiftui-expert-skill +### Example Install Entry +```yaml +skills: + - name: swiftui-expert-skill + install: "https://github.com/avdlee/swiftui-agent-skill --skill swiftui-expert-skill" ``` ### Notes diff --git a/scripts/sync-skills.sh b/scripts/sync-skills.sh index 7850ad4..c5070f7 100644 --- a/scripts/sync-skills.sh +++ b/scripts/sync-skills.sh @@ -3,42 +3,23 @@ set -euo pipefail ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" MANIFEST="$ROOT_DIR/skills.yaml" -CACHE_DIR="$HOME/.ai-skills/registry" -LOCAL_SKILLS_DIR="$HOME/.ai-skills/skills" if [[ ! -f "$MANIFEST" ]]; then echo "Missing skills manifest: $MANIFEST" >&2 exit 1 fi -REGISTRY_URL="$(grep -E '^registry:' "$MANIFEST" | awk '{print $2}')" -if [[ -z "$REGISTRY_URL" ]]; then - echo "Missing registry in skills.yaml" >&2 +INSTALLS=$(sed -n 's/^[[:space:]]*install:[[:space:]]*//p' "$MANIFEST" | sed 's/^"//;s/"$//') + +if [[ -z "$INSTALLS" ]]; then + echo "No install entries found in skills.yaml" >&2 exit 1 fi -mkdir -p "$CACHE_DIR" "$LOCAL_SKILLS_DIR" - -if [[ -d "$CACHE_DIR/.git" ]]; then - git -C "$CACHE_DIR" pull --ff-only -else - git clone "$REGISTRY_URL" "$CACHE_DIR" -fi - -SKILL_NAMES=$(awk '/^- name:/{print $2}' "$MANIFEST") - -for SKILL in $SKILL_NAMES; do - SRC="$CACHE_DIR/skills/$SKILL" - DEST="$LOCAL_SKILLS_DIR/$SKILL" - - if [[ ! -d "$SRC" ]]; then - echo "Missing skill in registry: $SKILL" >&2 - exit 1 - fi - - rm -rf "$DEST" - cp -R "$SRC" "$DEST" - echo "Synced skill: $SKILL" -done +while IFS= read -r INSTALL; do + [[ -z "$INSTALL" ]] && continue + read -r -a ARGS <<< "$INSTALL" + npx skills add "${ARGS[@]}" +done <<< "$INSTALLS" echo "Done. Restart your editor if skills do not appear." diff --git a/skills.yaml b/skills.yaml index e4e9bd7..ca13003 100644 --- a/skills.yaml +++ b/skills.yaml @@ -1,9 +1,8 @@ version: 1 -registry: git@:org/mobile-ai-skills.git skills: - name: swiftui-expert-skill - version: 1.2.0 + install: "https://github.com/avdlee/swiftui-agent-skill --skill swiftui-expert-skill" - name: onboarding-cro - version: 1.0.0 + install: "vercel-labs/agent-skills" - name: webapp-testing - version: 1.0.0 + install: "vercel-labs/agent-skills"