From 5d7ff301bb0fbea1af135ac49572d4125986ec91 Mon Sep 17 00:00:00 2001
From: Matt Bruce <matt.bruce1@toyota.com>
Date: Tue, 10 Feb 2026 14:08:36 -0600
Subject: [PATCH] chore: add skills sync

---
 Agents.md              | 12 +++++++++++-
 docs/ai/skills.md      | 27 ++++++++++++++++++++++++++
 scripts/sync-skills.sh | 44 ++++++++++++++++++++++++++++++++++++++++++
 skills.yaml            |  9 +++++++++
 4 files changed, 91 insertions(+), 1 deletion(-)
 create mode 100644 scripts/sync-skills.sh
 create mode 100644 skills.yaml

diff --git a/Agents.md b/Agents.md
index 4a36e71..a9aac40 100644
--- a/Agents.md
+++ b/Agents.md
@@ -3,6 +3,9 @@
 ## Purpose
 This file defines how to use agent-style workflows in this project so tasks are clear, scoped, and repeatable.
 
+## Sync Expectation
+Keep this file aligned with PRD and README when workflows, scope, or structure change.
+
 ## When to Use Agents
 - Multi-step changes across files.
 - Refactors with clear acceptance criteria.
@@ -19,6 +22,13 @@ This file defines how to use agent-style workflows in this project so tasks are
 3. Ask for a plan, then approve before edits.
 4. Ask for focused changes and verification steps.
 
+## 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.
+3. Restart your editor if needed.
+
 ## Suggested Agent Request Template
 - Goal: (one sentence)
 - Inputs: (files, context, constraints)
@@ -27,6 +37,6 @@ This file defines how to use agent-style workflows in this project so tasks are
 
 ## Example
 Goal: Add a troubleshooting section to the AI docs.
-Inputs: docs/ai/troubleshooting.md, AI-Docs-Plan.md
+Inputs: docs/ai/troubleshooting.md, docs/planning/AI-Docs-Plan.md
 Output: Updated troubleshooting section with 5 common issues.
 Verification: Manual review.
diff --git a/docs/ai/skills.md b/docs/ai/skills.md
index 25b33b0..f7121d1 100644
--- a/docs/ai/skills.md
+++ b/docs/ai/skills.md
@@ -11,6 +11,33 @@ Skills are reusable instructions and workflows that guide the assistant through
 ## Skills Directory
 Store skills in the team-approved skills directory for your environment. If you do not know the location, ask your team lead or check your internal setup docs.
 
+## Skills Governance And Sync
+To keep skills consistent across teams, use a central skills registry plus a per-project manifest. Avoid copying skills into every repo unless the skill is tightly coupled to the project.
+
+### 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
+- Agents.md points to the manifest and sync command
+
+### Project Manifest Example
+Use a small manifest to declare the approved skills and versions for the project:
+
+```yaml
+version: 1
+registry: git@<host>:org/mobile-ai-skills.git
+skills:
+	- name: swiftui-expert-skill
+		version: 1.2.0
+	- name: onboarding-cro
+		version: 1.0.0
+```
+
+### Sync Workflow
+1. Run the sync script.
+2. The script pulls the registry and copies required skills to your local skills directory.
+3. Restart your editor if required.
+
 ## How to Download Existing Skills
 1. Locate the skill in the team or org repository.
 2. Add the skill to your local skills directory following team guidance.
diff --git a/scripts/sync-skills.sh b/scripts/sync-skills.sh
new file mode 100644
index 0000000..7850ad4
--- /dev/null
+++ b/scripts/sync-skills.sh
@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+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
+  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
+
+echo "Done. Restart your editor if skills do not appear."
diff --git a/skills.yaml b/skills.yaml
new file mode 100644
index 0000000..e4e9bd7
--- /dev/null
+++ b/skills.yaml
@@ -0,0 +1,9 @@
+version: 1
+registry: git@<host>:org/mobile-ai-skills.git
+skills:
+  - name: swiftui-expert-skill
+    version: 1.2.0
+  - name: onboarding-cro
+    version: 1.0.0
+  - name: webapp-testing
+    version: 1.0.0