diff --git a/docs/ai/skills.md b/docs/ai/skills.md
index 50d0860..3acfa93 100644
--- a/docs/ai/skills.md
+++ b/docs/ai/skills.md
@@ -11,9 +11,54 @@ You are here: [AI Docs Home](index.md) > Skills Library
 - Next Steps
 
 ## 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.
-- Instructions are always-on repo rules that auto-apply by file pattern.
+
+**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.
+- **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.