updated defintion

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.