claude-code-arcane 2.9.8 → 2.9.9

package/skills/self-improving-agent/CLAUDE.md

@@ -4,13 +4,13 @@ This plugin helps you curate Claude Code's auto-memory into durable project know
 
 ## Commands
 
-Use the `/si:` namespace for all commands:
+All commands are sub-commands of `/self-improving-agent`:
 
-- `/si:review` — Analyze auto-memory health and find promotion candidates
-- `/si:promote <pattern>` — Graduate a learning to CLAUDE.md or `.claude/rules/`
-- `/si:extract <pattern>` — Create a reusable skill from a proven pattern
-- `/si:status` — Quick memory health dashboard
-- `/si:remember <knowledge>` — Explicitly save something to auto-memory
+- `/self-improving-agent review` — Analyze auto-memory health and find promotion candidates
+- `/self-improving-agent promote <pattern>` — Graduate a learning to CLAUDE.md or `.claude/rules/`
+- `/self-improving-agent extract <pattern>` — Create a reusable skill from a proven pattern
+- `/self-improving-agent status` — Quick memory health dashboard
+- `/self-improving-agent remember <knowledge>` — Explicitly save something to auto-memory
 
 ## How auto-memory works
 
@@ -22,25 +22,25 @@ This plugin reads that directory — it never creates its own storage.
 
 ### After completing a feature or debugging session
 ```
-/si:review
+/self-improving-agent review
 ```
 Check if anything Claude learned should become a permanent rule.
 
 ### When a pattern keeps coming up
 ```
-/si:promote "Always run migrations before tests in this project"
+/self-improving-agent promote "Always run migrations before tests in this project"
 ```
 Moves it from MEMORY.md (background note) to CLAUDE.md (enforced rule).
 
 ### When you solved something non-obvious that could help other projects
 ```
-/si:extract "Docker build fix for ARM64 platform mismatch"
+/self-improving-agent extract "Docker build fix for ARM64 platform mismatch"
 ```
 Creates a standalone skill with SKILL.md, ready to install elsewhere.
 
 ### To check memory capacity
 ```
-/si:status
+/self-improving-agent status
 ```
 Shows line counts, topic files, stale entries, and recommendations.
 
@@ -55,8 +55,8 @@ Shows line counts, topic files, stale entries, and recommendations.
 
 ## Agents
 
-- **memory-analyst**: Spawned by `/si:review` to analyze patterns across memory files
-- **skill-extractor**: Spawned by `/si:extract` to generate complete skill packages
+- **memory-analyst**: Spawned by `/self-improving-agent review` to analyze patterns across memory files
+- **skill-extractor**: Spawned by `/self-improving-agent extract` to generate complete skill packages
 
 ## Hooks
 

package/skills/self-improving-agent/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: self-improving-agent
 description: "Curate Claude Code's auto-memory into durable project knowledge. Analyze MEMORY.md for patterns, promote proven learnings to CLAUDE.md and .claude/rules/, extract recurring solutions into reusable skills."
-argument-hint: ""
+argument-hint: "[extract|promote|remember|review|status] [args]"
 category: "arcane"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash, Write, Edit
@@ -11,15 +11,19 @@ allowed-tools: Read, Glob, Grep, Bash, Write, Edit
 
 Claude Code's auto-memory (v2.1.32+) automatically records project patterns, debugging insights, and your preferences in `MEMORY.md`. This skill adds the intelligence layer: it analyzes what Claude has learned, promotes proven patterns into project rules, and extracts recurring solutions into reusable skills. May write or edit CLAUDE.md, .claude/rules/ files, and new skill files during promotion and extraction.
 
+## Sub-commands
+
+`/self-improving-agent` with no argument shows this overview. With a sub-command as its first argument, read `skills/<sub-command>/SKILL.md` from this skill's directory and follow it, passing the remaining arguments. Sub-commands: `extract`, `promote`, `remember`, `review`, `status`.
+
 ## Quick Reference
 
 | Command | What it does |
 |---------|-------------|
