diff --git a/SKILL.md b/SKILL.md
index ff1fa73..d7cab60 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -1,23 +1,33 @@
 ---
 name: codebase-analysis
 description: >-
-  Analyze open source repositories to extract architectural conventions,
-  patterns, and design decisions. Produces convention docs and pattern
-  files pushed to git repos. Use when asked to "analyze a repo",
-  "extract patterns from", "what conventions does X use", "add X to the
-  analysis repos", "how does X do Y architecturally", or when adding a
-  new project to the conventions collection. Triggers on: codebase
-  analysis, repo analysis, extract conventions, architectural analysis,
-  project conventions, "analyze this repo", "what patterns does X use",
-  "how is X structured". Do NOT use for: code review of specific PRs
-  (use pr-review), security audits (use vuln-scout), or reading a
-  single file for a quick answer.
+  Analyze open source repositories to extract conventions or patterns.
+  Two modes: "conventions" (how a project works architecturally) and
+  "patterns" (how to write idiomatic code in that language/ecosystem).
+  Use when asked to "analyze a repo", "extract patterns from", "what
+  conventions does X use", "how should I write X", "what's idiomatic",
+  "add X to the analysis repos", or "how does X do Y architecturally".
+  Do NOT use for: code review of specific PRs (use pr-review), security
+  audits (use vuln-scout), or reading a single file for a quick answer.
 ---
 
 # Codebase Analysis
 
-Extract architectural conventions from open source repositories.
-Output: convention repos (one per project analyzed).
+Extract conventions or idiomatic patterns from open source repos.
+
+## Mode
+
+Set `MODE` when invoking (or infer from request):
+
+| Mode | Question | Output | Repo suffix |
+|------|----------|--------|-------------|
+| `conventions` | "How does this project work?" | Architecture, governance, unique infra | `*-conventions` |
+| `patterns` | "How should I write code like this?" | Prescriptive rules for users | `*-patterns` |
+
+**Default:** `conventions` unless the request says "idiomatic",
+"how to write", "style guide", or "patterns for users".
+
+**Both modes share Phases 1-7.** They diverge at Phase 8 (synthesis).
 
 ## Configuration
 
@@ -53,8 +63,11 @@ shell environment, or git remote configuration).
 
 ## Naming
 
-- `*-patterns` = language-level (how the language wants you to write)
-- `*-conventions` = project-specific (how a codebase chose to do it)
+- `*-patterns` = prescriptive (how users should write code)
+- `*-conventions` = descriptive (how a specific codebase works)
+
+A language can have both: `go-patterns` (write Go like this) AND
+`golang-conventions` (how the Go team builds Go itself).
 
 ## Thinking Framework
 
@@ -194,7 +207,13 @@ reasoning is pure expert knowledge.
 
 ### Phase 8: Synthesis
 
-Produce two files. Push to `GIT_REMOTE`.
+Produce output based on MODE. Push to `GIT_REMOTE`.
+
+---
+
+#### MODE: conventions
+
+Output: `<project>-conventions` repo.
 
 **`analysis.md`** — the full story:
 1. Repo shape and organizational philosophy
@@ -205,13 +224,54 @@ Produce two files. Push to `GIT_REMOTE`.
 6. Quality metrics in context (not bare numbers)
 
 **`conventions.md`** — the reference:
-For each pattern:
+For each unique pattern:
 - Name and location in source
 - Code example (real, not simplified)
 - When to use / When NOT to use
 - Origin (commit date, author, PR# if available)
 
-End both files with `<!-- PATTERN_COMPLETE -->` sentinel.
+**Tone:** Descriptive. "This project does X because Y."
+
+---
+
+#### MODE: patterns
+
+Output: `<language>-patterns` or `<ecosystem>-patterns` repo.
+
+**Synthesis question:** "What should a developer copy from this
+codebase?" Filter everything through: "If I were writing new code
+in this language/ecosystem, what rules does this source teach me?"
+
+**`patterns/<topic>.md`** — one file per topic area:
+- Error handling patterns
+- Naming conventions
+- Concurrency patterns
+- Testing patterns
+- Interface/protocol design
+- Module organization
+
+Each pattern entry:
+- Name (short, linkable heading)
+- Rule (one sentence: "Do X" or "Never Y")
+- Example (real code from the source, not invented)
+- Why (the force that makes this the right choice)
+- When NOT to use (where the pattern breaks down)
+- Source (file path + line, or commit where it's demonstrated)
+
+**`smells.md`** — anti-patterns found in the source:
+- What it looks like
+- Why it exists (technical debt? deliberate tradeoff?)
+- What to do instead
+
+**Tone:** Prescriptive. "Write it this way because X."
+
+**Key difference from conventions mode:** Skip governance, team
+structure, TODO culture, and project history unless they directly
+inform HOW to write code. Focus on patterns a user should copy.
+
+---
+
+End all output files with `<!-- PATTERN_COMPLETE -->` sentinel.
 
 ## Cross-Ecosystem Observations
 
@@ -258,8 +318,11 @@ See `references/pattern-breaks.md` for real examples with git history.
 
 ## Output Repos
 
-Push to `GIT_REMOTE` under `GIT_ORG/<project>-conventions`. See
-`references/commands.md` for repo creation and push commands.
+Push to `GIT_REMOTE` under:
+- **conventions mode:** `GIT_ORG/<project>-conventions`
+- **patterns mode:** `GIT_ORG/<language>-patterns`
+
+See `references/commands.md` for repo creation and push commands.
 
 ## Fallbacks