Signed-off-by: Matt Bruce <matt.bruce1@toyota.com>

Signed-off-by: Matt Bruce <matt.bruce1@toyota.com>

Agents.md

@@ -1,9 +1,58 @@
 # Agents
 
 ## Purpose
-This file defines how to use agent-style workflows in this project so tasks are clear, scoped, and repeatable.
+This file defines how to use agent-style workflows and skills in this project, so tasks are clear, scoped, and repeatable.
 It is internal guidance for the assistant, not reader-facing documentation.
 
+## What Are Agents vs Skills?
+
+**Short answer:**
+
+- **Skills** = reusable tools or playbooks the AI can call when needed. Like a toolbox for a generalist.
+- **Custom agents** (your /assets/agents/ folders) = specialized AI teammates with their own personality, expertise, and decision-making style. Like building a team of experts.
+
+You can get pretty far with just the default agent (the generalist one) + skills, but custom agents unlock a completely different level: turning one smart generalist into a full specialized team.
+
+### Why people actually create and use custom agents
+
+Here’s what changes in practice:
+
+**True specialization & expertise**
+- A default agent + “use the React skill” still thinks like a generalist.
+- A custom @react-architect agent has deep, baked-in knowledge (your exact component patterns, state management preferences, accessibility rules, performance gotchas). It doesn’t forget or need reminding.
+
+**Different thinking styles / risk levels**
+- @rapid-prototype agent → fast, experimental, okay with temporary hacks
+- @production-safety agent → extremely conservative, asks for confirmation on big changes, always checks security/performance first
+- @security-auditor agent → thinks about threats, OWASP, secrets scanning before writing a single line
+You can’t get this reliably just by prompting the default agent every time.
+
+**Multi-agent orchestration (the real 2026 power move)**
+Tools like Windsurf Cascade, Claude Code Subagents, VS Code Agents, RooCode, Cline, and even Cursor (via agent handoffs) let agents delegate to each other:
+Planner Agent → Backend Agent → Frontend Agent → Tester Agent → Reviewer Agent
+This is way smoother and more reliable than one default agent trying to do everything.
+
+**Convenient UX**
+You just type @security review this or switch to the agent in the sidebar. No long prompt every session.
+
+**Consistency across sessions & team members**
+The custom agent always behaves the same way. No “mood” variation like the default agent sometimes has.
+
+**Curated tool/skill usage**
+You can restrict or prioritize certain skills for that agent only (e.g. the security agent only gets vulnerability-scanning skills and is blocked from deploying).
+
+**Real-world analogy**
+
+Default agent + skills = One extremely capable senior developer with a huge toolbox. You still have to guide them a lot.
+Custom agents = You built a small specialized team (architect, frontend wizard, security lead, QA expert). You just assign the right person to the task.
+
+Most power users and big teams in 2026 do both:
+
+- A rich library of skills (your /assets/skills/)
+- Several custom agents (your /assets/agents/) that know exactly which skills to use and how.
+
+That’s exactly why having separate /agents/ and /skills/ folders in your repo is such a smart setup.
+
 ## Audience And Tone Rules
 Assume the reader is new to AI and needs detailed, step-by-step guidance.
 

assets/README.md

@@ -4,6 +4,8 @@ One script installs everything. No cloning or manual copy/paste required.
 
 ## Quick Start
 
