diff --git a/src/resources/skills/create-skill/references/sf-skill-ecosystem.md b/src/resources/skills/create-skill/references/sf-skill-ecosystem.md
index 70bcee996..0ca90a8bb 100644
--- a/src/resources/skills/create-skill/references/sf-skill-ecosystem.md
+++ b/src/resources/skills/create-skill/references/sf-skill-ecosystem.md
@@ -3,28 +3,29 @@ SF-specific skill ecosystem details: directory conventions, discovery mechanics,
 </overview>
 
 <skill_directories>
-SF supports two skill directories, checked in order:
+SF discovers skills from four directories — two user-scope, two project-scope — covering both the industry-standard `.agents/` ecosystem and Claude Code's `.claude/` convention:
 
-**User-scope (global):** `~/.sf/agent/skills/`
-- Available in every SF session regardless of working directory
-- Installed by default or by the user
+**User-scope (global):**
+- `~/.agents/skills/` — industry-standard ecosystem path (skills.sh and similar registries install here)
+- `~/.claude/skills/` — Claude Code's official skills directory
+Available in every SF session regardless of working directory.
 
-**Project-scope (local):** `.pi/agent/skills/`
-- Available only when SF runs inside the project directory
-- The project-local directory uses `.pi` (inherited from the pi base), **not** `.sf`
-- Ideal for project-specific workflows, deploy scripts, or conventions
+**Project-scope (local):**
+- `<project>/.agents/skills/` — project-scoped industry-standard
+- `<project>/.claude/skills/` — project-scoped Claude Code skills
+Available only when SF runs inside the project directory. Ideal for project-specific workflows, deploy scripts, or conventions.
 
-Skills in both directories follow the same SKILL.md format and router pattern conventions.
+Skills in any of the four directories follow the same SKILL.md format and router pattern conventions. SF does NOT use `~/.sf/agent/skills/` or `.pi/agent/skills/` for skill discovery — those paths are inactive.
 </skill_directories>
 
 <skill_discovery>
 SF auto-discovers skills at session start and during auto-mode:
 
-**Session start:** All skills in both directories are enumerated and their names + descriptions are injected into the system prompt as `<available_skills>`.
+**Session start:** Skills in all four directories are enumerated and their names + descriptions are injected into the system prompt as `<available_skills>`.
 
-**Auto-mode discovery:** `skill-discovery.ts` takes a snapshot of the skills directory at auto-mode start. On each unit boundary it diffs against the snapshot. Any new skills found are injected via a `<newly_discovered_skills>` XML block so the LLM sees them without requiring `/reload`.
+**Auto-mode discovery:** `skill-discovery.ts` takes a snapshot of the skills directories at auto-mode start. On each unit boundary it diffs against the snapshot. Any new skills found are injected via a `<newly_discovered_skills>` XML block so the LLM sees them without requiring `/reload`.
 
-**Manual reload:** Running `/reload` re-scans both directories and updates the available skills list mid-session.
+**Manual reload:** Running `/reload` re-scans all four directories and updates the available skills list mid-session.
 </skill_discovery>
 
 <skill_validation>
@@ -42,7 +43,7 @@ Skill metadata has validation constraints:
 - **Staleness detection:** Skills unused for 60+ days are flagged as stale
 - **Pass/fail rates:** Derived from unit completion status when a skill is active
 
-Telemetry data is stored in `~/.sf/metrics.json` alongside other SF metrics.
+Telemetry data is stored per-project in `<project>/.sf/metrics.json` alongside other SF metrics.
 </skill_telemetry>
 
 <skill_health>
@@ -56,7 +57,7 @@ Telemetry data is stored in `~/.sf/metrics.json` alongside other SF metrics.
   - Rising token trend → flagged (may indicate skill drift or bloat)
   - 60+ days stale → flagged
 
-The `/doctor` command surfaces skill health issues alongside other system diagnostics.
+The `/sf doctor` command surfaces skill health issues alongside other system diagnostics.
 </skill_health>
 
 <activation>