diff --git a/README.md b/README.md
index 5e32093..03518aa 100644
--- a/README.md
+++ b/README.md
@@ -7,6 +7,135 @@ Every skill is pinned in `skills-lock.json` for reproducible installs.
 First-party skills live under `skills/` and are layered on top of the locked ones at install time.
 Compatible with Claude Code, Codex, Gemini CLI, Cursor, Copilot, Windsurf, Cline, and other agents.
 
+## Skill map 🗺️
+
+How the first-party skills work together. A solid arrow means the skill invokes or relies on the other one; a dotted arrow means it fires automatically. Every skill that reports a result closes with the `confidence` block; those arrows are left out. The locked third-party skills (caveman, ponytail, archify) are not drawn.
+
+```mermaid
+flowchart LR
+  subgraph triggers [Triggers]
+    commit_req([commit request])
+    stage_req([staging or fix ready])
+    edit_hook([edit in a git worktree])
+    reminders([reminder hooks])
+    code_task([code task])
+  end
+  subgraph commit [Commit]
+    commit_next[commit-next]
+    commit_no_verify[commit-no-verify]
+    comments_clean[comments-clean]
+    advocate[advocate]
+    confidence[confidence]
+    break_risk[break-risk]
+    explain[explain]
+  end
+  subgraph coordination [Coordination]
+    democracy[democracy]
+    coordinate[coordinate]
+    funnel[funnel]
+    cleanup[cleanup]
+  end
+  subgraph ci [CI]
+    observe[observe]
+    triage[triage]
+    ci_artifacts[ci-artifacts]
+    tune[tune]
+    merge_fix[merge-fix]
+  end
+  subgraph reasoning [Reasoning]
+    active_listening[active-listening]
+    dialectic[dialectic]
+    criticize[criticize]
+    sceptic[sceptic]
+    auto_feature[auto-feature]
+  end
+  subgraph autonomy [Autonomy]
+    plan[plan]
+    robot[robot]
+  end
+  subgraph self_improvement [Self-improvement]
+    dream[dream]
+    autotune[autotune]
+    autoskill[autoskill]
+    essence[essence]
+    shortcuts[shortcuts]
+  end
+  subgraph quality [Quality]
+    test[test]
+    refactor[refactor]
+    no_defaults[no-defaults]
+    scope_guard[scope-guard]
+  end
+  subgraph standalone [Standalone]
+    changelog[changelog]
+    help_skills[help-skills]
+    status_matrix[status-matrix]
+    medusa[medusa]
+  end
+
+  commit_req -.-> commit_next
+  commit_req -.-> commit_no_verify
+  stage_req -.-> confidence
+  edit_hook -. council gate .-> democracy
+  reminders -.-> dream
+  reminders -.-> autotune
+  code_task -.-> no_defaults
+  code_task -.-> scope_guard
+
+  commit_next --> merge_fix
+  commit_next --> commit_no_verify
+  commit_next --> explain
+  commit_next --> dialectic
+  commit_no_verify --> comments_clean
+  commit_no_verify --> advocate
+  advocate --> dialectic
+  confidence --> break_risk
+  confidence -. objective .-> autotune
+
+  coordinate --> democracy
+  cleanup --> democracy
+  funnel --> democracy
+  funnel --> dialectic
+  democracy --> merge_fix
+
+  observe --> triage
+  observe --> ci_artifacts
+  triage --> ci_artifacts
+  triage --> democracy
+  triage --> dialectic
+  triage --> funnel
+  triage --> tune
+  tune --> democracy
+  tune --> funnel
+  tune --> merge_fix
+  tune --> dialectic
+
+  dialectic --> active_listening
+  criticize --> dialectic
+  criticize --> active_listening
+  sceptic --> dialectic
+  sceptic --> no_defaults
+  auto_feature --> sceptic
+  auto_feature --> active_listening
+
+  plan --> robot
+  plan --> active_listening
+  robot --> dialectic
+
+  dream --> dialectic
+  dream --> autotune
+  dream --> autoskill
+  autoskill --> autotune
+  autoskill --> shortcuts
+  autotune --> essence
+
+  test --> triage
+  test --> dialectic
+  test --> no_defaults
+  test --> comments_clean
+  refactor --> comments_clean
+```
+
 ## Requirements 📦
 
 - Node.js (provides `npx skills`).