sk-prompt

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

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

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).

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

Smart Router Pseudocode

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)]},
}

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": [],
}

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

Framework Selection Matrix

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

   • Gather: What needs enhancement? Use case/goal? Requirements?
   • Exception: $raw mode skips questions entirely

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

   • Wait for user 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 use second-person voice in enhanced prompts

   • Use imperative or third-person form in the output

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 - DEPTH methodology (Discover, Engineer, Prototype, Test, Harmonize), RICCE integration
• patterns-evaluation.md - 7 framework definitions, CLEAR scoring

Asset Files

• format-guide-markdown.md - Markdown format deep-dive: fundamentals, delivery standards, RCAF/CRAFT structures, advanced patterns, validation, best practices
• 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 - 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

Deterministic Agent Rules

• Use references/patterns-evaluation.md as the framework-selection source of truth.
• 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, run up to 3 total improvement cycles and then return the best validated prompt with explicit escalation notes.

Structured Output Block

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 6 decision tree
• Memory: Context preserved via Spec Kit Memory MCP

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.