Skip to main content
skill CX Codex

automatic-stateful-prompt-improver — Claude Code skill: install

automatic-stateful-prompt-improver intercepts complex prompts to refine them via DSPy, APE, and OPRO techniques. Stores optimization outcomes in an MCP server to learn across sessions.

MIT 207 installs ★ 274 updated 2026-10-30

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add curiositech/some_claude_skills --skill automatic-stateful-prompt-improver -a claude-code
Open on GitHub

What automatic-stateful-prompt-improver does

The skill captures complex requests, code generation tasks, and ambiguous requirements before execution. It runs input text through mcp__prompt-learning__optimize_prompt using 3 to 20 iterations depending on complexity. Conversational greetings, single-step file actions, and terminal commands like npm install remain untouched.

Once the primary task finishes, the skill assesses output quality and invokes record_feedback with a score from 0.0 to 1.0. This feedback loop indexes successful prompt variants through embeddings. Iteration stops automatically when improvement drops below 1% across 3 cycles or when the validation score reaches 0.95.

A configured prompt-learning MCP server is strictly mandatory. Without this external service, none of the optimization or feedback tools can run.

What it helps with

  • Refine ambiguous instructions for multistep reasoning tasks
  • Store historical prompt variations indexed by embeddings
  • Record execution scores from 0.0 to 1.0 into the MCP database
  • Prevent unnecessary token spend by halting iterations when gains drop under 1%

Example prompts for the agent

  • Optimize this prompt for financial report generation
  • Refine my request before running the data pipeline
  • Improve this system instruction for parsing source code

How to install automatic-stateful-prompt-improver

1Skills CLI (Vercel)

npx skills add curiositech/some_claude_skills --skill automatic-stateful-prompt-improver -a claude-code

2Manually: put the files in place

~/.claude/skills/automatic-stateful-prompt-improver/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/automatic-stateful-prompt-improver/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about automatic-stateful-prompt-improver

How to install automatic-stateful-prompt-improver in Claude Code?

Run npx skills add curiositech/some_claude_skills --skill automatic-stateful-prompt-improver -a claude-code in your terminal.

Which requests does the skill skip?

It skips direct CLI commands, greetings, simple definitions, and routine file actions that do not require reasoning.

What dependencies does this skill require?

You need an active prompt-learning MCP server. The skill relies directly on its tools for optimization, metric logging, and analytics.

Source text

SKILL.md · MIT
---
name: automatic-stateful-prompt-improver
description: Automatically intercepts and optimizes prompts using the prompt-learning MCP server. Learns from performance over time via embedding-indexed history. Uses APE, OPRO, DSPy patterns. Activate
  on "optimize prompt", "improve this prompt", "prompt engineering", or ANY complex task request. Requires prompt-learning MCP server. NOT for simple questions (just answer them), NOT for direct commands
  (just execute them), NOT for conversational responses (no optimization needed).
allowed-tools: mcp__prompt-learning__optimize_prompt,mcp__prompt-learning__retrieve_prompts,mcp__prompt-learning__record_feedback,mcp__prompt-learning__suggest_improvements,mcp__prompt-learning__get_analytics,mcp__SequentialThinking__sequentialthinking
metadata:
  category: AI & Machine Learning
  pairs-with:
  - skill: skill-coach
    reason: Optimize skill prompts systematically
  - skill: skill-logger
    reason: Track prompt performance over time
  tags:
  - prompts
  - optimization
  - learning
  - embeddings
  - dspy
---

# Automatic Stateful Prompt Improver

## MANDATORY AUTOMATIC BEHAVIOR

**When this skill is active, I MUST follow these rules:**

### Auto-Optimization Triggers

I AUTOMATICALLY call `mcp__prompt-learning__optimize_prompt` BEFORE responding when:

1. **Complex task** (multi-step, requires reasoning)
2. **Technical output** (code, analysis, structured data)
3. **Reusable content** (system prompts, templates, instructions)
4. **Explicit request** ("improve", "better", "optimize")
5. **Ambiguous requirements** (underspecified, multiple interpretations)
6. **Precision-critical** (code, legal, medical, financial)

### Auto-Optimization Process

```
1. INTERCEPT the user's request
2. CALL: mcp__prompt-learning__optimize_prompt
   - prompt: [user's original request]
   - domain: [inferred domain]
   - max_iterations: [3-20 based on complexity]
3. RECEIVE: optimized prompt + improvement details
4. INFORM user briefly: "I've refined your request for [reason]"
5. PROCEED with the OPTIMIZED version
```

### Do NOT Optimize

