diff --git a/IMPROVEMENT_RECOMMENDATIONS.md b/IMPROVEMENT_RECOMMENDATIONS.md
new file mode 100644
index 0000000..632f41b
--- /dev/null
+++ b/IMPROVEMENT_RECOMMENDATIONS.md
@@ -0,0 +1,572 @@
+# Guide Improvement Recommendations
+
+Based on comprehensive analysis of zebbern/claude-code-guide, here are prioritized recommendations to enhance our Claude Code Ultimate Guide.
+
+## Priority 1: High-Impact Quick Wins โก
+
+### 1.1 Add Status Overview Table (5 min)
+
+**What:** Add a visual status table at the top showing section completeness.
+
+**Where:** Right after the main title, before TOC.
+
+**Implementation:**
+```markdown
+
+
+| Section | Status | Coverage |
+|---------|--------|----------|
+| Installation & Setup | โ
Complete | 100% |
+| Core Concepts | โ
Complete | 100% |
+| Agents & Skills | โ
Complete | 100% |
+| MCP Integration | ๐ Updating | 95% |
+| Advanced Patterns | โ
Complete | 100% |
+| Troubleshooting | โ
Complete | 100% |
+
+
+```
+
+**Benefit:** Users immediately see what's covered and maturity level.
+
+---
+
+### 1.2 Create One-Page Cheat Sheet (30 min)
+
+**What:** Ultra-condensed reference for daily use.
+
+**File:** `cheatsheet-en.md` (already exists but could be enhanced)
+
+**Format:** Single page with these sections:
+```markdown
+## Quick Reference Card
+
+### Essential Commands
+claude # Start REPL
+claude -p "query" # Print mode
+claude --model sonnet # Model selection
+claude --think # Extended reasoning
+
+### Config Management
+claude config get
+claude config set
+claude config add # For arrays
+
+### MCP Quick Setup
+claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents
+
+### Debugging
+claude doctor
+claude --debug
+claude --verbose
+
+### Permission Control
+--allowedTools "Edit,Read,Bash(git:*)"
+--disallowedTools "WebFetch"
+```
+
+**Benefit:** Printable, scannable, perfect for new team members.
+
+---
+
+### 1.3 Complete Command Line Flags Table (20 min)
+
+**What:** Comprehensive reference for all CLI flags.
+
+**Where:** Section 6 or new appendix.
+
+**Content:** Based on zebbern's table:
+| Flag | Description | Example |
+|------|-------------|---------|
+| `-p, --print` | Print response and exit | `claude -p "query"` |
+| `--output-format` | Output format (text/json/stream-json) | `--output-format json` |
+| `--input-format` | Input format (text/stream-json) | `--input-format stream-json` |
+| `--replay-user-messages` | Re-emit user messages in stream | `--replay-user-messages` |
+| `--allowedTools` | Whitelist tools | `--allowedTools "Edit,Read"` |
+| `--disallowedTools` | Blacklist tools | `--disallowedTools "WebFetch"` |
+| `--mcp-config` | Load MCP from JSON | `--mcp-config ./mcp.json` |
+| `--strict-mcp-config` | Only use specified MCP | `--strict-mcp-config` |
+| `--append-system-prompt` | Add to system prompt | `--append-system-prompt "..."` |
+| `--permission-mode` | Permission mode | `--permission-mode plan` |
+| `--model` | Model selection | `--model sonnet` |
+| `--add-dir` | Additional directories | `--add-dir ../apps ../lib` |
+| `--continue` | Continue last conversation | `--continue` |
+| `-r, --resume` | Resume session by ID | `--resume abc123` |
+| `--dangerously-skip-permissions` | Skip all permissions | `--dangerously-skip-permissions` |
+
+**Benefit:** Complete reference for power users and automation.
+
+---
+
+## Priority 2: Enhanced Troubleshooting ๐ง
+
+### 2.1 MCP Troubleshooting Section Enhancement (45 min)
+
+**What:** Add common MCP errors and solutions.
+
+**Where:** Expand section 10.4 "MCP Issues"
+
+**New subsections:**
+
+#### Common MCP Errors
+
+**Error 1: Tool Name Validation Failed**
+```
+API Error 400: "tools.11.custom.name: String should match pattern '^[a-zA-Z0-9_-]{1,64}'"
+```
+**Solution:**
+- Server name: only letters, numbers, underscores, hyphens
+- Max 64 characters
+- No special characters or spaces
+
+**Error 2: MCP Server Not Found**
+```
+MCP server 'my-server' not found
+```
+**Solution:**
+1. Check scope settings (local/user/project)
+2. Run `claude mcp list` to verify
+3. Ensure correct directory for local scope
+4. Restart Claude Code
+
+**Error 3: Windows Path Issues**
+```
+Error: Cannot find module 'C:UsersusernameDocuments'
+```
+**Solution:**
+```bash
+# Wrong
+claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:\Users\username\Documents
+
+# Correct
+claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:/Users/username/Documents
+# or
+claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem "C:\\Users\\username\\Documents"
+```
+
+#### MCP Debugging Techniques
+
+**Enable Debug Mode:**
+```bash
+claude --mcp-debug
+```
+
+**View MCP Status:**
+```bash
+/mcp # Inside Claude Code
+```
+
+**View Log Files:**
+```bash
+# macOS/Linux
+tail -f ~/Library/Logs/Claude/mcp*.log
+
+# Windows
+type "%APPDATA%\Claude\logs\mcp*.log"
+```
+
+**Manual Server Test:**
+```bash
+# Test if server works standalone
+npx -y @modelcontextprotocol/server-filesystem ~/Documents
+```
+
+---
+
+### 2.2 One-Shot Health Check Scripts (15 min)
+
+**What:** Copy-paste diagnostic scripts.
+
+**Where:** Section 10 "Help & Troubleshooting"
+
+**Windows (PowerShell):**
+```powershell
+Write-Host "`n=== Node & npm ==="; node --version; npm --version
+Write-Host "`n=== Where is claude? ==="; where claude
+Write-Host "`n=== Try doctor ==="; try { claude doctor } catch { Write-Host "claude not on PATH" }
+Write-Host "`n=== API key set? ==="; if ($env:ANTHROPIC_API_KEY) { "Yes" } else { "No" }
+Write-Host "`n=== MCP Status ==="; claude mcp list
+```
+
+**macOS/Linux (bash/zsh):**
+```bash
+echo "=== Node & npm ==="; node --version; npm --version
+echo "=== Where is claude? ==="; which claude || echo "claude not on PATH"
+echo "=== Try doctor ==="; claude doctor || true
+echo "=== API key set? ==="; [ -n "$ANTHROPIC_API_KEY" ] && echo Yes || echo No
+echo "=== MCP Status ==="; claude mcp list
+```
+
+**Benefit:** Instant diagnosis for users reporting issues.
+
+---
+
+### 2.3 Full Clean Reinstall Procedures (20 min)
+
+**What:** Nuclear option for corrupted installations.
+
+**Where:** Section 10 troubleshooting
+
+**Windows PowerShell Script:**
+```powershell
+# 1. Uninstall
+npm uninstall -g @anthropic-ai/claude-code
+
+# 2. Remove shims
+Remove-Item -LiteralPath "$env:USERPROFILE\AppData\Roaming\npm\claude*" -Force -ErrorAction SilentlyContinue
+Remove-Item -LiteralPath "$env:USERPROFILE\AppData\Roaming\npm\node_modules\@anthropic-ai\claude-code" -Recurse -Force -ErrorAction SilentlyContinue
+
+# 3. Delete cache
+Remove-Item -LiteralPath "$env:USERPROFILE\.claude\downloads\*" -Recurse -Force -ErrorAction SilentlyContinue
+Remove-Item -LiteralPath "$env:USERPROFILE\.claude\local" -Recurse -Force -ErrorAction SilentlyContinue
+
+# 4. Remove config (optional - backs up first)
+Copy-Item "$env:USERPROFILE\.claude.json" "$env:USERPROFILE\.claude.json.backup" -ErrorAction SilentlyContinue
+Remove-Item -LiteralPath "$env:USERPROFILE\.claude.json" -Force -ErrorAction SilentlyContinue
+
+# 5. Reinstall
+npm install -g @anthropic-ai/claude-code
+```
+
+**macOS/Linux Script:**
+```bash
+#!/bin/bash
+# 1. Uninstall
+npm uninstall -g @anthropic-ai/claude-code
+
+# 2. Remove global bin files
+rm -f "$(npm config get prefix)/bin/claude"
+rm -rf "$(npm config get prefix)/lib/node_modules/@anthropic-ai/claude-code"
+
+# 3. Delete cache
+rm -rf ~/.claude/downloads/*
+rm -rf ~/.claude/local
+
+# 4. Backup and remove config (optional)
+cp ~/.claude.json ~/.claude.json.backup 2>/dev/null || true
+rm -f ~/.claude.json
+
+# 5. Reinstall
+npm install -g @anthropic-ai/claude-code
+```
+
+**Benefit:** Last resort fix for mysterious issues.
+
+---
+
+## Priority 3: Format Enhancements ๐
+
+### 3.1 Add Visual Badges (10 min)
+
+**What:** Status badges at top of README.
+
+**Implementation:**
+```markdown
+
+
+
+
+```
+
+---
+
+### 3.2 Collapsible Tables for Dense Content (30 min)
+
+**What:** Use `` tags or tables for long sections.
+
+**Where:** Troubleshooting, environment variables, MCP server list.
+
+**Example:**
+```markdown
+
+Environment Variables Reference (click to expand)
+
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `ANTHROPIC_API_KEY` | API authentication | `sk-ant-...` |
+| `ANTHROPIC_MODEL` | Default model | `claude-sonnet-4-20250514` |
+| `BASH_DEFAULT_TIMEOUT_MS` | Bash timeout | `60000` |
+...
+
+
+```
+
+**Benefit:** Reduces visual clutter while keeping info accessible.
+
+---
+
+### 3.3 "C-Style Comment" Format for Multi-Variant Commands (15 min)
+
+**What:** Visual organization for OS-specific commands.
+
+**Example:**
+```C
+# Quick Start Installation
+/*โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ*/
+/* Universal Method */ npm install -g @anthropic-ai/claude-code
+/*โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ*/
+/* Windows (CMD) */ npm install -g @anthropic-ai/claude-code
+/* Windows (PowerShell) */ irm https://claude.ai/install.ps1 | iex
+/*โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ*/
+/* macOS */ brew install node && npm install -g @anthropic-ai/claude-code
+/*โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ*/
+/* Linux (Debian/Ubuntu) */ sudo apt update && sudo apt install -y nodejs npm
+/* */ npm install -g @anthropic-ai/claude-code
+```
+
+**Benefit:** Extremely scannable, looks professional.
+
+---
+
+## Priority 4: Content Additions ๐
+
+### 4.1 Security Best Practices - Do/Don't Format (30 min)
+
+**What:** Clear visual Do/Don't examples.
+
+**Where:** Section 8 Security
+
+**Format:**
+```markdown
+### Security Pitfalls
+
+**โ Don't:**
+- Use `--dangerously-skip-permissions` on production systems
+- Hard-code secrets in commands/config files
+- Grant overly broad permissions (`Bash(*)`)
+- Run with elevated privileges unnecessarily
+
+**โ
Do:**
+- Store secrets in environment variables
+- Start from minimal permissions and expand gradually
+- Audit regularly with `claude config list`
+- Isolate risky operations in containers/VMs
+```
+
+---
+
+### 4.2 Performance Pitfalls Section (20 min)
+
+**What:** Common performance mistakes.
+
+**Format:**
+```markdown
+### Performance Pitfalls
+
+**โ Don't:**
+- Load entire monorepo when you only need one package
+- Max out thinking/turn budgets for simple tasks
+- Ignore session cleanup (old sessions accumulate)
+- Use `--ultrathink` for trivial edits
+
+**โ
Do:**
+- Use `--add-dir` for focused context
+- Right-size with `--max-turns` and `MAX_THINKING_TOKENS`
+- Set `cleanupPeriodDays` to prune old sessions
+- Match thinking level to task complexity
+```
+
+---
+
+### 4.3 Workflow Pitfalls Section (20 min)
+
+**What:** Common workflow mistakes.
+
+**Format:**
+```markdown
+### Workflow Pitfalls
+
+**โ Don't:**
+- Skip project context (`CLAUDE.md`)
+- Use vague prompts ("fix this", "check my code")
+- Ignore errors in logs
+- Automate workflows without testing first
+
+**โ
Do:**
+- Maintain and update `CLAUDE.md` regularly
+- Be specific and goal-oriented in prompts
+- Monitor via logs/OpenTelemetry as appropriate
+- Test automation in safe environments first
+- Review agent outputs before committing
+```
+
+---
+
+### 4.4 DeepSeek Integration (15 min)
+
+**What:** Alternative LLM provider integration.
+
+**Where:** Section 11 "Third-Party Integrations"
+
+**Content:**
+```markdown
+## 11.1 DeepSeek Integration
+
+Use DeepSeek's Claude-compatible API as a cost-effective alternative.
+
+### Setup
+
+1. **Prerequisites:**
+ - Claude Code installed: `npm install -g @anthropic-ai/claude-code`
+ - DeepSeek API key from [platform.deepseek.com](https://platform.deepseek.com)
+
+2. **Configure Environment:**
+ ```bash
+ export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
+ export ANTHROPIC_AUTH_TOKEN=${YOUR_DEEPSEEK_API_KEY}
+ export ANTHROPIC_MODEL=deepseek-chat
+ export ANTHROPIC_SMALL_FAST_MODEL=deepseek-chat
+ ```
+
+3. **Launch Claude:**
+ ```bash
+ claude
+ ```
+
+### Cost Comparison
+
+| Provider | Model | Cost per 1M tokens |
+|----------|-------|-------------------|
+| Anthropic | Sonnet 4 | ~$3.00 |
+| DeepSeek | deepseek-chat | ~$0.14 |
+
+**Savings: ~95% reduction**
+
+### Limitations
+
+- DeepSeek models have different capabilities than Claude
+- Some advanced features may not work identically
+- Performance/quality trade-offs exist
+
+### Resources
+
+- [DeepSeek API Documentation](https://api-docs.deepseek.com/guides/anthropic_api)
+- [DeepSeek Platform](https://platform.deepseek.com)
+```
+
+---
+
+## Priority 5: Documentation Structure ๐๏ธ
+
+### 5.1 Add Quick Navigation Links (10 min)
+
+**What:** Jump links at top of major sections.
+
+**Example:**
+```markdown
+## Section 6: Commands & Usage
+
+_Quick jump:_ [Slash Commands](#slash-commands) ยท [CLI Flags](#cli-flags) ยท [Cheat Sheet](#cheat-sheet) ยท [Environment Variables](#environment-variables)
+
+---
+
+### 6.1 Slash Commands
+...
+```
+
+---
+
+### 5.2 Appendix: Useful Paths (10 min)
+
+**What:** Reference for file locations.
+
+**Content:**
+```markdown
+## Appendix A: File Locations Reference
+
+### Windows
+- **npm global bin:** `C:\Users\\AppData\Roaming\npm`
+- **Node.js:** `C:\Program Files\nodejs`
+- **Claude data:** `C:\Users\\.claude\`
+- **Claude config:** `C:\Users\\.claude.json`
+- **Logs:** `%APPDATA%\Claude\logs\`
+
+### macOS/Linux
+- **npm global bin:** `$(npm config get prefix)/bin` (often `/usr/local/bin`)
+- **Claude data:** `~/.claude/`
+- **Claude config:** `~/.claude.json`
+- **Logs (macOS):** `~/Library/Logs/Claude/`
+- **Logs (Linux):** `~/.local/share/claude/logs/`
+```
+
+---
+
+## Implementation Roadmap
+
+### Phase 1: Quick Wins (2-3 hours)
+1. โ
Add thinking keywords inline syntax
+2. โ
Create GitHub Actions examples directory
+3. Add status overview table
+4. Create/enhance cheat sheet
+5. Add CLI flags table
+6. Add visual badges
+
+### Phase 2: Troubleshooting (3-4 hours)
+1. MCP troubleshooting enhancement
+2. One-shot health check scripts
+3. Full clean reinstall procedures
+4. Appendix: useful paths
+
+### Phase 3: Content Enrichment (4-5 hours)
+1. Security pitfalls Do/Don't
+2. Performance pitfalls
+3. Workflow pitfalls
+4. DeepSeek integration
+5. Collapsible tables for dense content
+
+### Phase 4: Format Polish (2-3 hours)
+1. C-style comment format for commands
+2. Quick navigation links
+3. Consistent emoji hierarchy
+4. Table of contents update
+
+---
+
+## Metrics for Success
+
+### User Experience
+- **Time to first success:** < 15 minutes (installation โ first task)
+- **Time to find answer:** < 2 minutes (via cheat sheet or quick links)
+- **Support ticket reduction:** Target 30% reduction via better troubleshooting
+
+### Content Quality
+- **Coverage:** 100% of official features documented
+- **Accuracy:** < 1% error rate in commands/examples
+- **Freshness:** Updated within 7 days of new Claude Code releases
+
+### Community Engagement
+- **GitHub Stars:** Track growth trend
+- **Issues/PRs:** Measure community contributions
+- **Fork activity:** Indicates usage/adaptation
+
+---
+
+## What NOT to Change
+
+**Keep these strengths from our guide:**
+
+1. **Learning Path Structure** - Junior โ Senior โ Power User progression
+2. **Trinity Pattern** - Unique advanced workflow
+3. **OpusPlan Mode** - Cost optimization strategy
+4. **Context Management Zones** - Clear guidance on usage levels
+5. **Maturity Model** - 5-level progression framework
+6. **Agent-Based Task Delegation** - Advanced orchestration
+7. **Skill Inheritance Model** - Reusable expertise
+8. **Git Archaeology Pattern** - Unique debugging approach
+9. **Narrative Style** - Pedagogical, not just reference
+10. **Real-world Examples** - Production scenarios, not toy examples
+
+---
+
+## Conclusion
+
+These recommendations balance:
+- **Immediate impact** (quick wins) with **long-term value** (structural improvements)
+- **Reference utility** (cheat sheets, tables) with **learning journey** (narrative)
+- **Completeness** (troubleshooting) with **scannability** (collapsible sections)
+
+**Core Philosophy:**
+> zebbern's guide = comprehensive reference
+> our guide = mastery journey
+> **enhanced guide = both**
+
+By selectively adopting zebbern's strengths while preserving our unique pedagogical approach, we create the definitive Claude Code resource.
diff --git a/english-ultimate-claude-code-guide.md b/english-ultimate-claude-code-guide.md
index d3906e2..4dfa1c2 100644
--- a/english-ultimate-claude-code-guide.md
+++ b/english-ultimate-claude-code-guide.md
@@ -3932,6 +3932,31 @@ The most powerful Claude Code pattern combines three techniques:
| `--think-hard` | Deep | ~10K | Architectural decisions |
| `--ultrathink` | Maximum | ~32K | Critical redesign |
+#### Inline Thinking Keywords
+
+You can also trigger extended thinking by adding keywords directly in your prompt:
+
+```bash
+# Minimal boost - standard analysis
+claude -p "Think. Outline a plan to refactor the auth module."
+
+# Medium boost - deeper consideration
+claude -p "Think hard. Draft a migration plan from REST to gRPC."
+
+# Strong boost - thorough analysis
+claude -p "Think harder. Evaluate trade-offs for our caching strategy."
+
+# Maximum boost - comprehensive reasoning
+claude -p "Ultrathink. Propose a step-by-step strategy to fix flaky payment tests and add guardrails."
+```
+
+**How it works:**
+- **think** โ Claude spends more time planning before responding
+- **think hard/harder** โ Progressively deeper analysis with more consideration of alternatives
+- **ultrathink** โ Maximum pre-answer reasoning about implications, edge cases, and trade-offs
+
+**Higher levels increase latency and token usage** - use the smallest level that works for your task.
+
### Example: Using the Trinity
```
diff --git a/examples/github-actions/README.md b/examples/github-actions/README.md
new file mode 100644
index 0000000..88e5229
--- /dev/null
+++ b/examples/github-actions/README.md
@@ -0,0 +1,203 @@
+# GitHub Actions Workflows for Claude Code
+
+Ready-to-use GitHub Actions workflows that integrate Claude Code into your CI/CD pipeline.
+
+## Prerequisites
+
+1. **Install the Claude GitHub App** on your org/repo (required for Actions to comment on PRs/issues)
+2. **Add API Key Secret**: In your repo, go to Settings โ Secrets and variables โ Actions โ New repository secret
+ - Name: `ANTHROPIC_API_KEY`
+ - Value: Your Anthropic API key from [console.anthropic.com](https://console.anthropic.com)
+3. **Copy Workflows**: Place these `.yml` files in `.github/workflows/` directory
+4. **Test**: Open a test PR or issue to see them run
+
+## Available Workflows
+
+### 1. Auto PR Review (`claude-pr-auto-review.yml`)
+
+Creates a structured review with inline comments as soon as a PR opens or updates.
+
+**Features:**
+- Automatic code review on PR open/update
+- Inline comments on specific lines
+- Reviews for correctness, readability, testing, performance, DX
+
+**Usage:**
+```bash
+# Copy the workflow file
+cp examples/github-actions/claude-pr-auto-review.yml .github/workflows/
+
+# Open a PR - Claude will automatically review it
+```
+
+---
+
+### 2. Security Review (`claude-security-review.yml`)
+
+Runs a focused security scan and comments findings directly on the PR.
+
+**Features:**
+- Security-focused analysis on every PR
+- Identifies potential vulnerabilities
+- OWASP Top 10 considerations
+- Posts findings as PR comments
+
+**Configuration:**
+```yaml
+# Optional parameters in the workflow file:
+exclude-directories: "docs,examples" # Skip certain directories
+claudecode-timeout: "20" # Timeout in minutes
+claude-model: "claude-3-5-sonnet-20240620" # Model to use
+```
+
+**Usage:**
+```bash
+# Copy the workflow file
+cp examples/github-actions/claude-security-review.yml .github/workflows/
+
+# Every PR will be automatically scanned for security issues
+```
+
+---
+
+### 3. Issue Triage (`claude-issue-triage.yml`)
+
+When a new issue opens, Claude proposes labels/severity and posts a tidy triage comment.
+
+**Features:**
+- Automatic issue classification
+- Label suggestions
+- Severity assessment (low, medium, high, critical)
+- Duplicate detection
+- Markdown triage comment
+
+**Auto-apply Labels (Optional):**
+To automatically apply suggested labels, edit the workflow file and change:
+```yaml
+- name: Apply labels (optional)
+ if: ${{ false }} # Change to true to auto-apply labels
+```
+
+**Usage:**
+```bash
+# Copy the workflow file
+cp examples/github-actions/claude-issue-triage.yml .github/workflows/
+
+# Open a new issue - Claude will automatically triage it
+```
+
+---
+
+## Customization
+
+### Model Selection
+Set `CLAUDE_MODEL` or `claude-model` parameter in workflows:
+```yaml
+env:
+ CLAUDE_MODEL: claude-3-5-sonnet-20240620
+```
+
+### Permissions
+Each workflow declares minimal required permissions:
+- `pull-requests: write` for PR reviews
+- `issues: write` for issue triage
+- `contents: read` for reading repository content
+
+Adjust only if your organization requires stricter policies.
+
+### Scope Filtering
+Use `paths:` filters to limit when workflows run:
+```yaml
+on:
+ pull_request:
+ paths:
+ - 'src/**'
+ - '!docs/**'
+```
+
+## Troubleshooting
+
+**No comments appear on PRs:**
+- Verify the Claude GitHub App is installed
+- Check workflow has `pull-requests: write` permission
+
+**403 when applying labels:**
+- Ensure the job has `issues: write` permission
+- Verify `GITHUB_TOKEN` has access to this repo
+
+**Anthropic API errors:**
+- Confirm `ANTHROPIC_API_KEY` is set at repository level
+- Check the key is not expired
+
+**YAML syntax errors:**
+- Validate spacing: two spaces per nesting level, no tabs
+- Use a YAML validator: [yamllint.com](https://www.yamllint.com/)
+
+## Advanced Usage
+
+### Combining Workflows
+Run multiple workflows together for comprehensive automation:
+- PR Review + Security Review on every PR
+- Issue Triage + Auto-labeling for new issues
+
+### Custom Prompts
+Edit the `direct_prompt` section in workflows to customize Claude's focus:
+```yaml
+direct_prompt: |
+ Review this PR focusing on:
+ 1. TypeScript type safety
+ 2. React performance patterns
+ 3. Accessibility compliance
+ 4. Test coverage
+```
+
+### Integration with Other Actions
+Combine with existing workflows:
+```yaml
+jobs:
+ tests:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Run tests
+ run: npm test
+
+ claude-review:
+ needs: tests # Run after tests pass
+ runs-on: ubuntu-latest
+ steps:
+ - uses: anthropics/claude-code-action@main
+ # ...
+```
+
+## Cost Considerations
+
+These workflows consume Anthropic API credits:
+- **PR Review**: ~$0.10-$0.50 per review (depending on diff size)
+- **Security Review**: ~$0.20-$0.80 per scan
+- **Issue Triage**: ~$0.05-$0.20 per issue
+
+**Tips to reduce costs:**
+- Use `paths:` filters to skip docs/config changes
+- Set conditions: `if: github.event.pull_request.draft == false`
+- Review logs and adjust model selection
+
+## Examples in This Directory
+
+```
+examples/github-actions/
+โโโ README.md # This file
+โโโ claude-pr-auto-review.yml # Auto PR review workflow
+โโโ claude-security-review.yml # Security scanning workflow
+โโโ claude-issue-triage.yml # Issue triage workflow
+```
+
+## Resources
+
+- [Claude Code Documentation](https://claude.ai/code)
+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
+- [Anthropic API Documentation](https://docs.anthropic.com/)
+- [Claude GitHub App](https://github.com/apps/claude)
+
+## License
+
+These workflows are provided as examples. Adapt them to your needs.
diff --git a/examples/github-actions/claude-issue-triage.yml b/examples/github-actions/claude-issue-triage.yml
new file mode 100644
index 0000000..6602a38
--- /dev/null
+++ b/examples/github-actions/claude-issue-triage.yml
@@ -0,0 +1,101 @@
+name: Claude Issue Triage
+on:
+ issues:
+ types: [opened, edited, reopened]
+
+permissions:
+ contents: read
+ issues: write
+
+jobs:
+ triage:
+ runs-on: ubuntu-latest
+ env:
+ CLAUDE_MODEL: claude-3-5-sonnet-20240620
+ steps:
+ - name: Collect context & similar issues
+ id: gather
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: |
+ TITLE="${{ github.event.issue.title }}"
+ BODY="${{ github.event.issue.body }}"
+ # naive similar search by title words
+ Q=$(echo "$TITLE" | tr -dc '[:alnum:] ' | awk '{print $1" "$2" "$3" "$4}')
+ gh api -X GET search/issues -f q="repo:${{ github.repository }} is:issue $Q" -f per_page=5 > similars.json
+ echo "$TITLE" > title.txt
+ echo "$BODY" > body.txt
+
+ - name: Ask Claude for triage JSON
+ env:
+ ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+ run: |
+ cat > payload.json << 'JSON'
+ {
+ "model": "${{ env.CLAUDE_MODEL }}",
+ "max_tokens": 1500,
+ "system": "You are a pragmatic triage engineer. Be specific, cautious with duplicates.",
+ "messages": [{
+ "role": "user",
+ "content": [{
+ "type":"text",
+ "text":"Given the issue and similar candidates, produce STRICT JSON with keys: labels (array of strings), severity (one of: low, medium, high, critical), duplicate_url (string or empty), comment_markdown (string brief). Do not include any extra keys."
+ },
+ {"type":"text","text":"Issue title:\n"},
+ {"type":"text","text": "PLACEHOLDER_TITLE"},
+ {"type":"text","text":"\n\nIssue body:\n"},
+ {"type":"text","text": "PLACEHOLDER_BODY"},
+ {"type":"text","text":"\n\nSimilar issues (JSON):\n"},
+ {"type":"text","text": "PLACEHOLDER_SIMILARS"}]
+ }]
+ }
+ JSON
+
+ # Inject files safely
+ jq --arg title "$(cat title.txt)" '.messages[0].content[2].text = $title' payload.json \
+ | jq --arg body "$(cat body.txt)" '.messages[0].content[4].text = $body' \
+ | jq --arg sims "$(cat similars.json)" '.messages[0].content[6].text = $sims' > payload.final.json
+
+ curl -s https://api.anthropic.com/v1/messages \
+ -H "x-api-key: $ANTHROPIC_API_KEY" \
+ -H "anthropic-version: 2023-06-01" \
+ -H "content-type: application/json" \
+ -d @payload.final.json > out.json
+ jq -r '.content[0].text' out.json > triage.json || echo '{}' > triage.json
+
+ # Validate JSON to avoid posting garbage
+ jq -e . triage.json >/dev/null 2>&1 || echo '{"labels":[],"severity":"low","duplicate_url":"","comment_markdown":"(triage failed to parse)"}' > triage.json
+
+ - name: Apply labels (optional)
+ if: ${{ false }} # flip to `true` to auto-apply labels
+ uses: actions/github-script@v7
+ with:
+ script: |
+ const triage = JSON.parse(require('fs').readFileSync('triage.json','utf8'))
+ if (triage.labels?.length) {
+ await github.rest.issues.addLabels({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ issue_number: context.issue.number,
+ labels: triage.labels
+ })
+ }
+
+ - name: Post triage comment
+ uses: actions/github-script@v7
+ with:
+ script: |
+ const fs = require('fs')
+ const triage = JSON.parse(fs.readFileSync('triage.json','utf8'))
+ const md = `### ๐ค Triage
+ - **Suggested labels:** ${triage.labels?.join(', ') || 'โ'}
+ - **Severity:** ${triage.severity || 'โ'}
+ ${triage.duplicate_url ? `- **Possible duplicate:** ${triage.duplicate_url}\n` : ''}
+ ---
+ ${triage.comment_markdown || ''}`
+ await github.rest.issues.createComment({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ issue_number: context.issue.number,
+ body: md
+ })
diff --git a/examples/github-actions/claude-pr-auto-review.yml b/examples/github-actions/claude-pr-auto-review.yml
new file mode 100644
index 0000000..e41ce81
--- /dev/null
+++ b/examples/github-actions/claude-pr-auto-review.yml
@@ -0,0 +1,31 @@
+name: Auto review PRs
+on:
+ pull_request:
+ types: [opened, synchronize, reopened, ready_for_review]
+
+permissions:
+ contents: read
+ pull-requests: write
+
+jobs:
+ auto-review:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ fetch-depth: 1
+
+ - name: Claude PR review
+ uses: anthropics/claude-code-action@main
+ with:
+ anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+ # Claude will fetch the diff and leave inline comments
+ direct_prompt: |
+ Review this pull request's diff for correctness, readability, testing, performance, and DX.
+ Prefer specific, actionable suggestions. Use inline comments where relevant.
+ # GitHub tools permitted during the run:
+ allowed_tools: >-
+ mcp__github__get_pull_request_diff,
+ mcp__github__create_pending_pull_request_review,
+ mcp__github__add_comment_to_pending_review,
+ mcp__github__submit_pending_pull_request_review
diff --git a/examples/github-actions/claude-security-review.yml b/examples/github-actions/claude-security-review.yml
new file mode 100644
index 0000000..46b989d
--- /dev/null
+++ b/examples/github-actions/claude-security-review.yml
@@ -0,0 +1,26 @@
+name: Security Review
+on:
+ pull_request:
+
+permissions:
+ contents: read
+ pull-requests: write
+
+jobs:
+ security:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ ref: ${{ github.event.pull_request.head.sha || github.sha }}
+ fetch-depth: 2
+
+ - name: Claude Code Security Review
+ uses: anthropics/claude-code-security-review@main
+ with:
+ claude-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
+ comment-pr: true
+ # Optional configuration:
+ # exclude-directories: "docs,examples"
+ # claudecode-timeout: "20"
+ # claude-model: "claude-3-5-sonnet-20240620"