Sk Prompt

---
name: sk-prompt
description: "Prompt engineering: transforms a request into a structured, scored AI prompt via 7 frameworks, DEPTH thinking and CLEAR scoring."
allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]
version: 3.0.2.0
---

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

# Prompt Engineering Specialist - Multi-Framework Enhancement with DEPTH Processing

Transforms vague or basic inputs into highly effective, structured AI prompts. Provides 7 text frameworks with automatic framework selection and CLEAR quality scoring.

**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` (skip DEPTH, 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 using RCAF, COSTAR, RACE, CIDI, TIDD-EC, CRISPE, or CRAFT frameworks with CLEAR scoring (40+/50 threshold).

#### Design-Generation Prompt
Construct a grounded, anti-default generation brief for a design-generation run. Covers the brief shape, the String Seed of Thought anti-median variation technique, pre-answering a multi-turn discovery form, and the handoff to `sk-code`. 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


<!-- CRITICAL: Keep one authoritative Smart Router Pseudocode block in this section.
     Detection context may appear before pseudocode. Do NOT duplicate routing logic in separate lookup tables. -->

### Primary Detection Signal

The primary routing signal is the **command prefix** (`$improve`, `$text`, `$refine`, `$short`, `$json`, `$yaml`, `$raw`). When present, the prefix determines the operating mode directly. When absent, the router falls back to **keyword-weighted intent scoring** against the request text, selecting the top-scoring intent (or top-2 when scores are close). A zero-score fallback defaults to `TEXT_ENHANCE` with a disambiguation checklist.

### Phase Detection

```text
USER REQUEST
    |
    +- STEP 0: Detect mode ($command prefix or keyword signals)
    +- STEP 1: Score intents (top-2 when ambiguity is small)
    +- Phase 1: Framework Selection (7 frameworks evaluated)
    +- Phase 2: DEPTH Processing (3-10 rounds based on mode)
    +- Phase 3: Scoring & Validation (CLEAR)
    +- Phase 4: Output Delivery (formatted prompt)
```

### Resource Domains

This skill uses a **simple intent router**, not a keyed resource-subdirectory router. Its real resources are flat markdown files under `references/` and `assets/`; there are no `references/<key>/` or `assets/<key>/` runtime-key directories to select. The router therefore discovers markdown resources recursively from `references/` and `assets/`, then applies command-prefix and intent scoring against the discovered inventory.

- `references/` for DEPTH methodology, framework definitions, and CLEAR scoring.
- `assets/` for format-specific deep-dives (Markdown, JSON, YAML).

```text
references/depth-framework.md            - DEPTH methodology, RICCE integration
references/patterns-evaluation.md        - 7 frameworks, CLEAR scoring
assets/format-guide-markdown.md          - Markdown format deep-dive
assets/format-guide-json.md              - JSON format deep-dive
assets/format-guide-yaml.md              - YAML format deep-dive
```

### Resource Loading Levels

| Level       | When to Load             | Resources                                                                  |
| ----------- | ------------------------ | -------------------------------------------------------------------------- |
| ALWAYS      | Every skill invocation   | SKILL.md (this file)                                                       |
| CONDITIONAL | If intent signals match  | references/depth-framework.md, references/patterns-evaluation.md           |
| CONDITIONAL | If design-generation signals match | references/patterns-evaluation.md                                 |
| ON_DEMAND   | Only on explicit request | assets/format-guide-markdown.md, assets/format-guide-json.md, assets/format-guide-yaml.md |

A run that loads `references/patterns-evaluation.md` reads three of its sections, not the whole file:

1. `## 2. FRAMEWORK LIBRARY & SELECTION`, to score at least three frameworks and choose one.
2. The chosen framework's `###` subsection under `## 3. FRAMEWORK DEEP DIVES`. A switch to another framework reads its subsection too. A name that matches no subsection reads all of section 3.
3. `## 10. CLEAR EVALUATION MASTERY`, to score the result.

A request that carries an on-demand keyword (the `ON_DEMAND_KEYWORDS` list below) reads the whole file.

### Smart Router Pseudocode