-| `/si:review` | Analyze MEMORY.md -- find promotion candidates, stale entries, consolidation opportunities |
-| `/si:promote` | Graduate a pattern from MEMORY.md to CLAUDE.md or `.claude/rules/` |
-| `/si:extract` | Turn a proven pattern into a standalone skill |
-| `/si:status` | Memory health dashboard -- line counts, topic files, recommendations |
-| `/si:remember` | Explicitly save important knowledge to auto-memory |
+| `/self-improving-agent review` | Analyze MEMORY.md -- find promotion candidates, stale entries, consolidation opportunities |
+| `/self-improving-agent promote` | Graduate a pattern from MEMORY.md to CLAUDE.md or `.claude/rules/` |
+| `/self-improving-agent extract` | Turn a proven pattern into a standalone skill |
+| `/self-improving-agent status` | Memory health dashboard -- line counts, topic files, recommendations |
+| `/self-improving-agent remember` | Explicitly save important knowledge to auto-memory |
 
 ## How It Fits Together
 
@@ -33,9 +37,9 @@ Claude Code's auto-memory (v2.1.32+) automatically records project patterns, deb
 │  standards  │   + topic files  │   + continuity         │
 │  Full load  │   First 200 lines│   Contextual load      │
 ├─────────────┴──────────────────┴────────────────────────┤
-│              /si:promote          /si:review             │
+│              /self-improving-agent promote          /self-improving-agent review             │
 │         Self-Improving Agent (this skill)                │
-│              /si:extract      /si:remember              │
+│              /self-improving-agent extract      /self-improving-agent remember              │
 ├─────────────────────────────────────────────────────────┤
 │  .claude/rules/    │    New Skills    │   Error Logs     │
 │  (scoped rules)    │    (extracted)   │   (auto-captured)│
@@ -48,18 +52,18 @@ Claude Code's auto-memory (v2.1.32+) automatically records project patterns, deb
 
 | File | Who writes | Scope | Loaded |
 |------|-----------|-------|--------|
-| `./CLAUDE.md` | You (+ `/si:promote`) | Project rules | Full file, every session |
+| `./CLAUDE.md` | You (+ `/self-improving-agent promote`) | Project rules | Full file, every session |
 | `~/.claude/CLAUDE.md` | You | Global preferences | Full file, every session |
 | `~/.claude/projects/<path>/memory/MEMORY.md` | Claude (auto) | Project learnings | First 200 lines |
 | `~/.claude/projects/<path>/memory/*.md` | Claude (overflow) | Topic-specific notes | On demand |
-| `.claude/rules/*.md` | You (+ `/si:promote`) | Scoped rules | When matching files open |
+| `.claude/rules/*.md` | You (+ `/self-improving-agent promote`) | Scoped rules | When matching files open |
 
 ### The promotion lifecycle
 
 ```
 1. Claude discovers pattern -> auto-memory (MEMORY.md)
-2. Pattern recurs 2-3x -> /si:review flags it as promotion candidate
-3. You approve -> /si:promote graduates it to CLAUDE.md or rules/
+2. Pattern recurs 2-3x -> /self-improving-agent review flags it as promotion candidate
+3. You approve -> /self-improving-agent promote graduates it to CLAUDE.md or rules/
 4. Pattern becomes an enforced rule, not just a note
 5. MEMORY.md entry removed -> frees space for new learnings
 ```

package/skills/self-improving-agent/agents/memory-analyst.md

@@ -64,7 +64,7 @@ Organize findings into:
 
 ## Output Format
 
-Use the format defined in the `/si:review` skill. Be specific — include line numbers, exact text, and concrete suggestions.
+Use the format defined in the `/self-improving-agent review` skill. Be specific — include line numbers, exact text, and concrete suggestions.
 
 ## Constraints
 

package/skills/self-improving-agent/hooks/error-capture.sh

@@ -103,8 +103,8 @@ cat << EOF
 <error-detected>
 Command error detected (pattern: "$matched_pattern").
 If this was unexpected or required investigation to fix, save the solution:
-  /si:remember "explanation of what went wrong and the fix"
-Or if this is a known pattern, check: /si:review
+  /self-improving-agent remember "explanation of what went wrong and the fix"
+Or if this is a known pattern, check: /self-improving-agent review
 Context: $(echo "$error_context" | head -2 | tr '\n' ' ' | cut -c1-200)
 </error-detected>
 EOF

package/skills/self-improving-agent/reference/memory-architecture.md