- Simple questions ("what is X?")
- Direct commands ("run npm install")
- Conversational responses ("hello", "thanks")
- File operations without reasoning
- Already-optimized prompts

## Learning Loop (Post-Response)

After completing ANY significant task:

```
1. ASSESS: Did the response achieve the goal?
2. CALL: mcp__prompt-learning__record_feedback
   - prompt_id: [from optimization response]
   - success: [true/false]
   - quality_score: [0.0-1.0]
3. This enables future retrievals to learn from outcomes
```

## Quick Reference

### Iteration Decision

| Factor | Low (3-5) | Medium (5-10) | High (10-20) |
|--------|-----------|---------------|--------------|
| Complexity | Simple | Multi-step | Agent/pipeline |
| Ambiguity | Clear | Some | Underspecified |
| Domain | Known | Moderate | Novel |
| Stakes | Low | Moderate | Critical |

### Convergence (When to Stop)

- Improvement < 1% for 3 iterations
- User satisfied
- Token budget exhausted
- 20 iterations reached
- Validation score > 0.95

### Performance Expectations

| Scenario | Improvement | Iterations |
|----------|-------------|------------|
| Simple task | 10-20% | 3-5 |
| Complex reasoning | 20-40% | 10-15 |
| Agent/pipeline | 30-50% | 15-20 |
| With history | +10-15% bonus | Varies |

## Anti-Patterns

### Over-Optimization

| What it looks like | Why it's wrong |
|--------------------|----------------|
| Prompt becomes overly complex with many constraints | Causes brittleness, model confusion, token waste |
| **Instead**: Apply Occam's Razor - simplest sufficient prompt wins |

### Template Obsession

| What it looks like | Why it's wrong |
|--------------------|----------------|
| Focusing on templates rather than task understanding | Templates don't generalize; understanding does |
| **Instead**: Focus on WHAT the task requires, not HOW to format it |

### Iteration Without Measurement

| What it looks like | Why it's wrong |
|--------------------|----------------|
| Multiple rewrites without tracking improvements | Can't know if changes help without metrics |
| **Instead**: Always define success criteria before optimizing |

### Ignoring Model Capabilities

| What it looks like | Why it's wrong |
|--------------------|----------------|
| Assumes model can't do things it can | Over-scaffolding wastes tokens |
| **Instead**: Test capabilities before heavy prompting |

## Reference Files

Load for detailed implementations:

| File | Contents |
|------|----------|
| `references/optimization-techniques.md` | APE, OPRO, CoT, instruction rewriting, constraint engineering |
| `references/learning-architecture.md` | Warm start, embedding retrieval, MCP setup, drift detection |
| `references/iteration-strategy.md` | Decision matrices, complexity scoring, convergence algorithms |

---

**Goal**: Simplest prompt that achieves the outcome reliably. Optimize for clarity, specificity, and measurable improvement.

© curiositech · MIT · curiositech/some_claude_skills

Similar skills

All skills for AI and ML →

From the same set180

The whole set →
test-automation-expert test-automation-expert — a test automation skill that covers strategy, framework setup, coverage gaps and flaky test debugging. Useful when a project needs tests from scratch or existing ones keep breaking. CX Codex +1 212installs very-long-text-summarization very-long-text-summarization — a Claude Code skill that digests books, handbooks and large codebases with hierarchical multi-pass extraction. It outputs a structured knowledge map, not a plain compressed retelling. CX Codex +1 210installs rest-api-design The rest-api-design skill guides REST endpoint design with Zod validation and OpenAPI docs. Use it when adding routes to a Next.js App Router project. CX Codex +1 209installs modern-auth-2026 modern-auth-2026 adds passwordless authentication patterns to your agent: WebAuthn passkeys, Google and Apple OAuth, magic links, and cross-device sync. CX Codex +1 208installs skill-coach skill-coach helps build and audit Agent Skills by checking activation, expert guidance, anti-patterns, and progressive disclosure. CX Codex +1 207installs maximalist-wall-decorator maximalist-wall-decorator guides bold interior wall decoration, gallery walls, and freehand paint techniques. Built for maximalist spaces embracing the "more is more" philosophy. CX Codex +1 206installs ai-engineer ai-engineer — a skill that steers the agent while you build LLM applications: RAG pipelines, chatbots, multi-agent systems. It acts as an instruction layer with architecture patterns. CX Codex +1 206installs research-analyst research-analyst is a Claude Code skill for market research, competitive analysis, and methodology evaluation. It delivers reasoned recommendations with cited sources. CX Codex +1 206installs

Project sponsors

Companies that keep this analytics open