# Sk Prompt

> Prompt engineering: turns a request into a structured, checked AI prompt, with a component skeleton and CLEAR screening.

- Skill: `michelkerkmeester/sk-prompt` (Agent Skill, multi-file: 111 files)
- Install (CLI): `npx get-skill add michelkerkmeester/sk-prompt`
- Raw SKILL.md: https://api.skillmd.com/api/skills/michelkerkmeester/sk-prompt/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: MichelKerkmeester (https://skillmd.com/u/michelkerkmeester)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/michelkerkmeester/sk-prompt

---


<!-- Keywords: prompt-engineering, prompt-improvement, improve prompt, improve this prompt, improve the prompt, enhance prompt, prompt improvement, improvement-checklist, early-exit, CLEAR-scoring, framework-selection, RCAF, COSTAR, CRAFT, TIDD-EC, CRISPE -->

# Prompt Engineering Specialist - One-Pass Prompt Improvement

Transforms vague or basic inputs into structured AI prompts in one pass: a ten-row checklist, one component skeleton with optional framework presets, and CLEAR screening.

**Core Principle**: Clarity, logic, expression, and reliability through structured methodology.

---

## 1. WHEN TO USE

### Activation Triggers

**Use when**:
- Enhancing or improving an AI prompt for any purpose
- Evaluating prompt quality with CLEAR scoring
- Selecting the right prompt framework for a given task
- Transforming vague requests into structured, effective prompts
- Supporting indirect invocation from `@prompt-improver` agent dispatches (the deep-path escalation target for CLI fast-path prompt cards)

**Keyword Triggers**:
- `$improve`, `$text`, `$short`, `$refine`, `$json`, `$yaml`
- `$raw` (no checklist pass, fast pass-through)
- "improve my prompt", "enhance this prompt", "prompt engineering"
- "create a prompt for", "optimize this prompt"

### Use Cases

#### Text Prompt Enhancement
Transform vague requests into structured prompts from one default skeleton, with RCAF, COSTAR, RACE, CIDI, TIDD-EC, CRISPE or CRAFT as optional presets, and CLEAR screening (40+/50 threshold).

#### Design-Generation Prompt
Construct a grounded, anti-default generation brief for a design-generation run. This skill owns the prompt only, never the measured design-reference extraction (`sk-design-md-generator`) or the run transport.

### When NOT to Use

**Skip this skill when:**
- Writing code or debugging (use sk-code skills instead)
- Creating documentation (use sk-doc instead)
- Simple text editing without prompt structure needs
- Direct API calls that do not need prompt optimization

---

## 2. SMART ROUTING

The `$improve`, `$text`, `$refine`, `$short`, `$json`, `$yaml` and `$raw` prefixes select this skill, and so does a request to improve, enhance, score or restructure a prompt.
The prefix is authoritative: it fixes the operating mode, and the intent scores the router computes never change it.
With no prefix, weighted keyword scoring picks the top intent, or the top two when their scores sit within `AMBIGUITY_DELTA`.
A zero score falls back to `TEXT_ENHANCE` with the disambiguation checklist rather than guessing.

`references/improvement-checklist.md` loads first on every run except `$raw` and the `FRAMEWORK` intent, and `references/patterns-evaluation.md` joins it for the text, design-generation, Markdown, JSON and YAML intents.
On `FRAMEWORK` it replaces the checklist default instead of joining it.
The `DESIGN_GEN` intent loads `references/patterns-evaluation.md`, the framework library and the CLEAR rubric, so the brief is built from a named framework rather than a design-specific reference this skill does not ship.
Read [`ROUTER.md`](./ROUTER.md) before selecting skill-local resources.
Open only the matched files.

---

## 3. HOW IT WORKS

### Enhancement Pipeline

Every improvement runs one pass, described in [improvement-checklist.md](./references/improvement-checklist.md):

1. Detect the mode from the command token or the user's own words. A pasted prompt is set aside before routing, so text inside it never picks the mode.
2. Check the prompt once against the ten checklist rows, marking each present, absent or not needed with a reason. A prompt that passes exits early, unchanged or minimally edited.
3. Write the prompt from the default component skeleton, applying a framework preset only when the request names one or its fit is clear from the task.
4. Self-check once against the success criteria, run the quick test when the effort level calls for it, and screen with CLEAR.
5. Deliver the prompt first, then the numbered open items and the change report.