@@ -103,7 +103,7 @@ When entries conflict:
 ```
 Auto-memory captures → This plugin curates → CLAUDE.md enforces
 
-MEMORY.md (raw notes)  →  /si:review (analyze)  →  /si:promote (graduate)
+MEMORY.md (raw notes)  →  /self-improving-agent review (analyze)  →  /self-improving-agent promote (graduate)
                                                           ↓
                                                     CLAUDE.md or
                                                     .claude/rules/
@@ -128,4 +128,4 @@ MEMORY.md (raw notes)  →  /si:review (analyze)  →  /si:promote (graduate)
 3. **Don't duplicate** — if it's in CLAUDE.md, remove it from MEMORY.md
 4. **Scope rules** — use `.claude/rules/` with paths for file-type-specific patterns
 5. **Review quarterly** — memory files go stale after refactors
-6. **Use /si:status** — monitor capacity before it becomes a problem
+6. **Use /self-improving-agent status** — monitor capacity before it becomes a problem

package/skills/self-improving-agent/reference/promotion-rules.md

@@ -74,10 +74,10 @@ When promoting, transform the learning:
 ## Promotion Workflow
 
 ```
-1. /si:review identifies candidate
+1. /self-improving-agent review identifies candidate
 2. Confirm the pattern is still valid
 3. Distill into one-line instruction
-4. /si:promote writes to CLAUDE.md or rules/
+4. /self-improving-agent promote writes to CLAUDE.md or rules/
 5. Remove from MEMORY.md
-6. Verify with /si:status
+6. Verify with /self-improving-agent status
 ```

package/skills/self-improving-agent/reference/rules-directory-patterns.md

@@ -125,7 +125,7 @@ paths:
 |--------|--------|
 | CLAUDE.md over 150 lines | Move scoped patterns to rules/ |
 | Same instruction repeated for different file types | Create a scoped rule |
-| `/si:promote` suggests a file-type-specific pattern | Create or append to a rule file |
+| `/self-improving-agent promote` suggests a file-type-specific pattern | Create or append to a rule file |
 | Team adds a new convention for a specific area | New rule file |
 
 ## Organization Tips

package/skills/self-improving-agent/settings.json

@@ -10,11 +10,11 @@
   "tags": ["memory", "auto-memory", "self-improvement", "learning", "rules", "skills"],
   "repository": "https://github.com/alirezarezvani/claude-skills",
   "commands": {
-    "review": "/si:review",
-    "promote": "/si:promote",
-    "extract": "/si:extract",
-    "status": "/si:status",
-    "remember": "/si:remember"
+    "review": "/self-improving-agent review",
+    "promote": "/self-improving-agent promote",
+    "extract": "/self-improving-agent extract",
+    "status": "/self-improving-agent status",
+    "remember": "/self-improving-agent remember"
   },
   "hooks": {
     "PostToolUse": {

package/skills/self-improving-agent/skills/extract/SKILL.md

@@ -7,17 +7,17 @@ user-invocable: false
 allowed-tools: Read, Glob, Grep, Bash, Write, Edit
 ---
 
-# /si:extract — Create Skills from Patterns
+# /self-improving-agent extract — Create Skills from Patterns
 
 Transforms a recurring pattern or debugging solution into a standalone, portable skill that can be installed in any project.
 
 ## Usage
 
 ```
-/si:extract <pattern description>                  # Interactive extraction
-/si:extract <pattern> --name docker-m1-fixes       # Specify skill name
-/si:extract <pattern> --output ./skills/            # Custom output directory
-/si:extract <pattern> --dry-run                     # Preview without creating files
+/self-improving-agent extract <pattern description>                  # Interactive extraction
+/self-improving-agent extract <pattern> --name docker-m1-fixes       # Specify skill name
+/self-improving-agent extract <pattern> --output ./skills/            # Custom output directory
+/self-improving-agent extract <pattern> --dry-run                     # Preview without creating files
 ```
 
 ## When to Extract
@@ -153,7 +153,7 @@ Source: MEMORY.md entries at lines {{n, m, ...}} (retained — the skill is port
 ### Extracting a debugging pattern
 
 ```
-/si:extract "Fix for Docker builds failing on Apple Silicon with platform mismatch"
+/self-improving-agent extract "Fix for Docker builds failing on Apple Silicon with platform mismatch"
 ```
 
 Creates `docker-m1-fixes/SKILL.md` with:
@@ -165,7 +165,7 @@ Creates `docker-m1-fixes/SKILL.md` with:
 ### Extracting a workflow pattern
 
 ```
