rohitg00 · rohitg00 · Feb 4, 2026 · Feb 4, 2026
diff --git a/README.md b/README.md
@@ -106,7 +106,7 @@ After plugin install, commands are namespaced:
 | `/pro-workflow:wrap-up` | End-of-session checklist |
 | `/pro-workflow:learn-rule` | Extract correction to memory (file-based) |
 | `/pro-workflow:parallel` | Worktree setup guide |
-| `/pro-workflow:learn` | **NEW** Save learning to SQLite database |
+| `/pro-workflow:learn` | **NEW** Claude Code best practices & save learnings |
 | `/pro-workflow:search` | **NEW** Search learnings by keyword |
 | `/pro-workflow:list` | **NEW** List all stored learnings |
 
@@ -139,6 +139,8 @@ Learnings are stored in SQLite with FTS5 full-text search:
 - Context (when to clarify)
 - Architecture (design decisions)
 - Performance (optimization)
+- Claude-Code (sessions, modes, CLAUDE.md, skills, subagents, hooks, MCP)
+- Prompting (scope, constraints, acceptance criteria)
 
 ## Hooks
 
@@ -185,7 +187,7 @@ pro-workflow/
 │   ├── plugin.json           # Plugin manifest
 │   ├── marketplace.json      # Marketplace config
 │   └── README.md
-├── src/                      # TypeScript source (NEW)
+├── src/                      # TypeScript source
 │   ├── db/
 │   │   ├── index.ts          # Database initialization
 │   │   ├── store.ts          # Stateless store factory
@@ -198,29 +200,45 @@ pro-workflow/
 │   └── pro-workflow/
 │       └── SKILL.md          # Main skill
 ├── agents/
-│   ├── planner.md
-│   └── reviewer.md
+│   ├── planner.md            # Planner agent
+│   └── reviewer.md           # Reviewer agent
 ├── commands/
-│   ├── wrap-up.md
-│   ├── learn-rule.md
-│   ├── parallel.md
-│   ├── learn.md              # NEW
-│   ├── search.md             # NEW
-│   └── list.md               # NEW
+│   ├── wrap-up.md # Wrap-up command
+│   ├── learn-rule.md # Learn rule command
+│   ├── parallel.md # Parallel command
+│   ├── learn.md
+│   ├── search.md # Search command
+│   └── list.md # List command
 ├── hooks/
-│   └── hooks.json
+│   └── hooks.json # Hooks file
 ├── scripts/                  # Hook scripts
 ├── contexts/
-│   ├── dev.md
-│   ├── review.md
-│   └── research.md
+│   ├── dev.md # Dev context
+│   ├── review.md # Review context
+│   └── research.md # Research context
+├── references/
+│   └── claude-code-resources.md # Claude code resources reference file
 ├── rules/
-│   └── core-rules.md
+│   └── core-rules.md # Core rules file
 ├── templates/