See the Smart Router Pseudocode in `ROUTER.md` for the complete routing logic.

### Operating Modes

| Mode | Command | Effort | Scoring | Use Case |
|------|---------|--------|---------|----------|
| Interactive | (default) | standard | CLEAR | Guided enhancement |
| Text | `$text` | standard | CLEAR | Standard text prompt |
| Short | `$short` | quick | CLEAR | Quick refinement |
| Improve | `$improve` | standard | CLEAR | Standard enhancement |
| Refine | `$refine` | thorough | CLEAR | Maximum optimization |
| JSON | `$json` | standard | CLEAR | API-ready format |
| YAML | `$yaml` | standard | CLEAR | Config format |
| Raw | `$raw` | none | None | No checklist pass |

### Framework Presets

Every prompt starts from one default skeleton: task, context, constraints, output format, optional examples and success criteria. The seven framework names stay as optional presets. Apply one only when the user or caller names it, or when its fit is clear from the task; the table shows where each fits.

| Preset | Fits when |
|--------|-----------|
| RACE | Urgent tasks and quick iterations |
| RCAF | General tasks that need a clear role and format |
| COSTAR | Content where style, tone and audience matter |
| CIDI | Process documentation and tutorials |
| CRISPE | Strategy and exploration |
| TIDD-EC | Quality-critical or compliance work that needs do's, don'ts and examples |
| CRAFT | Complex projects and planning |

See [patterns-evaluation.md](./references/patterns-evaluation.md) for complete framework details.

### Scoring Systems

**CLEAR** (50-point scale): Correctness (10) + Logic (10) + Expression (15) + Arrangement (10) + Reusability (5). Threshold: 40+. CLEAR is a structural screen, not proof the prompt works; repair up to 3 cycles.

---

## 4. RULES

### ✅ ALWAYS

1. **ALWAYS deliver first**
   - A request that carries a prompt or a task gets the improved prompt in the same reply
   - List every default and assumption as a numbered open item after the prompt, never inside it
   - Ask one question only when there is no prompt and no task, or when two mode commands conflict; `$raw` never asks

2. **ALWAYS run the one-pass checklist** at the detected effort level
   - Quick for `$short`, standard by default, thorough for `$refine`, none for `$raw`
   - Mark each row present, absent or not needed with a one-line reason

3. **ALWAYS exit early on a prompt that already passes**
   - Return it unchanged or with the smallest edit asked for, and say so

4. **ALWAYS route on the user's own words**
   - Set a pasted prompt aside before detecting the mode

5. **ALWAYS screen with CLEAR** before delivery
   - Write the reason before each score; pass at 40/50; repair up to 3 cycles

6. **ALWAYS end with a change report**
   - Added, Changed, Removed, Skipped, plus `Quick test: NOT RUN` when the test did not run

### ⛔ NEVER

1. **NEVER stall on questions**
   - Deliver first: write from stated defaults and list each assumption as a numbered open item; ask one question only when there is no prompt and no task, or two mode commands conflict, and then wait for the answer

2. **NEVER force a framework preset**
   - Use the default skeleton unless the request names a preset or its fit is clear

3. **NEVER deliver without scoring**
   - Every improved prompt carries a CLEAR screen (except $raw)

4. **NEVER write the enhanced prompt in the operator's voice**
   - Address the executing model: the role line in the second person ("You are..."), task steps in the imperative

5. **NEVER exceed context with full reference loading**
   - Load only the references needed for the detected mode

6. **NEVER rewrite user guidelines or examples needlessly**
   - Preserve them as closely as possible, word for word when asked; warn when the prompt grows past about 3 times the original

### ⚠️ ESCALATE IF

1. **ESCALATE IF there is no prompt and no task, or two mode commands conflict**
   - Ask one question, such as "Which mode do you want: $raw or $text?"; any other uncertainty is delivered with the assumption as open item 1

2. **ESCALATE IF CLEAR score stays below threshold after 3 repair cycles**
   - Deliver the best version with a note naming the weakest dimension

3. **ESCALATE IF request conflicts with prompt engineering scope**
   - Redirect: "This appears to be a [code/doc/debug] task. Consider using [sk-code/sk-doc] instead."