-/si:extract "Always regenerate TypeScript API client after modifying OpenAPI spec"
+/self-improving-agent extract "Always regenerate TypeScript API client after modifying OpenAPI spec"
 ```
 
 Creates `api-client-regen/SKILL.md` with:

package/skills/self-improving-agent/skills/promote/SKILL.md

@@ -7,17 +7,17 @@ user-invocable: false
 allowed-tools: Read, Glob, Grep, Bash, Write, Edit
 ---
 
-# /si:promote — Graduate Learnings to Rules
+# /self-improving-agent promote — Graduate Learnings to Rules
 
 Moves a proven pattern from Claude's auto-memory into the project's rule system, where it becomes an enforced instruction rather than a background note.
 
 ## Usage
 
 ```
-/si:promote <pattern description>                    # Auto-detect best target
-/si:promote <pattern> --target claude.md             # Promote to CLAUDE.md
-/si:promote <pattern> --target rules/testing.md      # Promote to scoped rule
-/si:promote <pattern> --target rules/api.md --paths "src/api/**/*.ts"  # Scoped with paths
+/self-improving-agent promote <pattern description>                    # Auto-detect best target
+/self-improving-agent promote <pattern> --target claude.md             # Promote to CLAUDE.md
+/self-improving-agent promote <pattern> --target rules/testing.md      # Promote to scoped rule
+/self-improving-agent promote <pattern> --target rules/api.md --paths "src/api/**/*.ts"  # Scoped with paths
 ```
 
 ## Workflow

package/skills/self-improving-agent/skills/remember/SKILL.md

@@ -7,17 +7,17 @@ user-invocable: false
 allowed-tools: Read, Glob, Grep, Bash, Write, Edit
 ---
 
-# /si:remember — Save Knowledge Explicitly
+# /self-improving-agent remember — Save Knowledge Explicitly
 
 Writes an explicit entry to auto-memory when something is important enough that you don't want to rely on Claude noticing it automatically.
 
 ## Usage
 
 ```
-/si:remember <what to remember>
-/si:remember "This project's CI requires Node 20 LTS — v22 breaks the build"
-/si:remember "The /api/auth endpoint uses a custom JWT library, not passport"
-/si:remember "Reza prefers explicit error handling over try-catch-all patterns"
+/self-improving-agent remember <what to remember>
+/self-improving-agent remember "This project's CI requires Node 20 LTS — v22 breaks the build"
+/self-improving-agent remember "The /api/auth endpoint uses a custom JWT library, not passport"
+/self-improving-agent remember "Reza prefers explicit error handling over try-catch-all patterns"
 ```
 
 ## When to Use
@@ -63,7 +63,7 @@ Keep entries concise — one line when possible. Auto-memory entries don't need
 If MEMORY.md is over 180 lines, warn the user:
 
 ```
-⚠️ MEMORY.md is at {{n}}/200 lines. Consider running /si:review to free space.
+⚠️ MEMORY.md is at {{n}}/200 lines. Consider running /self-improving-agent review to free space.
 ```
 
 ### Step 4: Suggest promotion
@@ -72,7 +72,7 @@ If the knowledge sounds like a rule (imperative, always/never, convention):
 
 ```
 💡 This sounds like it could be a CLAUDE.md rule rather than a memory entry.
-   Rules are enforced with higher priority. Want to /si:promote it instead?
+   Rules are enforced with higher priority. Want to /self-improving-agent promote it instead?
 ```
 
 ### Step 5: Confirm
@@ -86,10 +86,10 @@ If the knowledge sounds like a rule (imperative, always/never, convention):
   Claude will see this at the start of every session in this project.
 ```
 
-## What NOT to use /si:remember for
+## What NOT to use /self-improving-agent remember for
 
 - **Temporary context**: Use session memory or just tell Claude in conversation
-- **Enforced rules**: Use `/si:promote` to write directly to CLAUDE.md
+- **Enforced rules**: Use `/self-improving-agent promote` to write directly to CLAUDE.md
 - **Cross-project knowledge**: Use `~/.claude/CLAUDE.md` for global rules
 - **Sensitive data**: Never store credentials, tokens, or secrets in memory files
 

package/skills/self-improving-agent/skills/review/SKILL.md

