Agents.md

@@ -1,58 +1,9 @@
 # Agents
 
 ## Purpose
-This file defines how to use agent-style workflows and skills in this project, so tasks are clear, scoped, and repeatable.
+This file defines how to use agent-style workflows 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,8 +4,6 @@ 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.
-# AGENTS_DIR now defaults to ~/.agents (not ~/.agents/agents) so agent loaders (e.g., VS Code Copilot Chat) can find them.
-# The npx skills CLI copies into tool-specific dirs (~/.copilot/, ~/.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_DIR="${AGENTS_DIR:-$HOME/.agents/agents}"
 SKILLS_DIR="${SKILLS_DIR:-$HOME/.agents/skills}"
 INSTRUCTIONS_DIR="${INSTRUCTIONS_DIR:-./instructions}"
 REPO_TOKEN="${REPO_TOKEN:-}"
@@ -261,7 +261,6 @@ 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 ─────────────────────────────────────────────────────
@@ -338,7 +337,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_DIR           Install location for agents       (default: ~/.agents/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,7 +9,6 @@ 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,75 +3,17 @@
 You are here: [AI Docs Home](index.md) > Skills Library
 
 ## Contents
-
-## Discover More Skills
-
-You can browse and discover additional skills at [https://skills.sh/](https://skills.sh/).
-
-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 Governance And Sync
+- Skills CLI (Single Path)
+- How To Connect Skills
+- Central Assets Repo
+- Next Steps
 
 ## Skills vs Agents vs Instructions
-
-**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.
+- 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.
 
 ## What Skills Are
 Skills are reusable instructions and workflows that guide the assistant through specialized tasks.