---

## 5. REFERENCES

### Core References

- [improvement-checklist.md](./references/improvement-checklist.md) - One-pass checklist, early exit, effort levels, self-check, quick test and change report
- [patterns-evaluation.md](./references/patterns-evaluation.md) - default skeleton, seven framework presets, CLEAR scoring (canonical rubric)

### Asset Files

- [format-guide-markdown.md](./assets/format-guide-markdown.md) - Markdown format deep-dive: fundamentals, delivery standards, RCAF/CRAFT structures, advanced patterns, validation, best practices
- [format-guide-json.md](./assets/format-guide-json.md) - JSON format deep-dive: fundamentals, data types, delivery standards, RCAF/CRAFT structures, advanced patterns, validation, best practices
- [format-guide-yaml.md](./assets/format-guide-yaml.md) - YAML format deep-dive: fundamentals, data types, delivery standards, RCAF/CRAFT structures, advanced patterns, templates, validation, best practices
- [cli-prompt-quality-card.md](./assets/cli-prompt-quality-card.md) - CLI fast-path card: the framework selection table, the CLEAR pre-dispatch check and the escalation triggers the `cli-*` packets delegate to
- [framework-registry.json](./assets/framework-registry.json) - Machine-readable scaffold registry with code-oriented slot templates for a subset of five frameworks

### Reference Loading Notes

- Load only references needed for current intent
- Smart Routing in `ROUTER.md` is the single authority for loading rules
- SKILL.md (this file) is always loaded; conditionally load mode-specific references

---

## 6. SUCCESS CRITERIA

### Enhancement Complete When

- ✅ Mode detected from the user's own words, effort level set
- ✅ Checklist pass recorded, or early exit stated
- ✅ CLEAR screen applied and threshold met, or best version delivered with a note
- ✅ Prompt delivered first, with open items and the change report
- ✅ User can iterate or accept

### Quality Targets

- **CLEAR Score**: 40+ out of 50
- **Early exit**: a prompt that already passes the checklist comes back unchanged or minimally edited

---

## 7. AGENT INVOCATION CONTRACT

`@prompt-improver` is the fresh-context escalation surface for this skill. The agent loads the references in this skill, applies the same framework-selection and CLEAR rules, and returns a structured block that the caller can inject into a CLI dispatch without loading the full skill inline.

### Expected Input Payload

| Field | Required | Description |
|-------|----------|-------------|
| `raw_task` | Yes | Raw task description or draft prompt to improve |
| `task_type` | No | One of `generation`, `review`, `research`, `edit`, `analyze` |
| `target_cli` | No | One of `claude-code`, `opencode`, `copilot` |
| `complexity_hint` | No | Integer `1-10` mapped to effort: 1-3 quick, 4-7 standard, 8-10 thorough |
| `constraints` | No | Compliance, security, audience, or output requirements |

### Model Eligibility

Dispatch `@prompt-improver`, or run this skill inline, only on an eligible (model, route) pair. Eligibility is a property of the (model, route) pair, never of the model alone.

| Route | Model | Eligible | Note |
|-------|-------|----------|------|
| any route | Opus | No | Denied under no circumstances |
| any route | Fable | No | Denied under no circumstances |
| native Claude | Sonnet | Yes | — |
| native Claude | Haiku | Yes | — |
| `cli-claude-code` | Sonnet | Yes | — |
| `cli-claude-code` | Haiku | Yes | — |
| `cli-codex` | GPT Luna | Yes | — |
| `cli-pi` | any model except Luna | Yes | — |
| `cli-opencode` | any model except Luna | Yes | — |
| `cli-deepseek-harness` | DeepSeek V4.1 Flash through the LLM Gateway or OpenCode Go route patch | No | Experimental mode: no pair is admitted yet. The LLM Gateway route answered a keyed run on 2026-11-06 and OpenCode Go answered one on 2026-11-07. The roster is closed at these two routes, and neither is Luna, Opus or Fable |
| `cli-mistral-vibe` | DeepSeek V4.1 Flash or GLM Flash through the `mistral` provider roster | No | Experimental mode: no pair is admitted yet. Print mode is pinned on `vibe 3.1.2`, the roster is closed at `deepseek-flash` and `glm-flash`, and neither is Luna, Opus or Fable |
| `cli-pi` or `cli-opencode` | Luna | No | Intentional asymmetry: Luna is eligible through `cli-codex` only |