@@ -7,17 +7,17 @@ user-invocable: false
 allowed-tools: Read, Glob, Grep, Bash
 ---
 
-# /si:review — Analyze Auto-Memory
+# /self-improving-agent review — Analyze Auto-Memory
 
 Performs a comprehensive audit of Claude Code's auto-memory and produces actionable recommendations.
 
 ## Usage
 
 ```
-/si:review                    # Full review
-/si:review --quick            # Summary only (counts + top 3 candidates)
-/si:review --stale            # Focus on stale/outdated entries
-/si:review --candidates       # Show only promotion candidates
+/self-improving-agent review                    # Full review
+/self-improving-agent review --quick            # Summary only (counts + top 3 candidates)
+/self-improving-agent review --stale            # Focus on stale/outdated entries
+/self-improving-agent review --candidates       # Show only promotion candidates
 ```
 
 ## What It Does
@@ -117,14 +117,14 @@ Memory Health:
 ## When to Use
 
 - After completing a major feature or debugging session
-- When `/si:status` shows MEMORY.md is over 150 lines
+- When `/self-improving-agent status` shows MEMORY.md is over 150 lines
 - Weekly during active development
 - Before starting a new project phase
 - After onboarding a new team member (review what Claude learned)
 
 ## Tips
 
-- Run `/si:review --quick` frequently (low overhead)
+- Run `/self-improving-agent review --quick` frequently (low overhead)
 - Full review is most valuable when MEMORY.md is getting crowded
 - Act on promotion candidates promptly — they're proven patterns
 - Don't hesitate to delete stale entries — auto-memory will re-learn if needed

package/skills/self-improving-agent/skills/status/SKILL.md

@@ -7,15 +7,15 @@ user-invocable: false
 allowed-tools: Read, Glob, Grep, Bash
 ---
 
-# /si:status — Memory Health Dashboard
+# /self-improving-agent status — Memory Health Dashboard
 
 Quick overview of your project's memory state across all memory systems.
 
 ## Usage
 
 ```
-/si:status                    # Full dashboard
-/si:status --brief            # One-line summary
+/self-improving-agent status                    # Full dashboard
+/self-improving-agent status --brief            # One-line summary
 ```
 
 ## What It Reports
@@ -88,7 +88,7 @@ done
 ### Brief mode
 
 ```
-/si:status --brief
+/self-improving-agent status --brief
 ```
 
 Output: `📊 Memory: {{n}}/200 lines | {{count}} rules | {{status_emoji}} {{status_word}}`