```python
from pathlib import Path

SKILL_ROOT = Path(__file__).resolve().parent
RESOURCE_BASES = (SKILL_ROOT / "references", SKILL_ROOT / "assets")
DEFAULT_RESOURCE = "references/depth-framework.md"
PATTERNS_RESOURCE = "references/patterns-evaluation.md"

COMMAND_INTENTS = {
    "$text": "TEXT_ENHANCE",
    "$improve": "TEXT_ENHANCE",
    "$refine": "TEXT_ENHANCE",
    "$short": "TEXT_ENHANCE",
    "$json": "FORMAT_JSON",
    "$yaml": "FORMAT_YAML",
    "$raw": "RAW",
}

INTENT_MODEL = {
    "TEXT_ENHANCE": {"keywords": [("improve", 4), ("enhance", 4), ("prompt", 3), ("text", 3), ("refine", 4)]},
    "FRAMEWORK": {"keywords": [("framework", 4), ("rcaf", 5), ("costar", 5), ("tidd-ec", 5), ("scoring", 3)]},
    "DESIGN_GEN": {"keywords": [("design generation", 5), ("generate ui", 4), ("canvas", 3), ("design brief", 4), ("variations", 3)]},
    "FORMAT_MARKDOWN": {"keywords": [("markdown", 4), ("md", 2), ("readme", 3)]},
    "FORMAT_JSON": {"keywords": [("json", 5), ("schema", 3), ("api-ready", 3)]},
    "FORMAT_YAML": {"keywords": [("yaml", 5), ("frontmatter", 3), ("config", 2)]},
    # $raw is the whole trigger: passthrough is asked for by command token, never
    # inferred from prose, and it deliberately loads nothing.
    "RAW": {"keywords": [("$raw", 5), ("raw passthrough", 4)]},
    # The fast-path card a CLI orchestrator reads before dispatch, instead of the
    # full body.
    "CLI_FAST_PATH": {"keywords": [("cli prompt quality card", 5), ("prompt framework selection table", 4), ("clear pre-dispatch check", 4), ("fast path prompt quality", 4)]},
}

RESOURCE_MAP = {
    "TEXT_ENHANCE": ["references/depth-framework.md", "references/patterns-evaluation.md"],
    "FRAMEWORK": ["references/patterns-evaluation.md"],
    "DESIGN_GEN": ["references/patterns-evaluation.md"],
    "FORMAT_MARKDOWN": ["assets/format-guide-markdown.md", "references/patterns-evaluation.md"],
    "FORMAT_JSON": ["assets/format-guide-json.md", "references/patterns-evaluation.md"],
    "FORMAT_YAML": ["assets/format-guide-yaml.md", "references/patterns-evaluation.md"],
    "RAW": [],
    "CLI_FAST_PATH": ["assets/cli-prompt-quality-card.md"],
}

ON_DEMAND_KEYWORDS = ["deep dive", "full template", "all frameworks", "format guide", "overnight-agent prompt", "system prompt", "prompt package", "prompt variant", "operator prompt", "evaluator prompt", "dispatch prompt"]

UNKNOWN_FALLBACK_CHECKLIST = [
    "Is this a prompt enhancement request or a different task?",
    "Does the user want a specific framework applied?",
    "Is the user asking about scoring or evaluation?",
    "Should this route to sk-doc or sk-code instead?",
]

AMBIGUITY_DELTA = 1

def _guard_in_skill(relative_path: str) -> str:
    resolved = (SKILL_ROOT / relative_path).resolve()
    resolved.relative_to(SKILL_ROOT)
    if resolved.suffix.lower() != ".md":
        raise ValueError(f"Only markdown resources are routable: {relative_path}")
    return resolved.relative_to(SKILL_ROOT).as_posix()

def discover_markdown_resources() -> set[str]:
    docs = []
    for base in RESOURCE_BASES:
        if base.exists():
            docs.extend(path for path in base.rglob("*.md") if path.is_file())
    return {doc.relative_to(SKILL_ROOT).as_posix() for doc in docs}

def _task_text(task) -> str:
    if isinstance(task, str):
        return task.lower()
    return " ".join(
        str(task.get(f, "")) for f in ("text", "query", "description", "keywords")
    ).lower()

def detect_command_intent(task):
    text = _task_text(task).strip()
    for prefix, intent in COMMAND_INTENTS.items():
        if text.startswith(prefix):
            return intent
    return None

def score_intents(task) -> dict[str, float]:
    text = _task_text(task)
    scores = {intent: 0 for intent in INTENT_MODEL}
    for intent, cfg in INTENT_MODEL.items():
        for keyword, weight in cfg["keywords"]:
            if keyword in text:
                scores[intent] += weight
    return scores

def select_intents(task, scores, ambiguity_delta=AMBIGUITY_DELTA, max_intents=2):
    command_intent = detect_command_intent(task)
    if command_intent:
        return (command_intent, None)
    ranked = sorted(scores.items(), key=lambda pair: pair[1], reverse=True)
    primary, primary_score = ranked[0]
    if primary_score == 0:
        return ("TEXT_ENHANCE", None)
    secondary, secondary_score = ranked[1]
    if secondary_score > 0 and (primary_score - secondary_score) <= ambiguity_delta:
        return (primary, secondary)
    return (primary, None)

def route_prompt_improver_resources(task):
    inventory = discover_markdown_resources()
    text = _task_text(task)
    scores = score_intents(task)
    command_intent = detect_command_intent(task)
    primary, secondary = select_intents(task, scores)
    intents = [primary] + ([secondary] if secondary else [])
    loaded = []
    seen = set()

    def load_if_available(relative_path: str):
        guarded = _guard_in_skill(relative_path)
        if guarded in inventory and guarded not in seen:
            load(guarded)
            loaded.append(guarded)
            seen.add(guarded)

    # Prefixes are authoritative; RAW skips DEPTH and reference loading.
    if command_intent == "RAW":
        return {"intents": intents, "intent_scores": scores, "resources": loaded, "load_level": "RAW"}

    # Unknown fallback: when no command prefix or keywords match at all.
    if not command_intent and scores.get(primary, 0) == 0:
        load_if_available(DEFAULT_RESOURCE)
        return {
            "intents": intents,
            "intent_scores": scores,
            "load_level": "UNKNOWN_FALLBACK",
            "resources": loaded,
            "needs_disambiguation": True,
            "disambiguation_checklist": UNKNOWN_FALLBACK_CHECKLIST,
        }

    # Standard routing: DEPTH default + intent-mapped resources.
    if primary != "FRAMEWORK":
        load_if_available(DEFAULT_RESOURCE)
    else:
        load_if_available(PATTERNS_RESOURCE)
    for intent in intents:
        for relative_path in RESOURCE_MAP.get(intent, []):
            load_if_available(relative_path)

    # ON_DEMAND: load all mapped markdown resources when trigger keywords are present.
    if any(kw in text for kw in ON_DEMAND_KEYWORDS):
        for paths in RESOURCE_MAP.values():
            for relative_path in paths:
                load_if_available(relative_path)

    return {"intents": intents, "intent_scores": scores, "resources": loaded}
```