+> For more on discovering and installing skills, see [docs/ai/skills.md](../docs/ai/skills.md).
+
 ### Cloned Repo
 
 ```bash

assets/setup.sh

@@ -17,10 +17,10 @@ VERSION="2.1.0"
 
 # ── Configuration (override with env vars) ───────────────────────────
 # Default paths use ~/.agents/ — the tool-agnostic directory.
-# The npx skills CLI copies into tool-specific dirs (~/.copilot/,
+# AGENTS_DIR now defaults to ~/.agents (not ~/.agents/agents) so agent loaders (e.g., VS Code Copilot Chat) can find them.
-# ~/.claude/, ~/.cursor/) automatically.
+# The npx skills CLI copies into tool-specific dirs (~/.copilot/, ~/.claude/, ~/.cursor/) automatically.
 ASSETS_BASE_URL="${ASSETS_BASE_URL:-}"
-AGENTS_DIR="${AGENTS_DIR:-$HOME/.agents/agents}"
+AGENTS_DIR="${AGENTS_DIR:-$HOME/.agents}"
 SKILLS_DIR="${SKILLS_DIR:-$HOME/.agents/skills}"
 INSTRUCTIONS_DIR="${INSTRUCTIONS_DIR:-./instructions}"
 REPO_TOKEN="${REPO_TOKEN:-}"
@@ -261,6 +261,7 @@ cmd_agents() {
   done <<< "$files"
 
   ok "$count agent(s) installed."
+  echo "\n${YELLOW}NOTE:${NC} Agent files are now installed directly in $AGENTS_DIR for compatibility with agent loaders."
 }
 
 # -- instructions ─────────────────────────────────────────────────────
@@ -337,7 +338,7 @@ ${BOLD}EXAMPLES${NC}
 
 ${BOLD}ENVIRONMENT VARIABLES${NC}
   ASSETS_BASE_URL      Base URL for remote downloads (required without clone)
-  AGENTS_DIR           Install location for agents       (default: ~/.agents/agents)
+  AGENTS_DIR           Install location for agents       (default: ~/.agents)
   SKILLS_DIR           Install location for custom skills (default: ~/.agents/skills)
   INSTRUCTIONS_DIR     Install location for instructions (default: ./instructions)
   REPO_TOKEN           Auth token for private repos      (optional)

docs/ai/index.md

@@ -9,6 +9,7 @@ You are here: AI Docs Home
     - [VS Code Initial Setup](vscode-setup.md)
     - [iOS Setup](ios/ios.md)
     - [Android Setup](android/android.md)
+    - [Skills Library](skills.md)
 - Use AI Day-To-Day
 - Safety And Cost
 ## How To Use This Guide

docs/ai/skills.md

@@ -3,17 +3,75 @@
 You are here: [AI Docs Home](index.md) > Skills Library
 
 ## Contents
-- Skills vs Agents vs Instructions
+
-- Skills Governance And Sync
+## Discover More Skills
-- Skills CLI (Single Path)
+
-- How To Connect Skills
+You can browse and discover additional skills at [https://skills.sh/](https://skills.sh/).
-- Central Assets Repo
+
-- Next Steps
+To install the global Skills CLI for managing and installing skills from the registry, run:
+
+```sh
+npm install -g skills
+```
+
+Once installed, you can search and add skills with commands like:
+
+```sh
+skills search swift
+skills install swiftui-modern
+```
+
+See the [skills.sh documentation](https://skills.sh/docs) for more details.
 
 ## Skills vs Agents vs Instructions
-- Skills are reusable workflows you load for specific tasks.
+
-- Agents are full modes/personas that control behavior end-to-end.
+**Short answer:**
-- Instructions are always-on repo rules that auto-apply by file pattern.
+
+- **Skills** = reusable tools or playbooks the AI can call when needed. Like a toolbox for a generalist.
+- **Custom agents** (your /assets/agents/ folders) = specialized AI teammates with their own personality, expertise, and decision-making style. Like building a team of experts.
+- **Instructions** = always-on repo rules that auto-apply by file pattern.
+
+You can get pretty far with just the default agent (the generalist one) + skills, but custom agents unlock a completely different level: turning one smart generalist into a full specialized team.
+
+### Why people actually create and use custom agents
+
+Here’s what changes in practice:
+
+**True specialization & expertise**
+- A default agent + “use the React skill” still thinks like a generalist.
+- A custom @react-architect agent has deep, baked-in knowledge (your exact component patterns, state management preferences, accessibility rules, performance gotchas). It doesn’t forget or need reminding.
+
+**Different thinking styles / risk levels**
+- @rapid-prototype agent → fast, experimental, okay with temporary hacks
+- @production-safety agent → extremely conservative, asks for confirmation on big changes, always checks security/performance first
+- @security-auditor agent → thinks about threats, OWASP, secrets scanning before writing a single line
+You can’t get this reliably just by prompting the default agent every time.
+
+**Multi-agent orchestration (the real 2026 power move)**
+Tools like Windsurf Cascade, Claude Code Subagents, VS Code Agents, RooCode, Cline, and even Cursor (via agent handoffs) let agents delegate to each other:
+Planner Agent → Backend Agent → Frontend Agent → Tester Agent → Reviewer Agent
+This is way smoother and more reliable than one default agent trying to do everything.
+
+**Convenient UX**
+You just type @security review this or switch to the agent in the sidebar. No long prompt every session.
+
+**Consistency across sessions & team members**
+The custom agent always behaves the same way. No “mood” variation like the default agent sometimes has.
+
+**Curated tool/skill usage**
+You can restrict or prioritize certain skills for that agent only (e.g. the security agent only gets vulnerability-scanning skills and is blocked from deploying).
+
+**Real-world analogy**
+
+Default agent + skills = One extremely capable senior developer with a huge toolbox. You still have to guide them a lot.
+Custom agents = You built a small specialized team (architect, frontend wizard, security lead, QA expert). You just assign the right person to the task.
+
+Most power users and big teams in 2026 do both:
+
+- A rich library of skills (your /assets/skills/)
+- Several custom agents (your /assets/agents/) that know exactly which skills to use and how.
+
+That’s exactly why having separate /agents/ and /skills/ folders in your repo is such a smart setup.
 
 ## What Skills Are
 Skills are reusable instructions and workflows that guide the assistant through specialized tasks.