@@ -96,12 +96,12 @@ Output: `📊 Memory: {{n}}/200 lines | {{count}} rules | {{status_emoji}} {{sta
 ## Interpretation
 
 - **Green (< 60%)**: Plenty of room. Auto-memory is working well.
-- **Yellow (60-90%)**: Getting full. Consider running `/si:review` to promote or clean up.
-- **Red (> 90%)**: Near capacity. Auto-memory may start dropping older entries. Run `/si:review` now.
+- **Yellow (60-90%)**: Getting full. Consider running `/self-improving-agent review` to promote or clean up.
+- **Red (> 90%)**: Near capacity. Auto-memory may start dropping older entries. Run `/self-improving-agent review` now.
 
 ## Tips
 
-- Run `/si:status --brief` as a quick check anytime
-- If capacity is yellow+, run `/si:review` to identify promotion candidates
+- Run `/self-improving-agent status --brief` as a quick check anytime
+- If capacity is yellow+, run `/self-improving-agent review` to identify promotion candidates
 - Stale entries waste space — delete references to files that no longer exist
 - Topic files are fine — Claude creates them to keep MEMORY.md under 200 lines

package/skills/senior-ml-engineer/references/llm_integration_guide.md

@@ -47,13 +47,14 @@ class OpenAIProvider(LLMProvider):
         return response.choices[0].text
 
 class AnthropicProvider(LLMProvider):
-    def __init__(self, api_key: str, model: str = "claude-3-opus"):
+    def __init__(self, api_key: str, model: str = "claude-opus-5-5"):
         self.client = Anthropic(api_key=api_key)
         self.model = model
 
     def chat(self, messages: List[Dict], **kwargs) -> str:
         response = self.client.messages.create(
             model=self.model,
+            max_tokens=kwargs.pop("max_tokens", 16000),
             messages=messages,
             **kwargs
         )
@@ -97,7 +98,7 @@ def call_with_fallback(
 |---------|----------|-----------|
 | Zero-shot | Simple tasks | Task description + input |
 | Few-shot | Complex tasks | Examples + task + input |
-| Chain-of-thought | Reasoning | "Think step by step" + task |
+| Reasoning | Multi-step problems | On models with adaptive thinking, raise `effort` instead of asking for step-by-step text |
 | Role-based | Specialized output | System role + task |
 
 ### Few-Shot Template
@@ -178,10 +179,8 @@ def truncate_to_token_limit(text: str, max_tokens: int, model: str = "gpt-4") ->
 
 | Model | Context Window | Effective Limit |
 |-------|----------------|-----------------|
-| GPT-4 | 8,192 | ~6,000 (leave room for response) |
-| GPT-4-32k | 32,768 | ~28,000 |
-| Claude 3 | 200,000 | ~180,000 |
-| Llama 3 | 8,192 | ~6,000 |
+| Claude Opus 5.5 / Sonnet 5.5 / Haiku 5.5 | 1,000,000 | leave room for `max_tokens` |
+| Other providers | check the provider's model docs | context windows change every release |
 
 ### Chunking Strategy
 
@@ -206,12 +205,7 @@ def chunk_text(text: str, chunk_size: int = 1000, overlap: int = 100) -> List[st
 
 ### Cost Calculation
 
-| Provider | Input Cost | Output Cost | Example (1K tokens) |
-|----------|------------|-------------|---------------------|
-| GPT-4 | $0.03/1K | $0.06/1K | $0.09 |
-| GPT-3.5 | $0.0005/1K | $0.0015/1K | $0.002 |
-| Claude 3 Opus | $0.015/1K | $0.075/1K | $0.09 |
-| Claude 3 Haiku | $0.00025/1K | $0.00125/1K | $0.0015 |
+Prices change with every model release, so keep them out of code: read them from config, and take the numbers from each provider's pricing page. Count tokens with the provider's response metadata (`usage`), not with a character estimate.
 
 ### Cost Tracking
 
@@ -229,30 +223,19 @@ class LLMUsage:
 def calculate_cost(
     input_tokens: int,
     output_tokens: int,
-    model: str
+    prices: dict,
 ) -> float:
-    """Calculate cost based on token usage."""
-    PRICING = {
-        "gpt-4": {"input": 0.03, "output": 0.06},
-        "gpt-3.5-turbo": {"input": 0.0005, "output": 0.0015},
-        "claude-3-opus": {"input": 0.015, "output": 0.075},
-    }
-
-    prices = PRICING.get(model, {"input": 0.01, "output": 0.03})
-
-    input_cost = (input_tokens / 1000) * prices["input"]
-    output_cost = (output_tokens / 1000) * prices["output"]
-
-    return input_cost + output_cost
+    """Cost in USD. `prices` comes from config: {"input": usd_per_mtok, "output": usd_per_mtok}."""
+    return (input_tokens * prices["input"] + output_tokens * prices["output"]) / 1_000_000
 ```
 
 ### Cost Optimization Strategies
 
-1. **Use smaller models for simple tasks** - GPT-3.5 for classification, GPT-4 for reasoning
-2. **Cache common responses** - Store results for repeated queries
-3. **Batch requests** - Combine multiple items in single prompt
-4. **Truncate context** - Only include relevant information
-5. **Set max_tokens limit** - Prevent runaway responses
+1. **Use a smaller model where it holds quality** - measure on real requests before routing a task to it
+2. **Cache repeated context** - provider prompt caching makes a stable system prompt or document far cheaper on repeat calls
+3. **Batch non-urgent work** - batch APIs trade latency for a lower price
+4. **Cache common responses** - store results for repeated queries
+5. **Set max_tokens deliberately** - high enough not to cut answers off, as a ceiling on runaway output
 
 ---
 

package/skills/senior-prompt-engineer/SKILL.md

@@ -23,12 +23,12 @@ python scripts/agent_orchestrator.py agent_config.yaml --visualize       # Visua
 
 ### 1. Prompt Optimizer
 