---

## 3. HOW IT WORKS

### Enhancement Pipeline

Every prompt enhancement follows this pipeline:

```
STEP 1: Mode Detection
       ├─ Command prefix check ($text, $improve, $refine, $short, etc.)
       ├─ Keyword signal analysis (>=80% confidence = auto-route)
       └─ Ambiguous? Ask ONE comprehensive question
       ↓
STEP 2: Framework Selection
       ├─ Evaluate 7 frameworks against request characteristics
       ├─ Score: complexity, urgency, audience, creativity, precision
       └─ Select primary framework + alternative
       ↓
STEP 3: DEPTH Processing (5-10 rounds)
       ├─ Discover: 5 perspectives, assumption audit, RICCE Role & Context
       ├─ Engineer: Framework application, RICCE Constraints & Instructions
       ├─ Prototype: Template build, RICCE validation
       ├─ Test: Scoring (CLEAR), quality gates
       └─ Harmonize: Final polish, RICCE completeness
       ↓
STEP 4: Scoring & Delivery
       ├─ Apply context-appropriate scoring system
       ├─ Verify threshold met (CLEAR 40+/50)
       └─ Deliver enhanced prompt with transparency report
```

See the Smart Routing pseudocode (Section 2) for the complete routing logic.

### Operating Modes

| Mode | Command | DEPTH Rounds | Scoring | Use Case |
|------|---------|-------------|---------|----------|
| Interactive | (default) | 10 | CLEAR | Guided enhancement |
| Text | `$text` | 10 | CLEAR | Standard text prompt |
| Short | `$short` | 3 | CLEAR | Quick refinement |
| Improve | `$improve` | 10 | CLEAR | Standard enhancement |
| Refine | `$refine` | 10 | CLEAR | Maximum optimization |
| JSON | `$json` | 10 | CLEAR | API-ready format |
| YAML | `$yaml` | 10 | CLEAR | Config format |
| Raw | `$raw` | 0 | None | Skip DEPTH |

### Framework Selection Matrix

| Complexity | Primary Need | Framework |
|-----------|-------------|-----------|
| 1-3 | Speed | RACE |
| 1-4 | Clarity | RCAF |
| 3-6 | Audience | COSTAR |
| 4-6 | Instructions | CIDI |
| 5-7 | Creativity | CRISPE |
| 6-8 | Precision | TIDD-EC |
| 7-10 | Comprehensive | CRAFT |
See [patterns-evaluation.md](./references/patterns-evaluation.md) for complete framework details.
See [depth-framework.md](./references/depth-framework.md) for the DEPTH methodology.