The denied list outranks the allowance list: Opus and Fable stay denied even where an allowance clause would otherwise admit them, such as Opus reached through `cli-opencode`.

The Luna asymmetry is intentional: Luna is eligible through `cli-codex` and not eligible through `cli-pi` or `cli-opencode`; do not "correct" it.

The allowance list is closed (default-deny). A pair that matches no allowance clause is not eligible; for example, Gemini reached through `cli-cursor` is not eligible.

An ineligible model must refuse the prompt-improve work, name the rule that denied it, and name an eligible (model, route) pair in its place, whether it was reached through this skill inline or through the agent. It must not do the work anyway with a caveat.

The route list above is a list of executors. The `cli-jev` transport, mode `cli-jev` of the `cli-classifier` hub, is deliberately absent: it answers one typed judgment and runs nothing, so no prompt-improvement task can be dispatched to it and it needs no eligibility row.

This table is the canonical home of the contract, so future edits land in one place. The dispatcher owns the choice: the `/prompt:improve` workflow dispatches `@prompt-improver` with `model=sonnet`, and the Claude Code copy of the agent pins `model: sonnet`. The agent keeps only a backstop that points here.

### Deterministic Agent Rules

- Use `references/improvement-checklist.md` for the one-pass checklist, effort levels, quick test and change report.
- Use `references/patterns-evaluation.md` for the default skeleton and presets: read `## 2. FRAMEWORK LIBRARY & SELECTION`, a named preset's subsection of `## 3. FRAMEWORK DEEP DIVES`, and `## 10. CLEAR EVALUATION MASTERY`, the one CLEAR rubric. An on-demand keyword reads the whole file.
- Map `complexity_hint` onto effort as the payload table says; with no hint, use standard.
- Require `CLEAR >= 40/50` before returning success.
- If the screen scores below threshold, repair up to 3 cycles, then return the best version with explicit escalation notes.

### Structured Output Block

```text
FRAMEWORK: <default skeleton | preset name>
CLEAR_SCORE: <n>/50 (C:<n> L:<n> E:<n> A:<n> R:<n>)
TEST: NOT RUN
CHANGES: <Added ...; Changed ...; Removed ...; Skipped ...>
RATIONALE: <1-2 lines>
ENHANCED_PROMPT: |
  <multi-line ready-to-dispatch prompt>
ESCALATION_NOTES: <remaining ambiguity, risk, or follow-up>
```

### Contract Guarantees

- The returned prompt is ready for CLI handoff without another pass.
- The output preserves caller-supplied constraints unless the agent flags them as contradictory or underspecified.
- The agent remains read-only and leaf-only; it does not write files or spawn other sub-agents.

---

## 8. INTEGRATION POINTS

### Framework Integration

This skill operates within the behavioral framework defined in AGENTS.md.

Key integrations:
- **Gate 2**: Skill routing via `.skilled/bin/skill-advisor.cjs` with prompt-related intent boosters
- **Tool Routing**: Per AGENTS.md Section 5 decision tree
- **Continuity**: Context preserved by `/speckit:save`, which writes through `generate-context.js`

### Tool Usage Guidelines

- **Read**: Load reference files from references/ directory
- **Write**: Output enhanced prompts to user-specified location
- **Glob**: Discover available reference files in skill directory
- **Bash**: Run validation scripts if needed

---

## 9. REFERENCES AND RELATED RESOURCES

The router discovers reference, asset, and script docs dynamically. Start with `references/improvement-checklist.md`, `references/patterns-evaluation.md`, `assets/format-guide-json.md`, `assets/format-guide-markdown.md`, `assets/format-guide-yaml.md`, `assets/cli-prompt-quality-card.md`, then load task-specific resources from `references/`, templates from `assets/`, and automation from `scripts/` when present.

### RELATED PLAYBOOK

Manual validation lives at `manual-testing-playbook/manual-testing-playbook.md`.

Related skills: `sk-doc` for documentation outputs, `sk-code` for code-generation prompt context, and the `cli-*` skills that use the prompt quality card before dispatch.