-Analyzes prompts for token efficiency, clarity, and structure. Generates optimized versions.
+Static checks for clarity and structure, with an approximate token count (characters / 4). `--optimize` only normalizes whitespace; the real rewrite is yours.
 
 ```bash
 python scripts/prompt_optimizer.py prompt.txt --analyze          # Full analysis
-python scripts/prompt_optimizer.py prompt.txt --optimize         # Generate optimized version
-python scripts/prompt_optimizer.py prompt.txt --tokens --model gpt-4  # Token count
+python scripts/prompt_optimizer.py prompt.txt --optimize         # Normalize whitespace
+python scripts/prompt_optimizer.py prompt.txt --tokens           # Approximate token count
 python scripts/prompt_optimizer.py prompt.txt --extract-examples --output examples.json
 ```
 
@@ -50,7 +50,7 @@ Parses agent definitions and visualizes execution flows. Validates tool configur
 python scripts/agent_orchestrator.py agent.yaml --validate       # Validate config
 python scripts/agent_orchestrator.py agent.yaml --visualize      # Show workflow (ASCII)
 python scripts/agent_orchestrator.py agent.yaml --visualize --format mermaid  # Mermaid
-python scripts/agent_orchestrator.py agent.yaml --estimate-cost  # Token estimation
+python scripts/agent_orchestrator.py agent.yaml --estimate-cost --price-in 4 --price-out 20  # Tokens; dollars with your current prices (USD/Mtok)
 ```
 
 ## Prompt Engineering Workflows
@@ -65,7 +65,7 @@ python scripts/agent_orchestrator.py agent.yaml --estimate-cost  # Token estimat
 |-------|---------|
 | Ambiguous output | Add explicit format specification |
 | Too verbose | Extract to few-shot examples |
-| Inconsistent results | Add role/persona framing |
+| Inconsistent results | Add 2-3 varied examples and state the success criteria |
 | Missing edge cases | Add constraint boundaries |
 
 4. **Optimize**: `python scripts/prompt_optimizer.py current_prompt.txt --optimize --output optimized.txt`
@@ -77,15 +77,15 @@ python scripts/agent_orchestrator.py agent.yaml --estimate-cost  # Token estimat
 1. Define task clearly (input format, output format)
 2. Select 3-5 diverse examples: simple case, edge case, complex case, negative case
 3. Format consistently
-4. Validate: `python scripts/prompt_optimizer.py prompt_with_examples.txt --validate-examples`
+4. Check what the prompt contains: `python scripts/prompt_optimizer.py prompt_with_examples.txt --extract-examples`
 5. Test with held-out cases
 
 ### Structured Output Design
 
 1. Define JSON/XML schema with types, constraints, enums
-2. Include schema description in prompt
-3. Add format enforcement: "Respond ONLY with valid JSON. Start with { and end with }"
-4. Validate: `python scripts/prompt_optimizer.py structured_prompt.txt --validate-schema schema.json`
+2. Pass the schema through the API's structured outputs (`output_config.format` on Claude) so the response is guaranteed to match it; do not rely on "respond ONLY with valid JSON" in the prompt
+3. Describe in the prompt what each field means, not the JSON syntax
+4. Validate the parsed result against the schema in code before using it
 
 ## Reference Documentation
 
@@ -103,6 +103,6 @@ python scripts/agent_orchestrator.py agent.yaml --estimate-cost  # Token estimat
 |---------|-------------|---------|
 | **Zero-shot** | Simple, well-defined tasks | "Classify this email as spam or not spam" |
 | **Few-shot** | Complex tasks, consistent format | Provide 3-5 examples before task |
-| **Chain-of-Thought** | Reasoning, math, multi-step | "Think step by step..." |
+| **Reasoning depth** | Reasoning, math, multi-step | Models with adaptive thinking: raise `effort`. Models without it: "Think step by step..." |
 | **Role Prompting** | Expertise, specific perspective | "You are an expert tax accountant..." |
 | **Structured Output** | Need parseable JSON/XML | Include schema + format enforcement |

package/skills/senior-prompt-engineer/references/prompt_engineering_patterns.md

@@ -164,7 +164,7 @@ The 7 apples cost $11.20
 | Reasoning chain | "Explain your reasoning" | Justification needed |
 
 **Zero-shot CoT:**
-Simply append "Let's think step by step." to any prompt.
+Append "Let's think step by step." only on models without built-in thinking. On models with adaptive thinking, control depth with `effort`; asking for the reasoning in the output can be declined as reasoning extraction.
 
 ---