-│   └── split-claude-md/
-├── package.json              # NEW
-├── tsconfig.json             # NEW
-└── README.md
+│   └── split-claude-md/ # Split claude md template
+├── package.json
+├── tsconfig.json # TypeScript configuration file
+└── README.md # README file
+```
+
+## Learn Claude Code
+
+Pro-workflow teaches Claude Code best practices directly, with links to official documentation for deep dives.
+
+**Official Docs:** https://code.claude.com/docs/
+
+Topics covered: sessions, context management, modes, CLAUDE.md, prompting, writing rules, skills, subagents, hooks, MCP, security, and IDE integration.
+
+```
+/pro-workflow:learn                 # Best practices guide & save learnings
+/pro-workflow:learn-rule            # Capture corrections to memory
+/pro-workflow:search claude-code    # Find past Claude Code learnings
 ```
 
 ## SkillKit - Universal AI Skills

diff --git a/commands/learn-rule.md b/commands/learn-rule.md
@@ -20,6 +20,10 @@ Capture a lesson from this session into permanent memory.
    - Git (commits, branches)
    - Quality (lint, types, style)
    - Context (when to clarify)
+   - Architecture (design decisions)
+   - Performance (optimization)
+   - Claude-Code (sessions, modes, CLAUDE.md, skills, subagents, hooks, MCP)
+   - Prompting (scope, constraints, acceptance criteria)
 
 3. **Propose addition**
    Show what will be added to LEARNED section.
@@ -39,4 +43,18 @@ Add to LEARNED section? (y/n)
 
 ---
 
+## Claude Code Examples
+
+```
+[LEARN] Claude-Code: Use plan mode before multi-file changes.
+Docs: https://code.claude.com/docs/common-workflows
+
+[LEARN] Claude-Code: Compact context at task boundaries, not mid-work.
+Docs: https://code.claude.com/docs/common-workflows
+
+[LEARN] Prompting: Always include acceptance criteria in prompts.
+```
+
+---
+
 **Trigger:** Use when user says "remember this", "add to rules", or after making a mistake.
diff --git a/commands/learn.md b/commands/learn.md
@@ -1,50 +1,147 @@
-# /learn - Save Learning to Database
+# /learn - Claude Code Best Practices & Learning Capture
 
-Capture a lesson from this session into the persistent SQLite database.
+Learn Claude Code best practices and capture lessons into persistent memory.
 
-## Process
+## Usage
 
-1. **Identify the learning**
-   - What mistake was made?
-   - What should happen instead?
-   - What category does this fall under?
+- `/learn` — Show best practices guide
+- `/learn <topic>` — Show practices for a specific topic (e.g., `/learn context`, `/learn prompting`)
+- `/learn save` — Capture a lesson from this session into the database
 
-2. **Categories**
-   - Navigation (file paths, finding code)
-   - Editing (code changes, patterns)
-   - Testing (test approaches)
-   - Git (commits, branches)
-   - Quality (lint, types, style)
-   - Context (when to clarify)
-   - Architecture (design decisions)
-   - Performance (optimization)
+## Best Practices
 
-3. **Save to database**
-   Use this format to save:
-   ```
-   Category: <category>
-   Rule: <one-line description of the correct behavior>
-   Mistake: <what went wrong>
-   Correction: <how it was fixed>
-   ```
+### Sessions & Context
+- Every Claude Code invocation is a session. Claude reads your project on start.
+- Context window is finite (200k tokens). Use `/context` to check usage.
+- Use `/compact` at task boundaries — after planning, after a feature, when >70%.
+- Don't compact mid-task. You lose working context.
+- **Docs:** https://code.claude.com/docs/common-workflows
+- **Pattern:** Context Discipline (Pattern 7)
 
-4. **Confirm storage**
-   Show the learning ID and confirm it was saved.
+### CLAUDE.md & Memory
+- CLAUDE.md is persistent project memory. It loads every session.
+- Put: project structure, build commands, conventions, constraints, gotchas.
+- Don't put: entire file contents, obvious things, rapidly changing info.
+- For complex projects, split into AGENTS.md, SOUL.md, LEARNED.md.
+- **Docs:** https://code.claude.com/docs/settings
+- **Pattern:** Split Memory (Pattern 4)
 
-## Example
+### Modes
+- **Normal** — Claude asks before edits (default)
+- **Auto-Accept** — Claude edits without asking (trusted iteration)
+- **Plan** — Research first, then propose plan (complex tasks)
+- Use Plan mode when: >3 files, architecture decisions, multiple approaches, unclear requirements.
+- Toggle with `Shift+Tab`.
+- **Docs:** https://code.claude.com/docs/common-workflows
+- **Pattern:** 80/20 Review (Pattern 5)
 
+### CLI Shortcuts
+| Shortcut | Action |
+|----------|--------|
+| `Shift+Tab` | Cycle modes |
+| `Ctrl+L` | Clear screen |
+| `Ctrl+C` | Cancel generation |
+| `Ctrl+B` | Run task in background |
+| `Up/Down` | Prompt history |
+| `/compact` | Compact context |
+| `/context` | Check context usage |
+| `/clear` | Clear conversation |
+- **Docs:** https://code.claude.com/docs/cli-reference
+
+### Prompting
+Good prompts have four parts:
+1. **Scope** — What files/area to work in
+2. **Context** — Background info Claude needs
+3. **Constraints** — What NOT to do
+4. **Acceptance criteria** — How to know it's done
+
+Bad: "Add rate limiting"
+Good: "In src/auth/, add rate limiting to the login endpoint. We use Express with Redis. Don't change session middleware. Return 429 after 5 failed attempts per IP in 15 min."
+
+### Writing Rules
+Rules in CLAUDE.md prevent Claude from going off-track.
+- Good: "Always use snake_case for database columns"
+- Good: "Run pytest -x after any Python file change"
+- Bad: "Write good code"
+- Bad: "Be careful"
+- **Pattern:** Self-Correction Loop (Pattern 1)
+
+### Skills
+Skills are reusable commands defined in markdown with frontmatter. Create one when you repeat the same prompt pattern >3 times.
+- **Docs:** https://code.claude.com/docs/settings
+- **Pattern:** Learning Log (Pattern 8)
+
+### Subagents
+Subagents run in separate context windows for parallel work.
+- Use for: parallel exploration, background tasks, independent research.
+- Avoid for: single-file reads, tasks needing conversation context.
+- Press `Ctrl+B` to send tasks to background.
+- **Docs:** https://code.claude.com/docs/sub-agents
+- **Pattern:** Parallel Worktrees (Pattern 2)
+
+### Hooks
+Hooks run scripts on events to automate quality enforcement.
+- Types: PreToolUse, PostToolUse, SessionStart, SessionEnd, Stop, UserPromptSubmit
+- Pro-Workflow ships hooks for edit tracking, quality gates, and learning capture.
+- **Docs:** https://code.claude.com/docs/hooks
+
+### Security
+- Review permission requests carefully.
+- Don't auto-approve shell commands you don't understand.
+- Keep secrets out of CLAUDE.md.
+- Use `.gitignore` and `.claudeignore` for sensitive files.
+- **Docs:** https://code.claude.com/docs/security
+
+### MCP
+- Keep <10 MCPs enabled, <80 tools total.
+- Disable MCPs you're not actively using.
+- Each MCP adds context overhead.
+- **Docs:** https://code.claude.com/docs/mcp
+
+### Integration
+- **VS Code / JetBrains:** https://code.claude.com/docs/ide-integration
+- **GitHub Actions:** https://code.claude.com/docs/github-actions
+- **Troubleshooting:** https://code.claude.com/docs/troubleshooting
+
+## Learning Path
+
+**Beginner:** Sessions, CLI shortcuts, context management, modes
+**Intermediate:** CLAUDE.md, writing rules, prompting, skills
+**Advanced:** Subagents, hooks, MCP, GitHub Actions, Pro-Workflow patterns 1-8
+
+## Saving Learnings
+
+Capture a lesson from this session:
+
+```
+Category: <category>
+Rule: <one-line description of the correct behavior>
+Mistake: <what went wrong>
+Correction: <how it was fixed>
 ```
-Recent mistake: Edited wrong utils.ts file when there were multiple
 
-Category: Navigation
-Rule: Confirm full path when multiple files share a name
-Mistake: Edited src/utils.ts instead of lib/utils.ts
-Correction: User pointed out the file was in lib/, not src/
+### Categories
+- Navigation (file paths, finding code)
+- Editing (code changes, patterns)
+- Testing (test approaches)
+- Git (commits, branches)
+- Quality (lint, types, style)
+- Context (when to clarify)
+- Architecture (design decisions)
+- Performance (optimization)
+- Claude-Code (sessions, modes, CLAUDE.md, skills, subagents, hooks, MCP)
+- Prompting (scope, constraints, acceptance criteria)
+
+### Example
 
-Saved as learning #42. Use /search utils to find this later.
 ```
+Category: Claude-Code
+Rule: Use plan mode before multi-file changes
+Mistake: Started editing 5 files without a plan, had to redo
+Correction: Enter plan mode first, get approval, then execute
 
-## Database Location
+Saved as learning #42. Use /search plan to find this later.
+```
 
 Learnings are stored in `~/.pro-workflow/data.db` and persist across sessions.
 
@@ -53,4 +150,4 @@ Use `/list` to see all learnings.
 
 ---
 
-**Trigger:** Use when user says "remember this", "add to rules", "learn this", or after making a mistake that should be captured.
+**Trigger:** Use when user says "learn", "teach me", "best practices", "remember this", or after making a mistake.
diff --git a/commands/list.md b/commands/list.md
@@ -47,6 +47,8 @@ Available categories:
 - Context
 - Architecture
 - Performance
+- Claude-Code
+- Prompting
 
 ## Related Commands
 

diff --git a/package.json b/package.json
@@ -51,6 +51,7 @@
     "contexts",
     "templates",
     "rules",
+    "references",
     "skills",
     "config.json",
     "README.md"