### Scoring Systems

**CLEAR** (50-point scale): Correctness (10) + Logic (10) + Expression (15) + Arrangement (10) + Reusability (5). Threshold: 40+.

---

## 4. RULES

### ✅ ALWAYS

1. **ALWAYS ask ONE comprehensive question** before processing, in an interactive run whose request leaves the goal open
   - Gather: What needs enhancement? Use case/goal? Requirements?
   - Exception: `$raw` mode skips questions entirely
   - An agent or other non-interactive run never asks: it proceeds on stated assumptions and flags each one in the transparency report

2. **ALWAYS apply DEPTH processing** for the detected mode
   - 10 rounds for text modes, 3 for $short, 0 for $raw

3. **ALWAYS enforce minimum 3 perspectives** during DEPTH Discover phase
   - Target 5 perspectives; 3 is the blocking minimum
   - Perspectives: Prompt Engineering, AI Interpretation, User Clarity, Framework Selection, Token Efficiency

4. **ALWAYS validate with RICCE** before delivery
   - Role, Instructions, Context, Constraints, Examples must be present or justified

5. **ALWAYS apply scoring** and verify threshold met
   - CLEAR 40+/50

6. **ALWAYS provide a transparency report** after delivering the enhanced prompt
   - Framework selected, DEPTH rounds applied, score breakdown, assumptions flagged

### ⛔ NEVER

1. **NEVER answer own questions**
   - In an interactive run, wait for the user's response before proceeding with enhancement

2. **NEVER skip framework evaluation**
   - Even for simple prompts, score at least 3 frameworks before selecting

3. **NEVER deliver without scoring**
   - Every enhanced prompt must have a CLEAR score (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

### ⚠️ ESCALATE IF

1. **ESCALATE IF mode detection confidence < 50%**
   - Ask: "What type of prompt are you creating? Can you describe the use case?"

2. **ESCALATE IF CLEAR score below threshold after DEPTH**
   - Suggest: "Score is below target. Options: A) Additional refinement round B) Switch framework C) Accept as-is"

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

- [depth-framework.md](./references/depth-framework.md) - DEPTH methodology (Discover, Engineer, Prototype, Test, Harmonize), RICCE integration
- [patterns-evaluation.md](./references/patterns-evaluation.md) - 7 framework definitions, CLEAR scoring

### 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

### Reference Loading Notes

- Load only references needed for current intent
- Smart Routing (Section 2) 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 and framework selected with reasoning
- ✅ DEPTH rounds completed per mode specification
- ✅ Scoring applied and threshold verified
- ✅ RICCE validation passed
- ✅ Enhanced prompt delivered with transparency report
- ✅ User can iterate or accept

### Quality Targets

- **CLEAR Score**: 40+ out of 50
- **Framework Selection Accuracy**: Match task characteristics to framework with >85% alignment

---

## 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` used to choose Quick vs Standard DEPTH energy |
| `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 | — |
| `cli-claude-code` | Sonnet | Yes | — |
| `cli-codex` | GPT Luna | Yes | — |
| `cli-pi` | any model except Luna | Yes | — |
| `cli-opencode` | any model except Luna | Yes | — |
| `cli-hermes` | `deepseek-v4.1-flash` or `glm-5.3-flash` through `llmgateway` | Yes | The Hermes roster is closed at these two ids; 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 canonical home of this contract is `.skilled/agents/prompt-improver.md`, so future edits land in one place.

### Deterministic Agent Rules

- Use `references/patterns-evaluation.md` as the framework-selection source of truth. Read only `## 2. FRAMEWORK LIBRARY & SELECTION`, the chosen framework's subsection of `## 3. FRAMEWORK DEEP DIVES` and `## 10. CLEAR EVALUATION MASTERY`. A framework switch reads the new framework's subsection, and an on-demand keyword reads the whole file.
- Use `references/depth-framework.md` for DEPTH flow and CLEAR dimension floors.
- Choose Quick DEPTH energy for low-complexity routine prompts and Standard DEPTH energy for escalated prompts.
- Require `CLEAR >= 40/50` and all per-dimension floors before returning success.
- If the first pass scores below threshold, retry once and then return the best validated prompt with explicit escalation notes.

### Structured Output Block

```text
FRAMEWORK: <name>
CLEAR_SCORE: <n>/50 (C:<n> L:<n> E:<n> A:<n> R:<n>)
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 framework-selection 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 `skill_advisor.py` 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/depth-framework.md`, `references/patterns-evaluation.md`, `assets/format-guide-json.md`, `assets/format-guide-markdown.md`, `assets/format-guide-yaml.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.