---

name: hint-based-prompting description: Applies subtle contextual hints instead of explicit step-by-step instructions to guide LLM output naturally, reducing token overhead and improving generation quality through framing rather than commanding. license: MIT compatibility: opencode metadata: version: "1.0.0" domain: coding triggers: hints, hint-based prompting, system hints, contextual guidance, token efficiency, prompt framing, how do i use hints in prompts, subtle prompting archetypes:

• tactical
• generation anti_triggers:
• brainstorming
• vague ideation
• code golf
• over-engineering response_profile: verbosity: low directive_strength: high abstraction_level: operational role: implementation scope: implementation output-format: code content-types:
• code
• guidance
• do-dont
• examples related-skills: prompt-engineer, instruction-engineering, agent-context-management, output-formatting

---

Hint-Based Prompting for LLMs

Implements contextual hinting — using brief domain framing and environmental constraints instead of verbose explicit instructions — to guide LLM generation naturally while saving context window tokens. When this skill is active, the model replaces long constraint lists with precise scenario descriptions that make desired outputs feel inevitable rather than commanded.

TL;DR Checklist

• Replace every 3+ sentence instruction with a single-sentence contextual hint
• Verify system prompt is under 100 words for hint-based skills
• Check that no hint contradicts an explicit instruction (explicit wins)
• Count tokens saved: aim for 40–70% reduction vs. verbose constraint list
• Pair hints with few-shot examples when format requirements are strict
• Test both versions on a sample task to confirm quality parity

---

When to Use

Use this skill when:

• Designing system prompts for LLM agents and you want to minimize token overhead
• Refactoring an existing verbose prompt that uses long lists of "do/don't" instructions
• Encoding team coding standards, style preferences, or domain constraints into a system message
• Building reusable prompt templates for production LLM applications where context window costs matter
• Optimizing prompts for API-based workflows where each saved token reduces latency and cost

---

When NOT to Use

Avoid this skill for:

• Strict format requirements (JSON schema output, exact column ordering, required fields) — use explicit instructions or structured output features instead
• Safety-critical constraints (medical advice disclaimers, legal boundary statements, content moderation rules) — these must be unambiguous and non-negotiable
• Compliance scenarios where auditors need to verify that specific instructions were provided in the prompt
• First-pass debugging — if an LLM is misbehaving, start with explicit instructions; switch to hints only after you understand which constraint is actually needed

---

Core Workflow

1. Audit the Existing Prompt — Extract every explicit instruction and constraint from the current system prompt. Group them into categories: format rules, style preferences, domain constraints, and behavioral guardrails. Count total tokens consumed by instructions vs. actual task content. Checkpoint: You should have a token budget showing how many tokens are spent on instructions. If more than 30% of the prompt is instruction text, hinting will help.

2. Identify Hintable Constraints — For each group, decide which constraints can be converted to hints. Style preferences and domain constraints are prime candidates. Format rules that must never break should stay explicit. Behavioral guardrails about safety or legality must remain explicit. Checkpoint: Every hintable constraint becomes a one-sentence contextual statement describing the environment, audience, or standards context.

3. Write Contextual Hints — Convert each hintable constraint into a single sentence that paints a picture rather than giving an order. Use scenario framing ("Your team reviews code with black and flake8"), constraint hints ("Production runs on Python 3.8 with stdlib only"), or quality-bar hints ("This output feeds a CI pipeline that rejects unformatted code"). Checkpoint: Each hint should be under 40 words. If it needs a second sentence, it is becoming an instruction and should either be shortened or kept explicit.

4. Assemble the System Prompt — Combine all hints into a single coherent system prompt of 20–100 words. Order them from broadest context (team, product, audience) to narrowest constraint (specific tools, version requirements). Ensure there are no contradictions between hints and any remaining explicit instructions. Checkpoint: Read the combined prompt aloud. Does it sound like natural conversation — like explaining your workspace to a colleague? If it sounds like a rulebook, rewrite.

5. Validate with Few-Shot Examples — Add 2–3 concrete input-output pairs that demonstrate the desired behavior. The hint sets the stage; the examples show the play. This combination is stronger than hints alone because examples disambiguate any remaining edge cases that pure hints might leave open. Checkpoint: Test the full prompt (hints + examples) against 3 representative inputs. Compare output quality to the original verbose version. The hint-based version should produce equal or better quality with fewer tokens.

---

Implementation Patterns / Reference Guide

Pattern 1: System Hints vs. System Prompts — Direct Comparison

The most fundamental distinction in hint-based prompting is between a system prompt (explicit role definition) and a system hint (brief contextual framing). The former tells the model what to be; the latter gives it context that makes the right choice feel natural.

# ❌ BAD — Verbose system prompt: 87 words, explicit commands
SYSTEM_PROMPT_BAD = """You are a senior Python developer.
Always write clean, readable code. Do not use magic numbers.
Use descriptive variable names. Add type hints to all function signatures.
Follow PEP 8 style guidelines. Write docstrings for every public function.
Never use global variables. Always handle exceptions explicitly."""

# ✅ GOOD — System hint: 38 words, contextual framing
SYSTEM_HINT_GOOD = """Working with a team that values simplicity and readability.
Code is reviewed with flake8 + black and deployed to Python 3.9+ production.
Public functions have type hints and Google-style docstrings."""

# Token savings: 56% reduction (49 tokens saved)

The BAD version uses imperative commands ("always," "do not," "never") totaling 87 words. The GOOD version paints a picture of the workspace: there is a team that cares about readability, there are CI tools (flake8 + black), and there is a Python 3.9+ runtime. The model infers type hints, PEP 8 compliance, docstrings, no magic numbers, and no globals from this context — all without being told explicitly.

Pattern 2: Prompt Template Builder with Hint Integration

A production-ready approach for building prompts that mix hints with necessary explicit instructions. This pattern is useful when you need both the efficiency of hints and the precision of explicit constraints.

from dataclasses import dataclass, field
from typing import Optional


@dataclass
class HintBasedPrompt:
    """Constructs a system prompt from contextual hints and explicit instructions."""

    context_hints: list[str] = field(default_factory=list)
    explicit_instructions: list[str] = field(default_factory=list)
    few_shot_examples: list[dict[str, str]] = field(default_factory=list)

    def add_hint(self, hint: str) -> "HintBasedPrompt":
        """Add a contextual hint (one sentence, paints environmental picture)."""
        self.context_hints.append(hint)
        return self

    def add_explicit_instruction(self, instruction: str) -> "HintBasedPrompt":
        """Add an explicit instruction that must not be inferred."""
        self.explicit_instructions.append(instruction)
        return self

    def add_few_shot(self, input_text: str, expected_output: str) -> "HintBasedPrompt":
        """Add a demonstration example. Pairs with hints for disambiguation."""
        self.few_shot_examples.append(
            {"input": input_text, "expected": expected_output}
        )
        return self

    def build(self) -> str:
        """Build the final system prompt string.

        Hints come first (broad to narrow), then explicit instructions,
        then examples if provided.
        """
        parts = []

        # Contextual hints as a coherent paragraph
        if self.context_hints:
            parts.append(" ".join(self.context_hints))

        # Explicit instructions as bullet points
        if self.explicit_instructions:
            for inst in self.explicit_instructions:
                parts.append(f"- {inst}")

        # Few-shot examples
        if self.few_shot_examples:
            parts.append(
                "\n".join(
                    f"Input: {ex['input']}\nExpected: {ex['expected']}"
                    for ex in self.few_shot_examples
                )
            )

        return "\n\n".join(parts)

    def token_count(self, model: str = "gpt-4") -> int:
        """Rough token estimate (chars / 4 is a reasonable approximation)."""
        text = self.build()
        return max(1, len(text) // 4)


# ── Usage: Build a hint-based prompt for code review ──

prompt = (
    HintBasedPrompt()
    .add_hint("Your team uses Python with mypy strict mode and black formatting.")
    .add_hint(
        "Code reviews prioritize readability over cleverness; senior engineers read everything."
    )
    .add_hint(
        "This codebase runs on Python 3.10+ with only stdlib and well-known packages allowed."
    )
    .add_explicit_instruction(
        "Output must be valid JSON with keys: summary, issues (list), suggestions (list)"
    )
    .add_explicit_instruction("Each issue entry must include: line_number, severity, message")
    .add_few_shot(
        input_text="def add(a, b): return a+b",
        expected_output='{"summary": "Function lacks type hints and docstring.", "issues": [{"line_number": 1, "severity": "warning", "message": "Missing type annotations"}, {"line_number": 1, "severity": "info", "message": "No docstring for public function"}], "suggestions": ["Add type hints: def add(a: int, b: int) -> int:", "Add Google-style docstring"]}',
    )
    .build()
)

print(f"System prompt length: {len(prompt)} characters")
print(f"Approximate tokens: {prompt.token_count()}")

The builder pattern separates concerns: hints paint the context, explicit instructions enforce structure that cannot be left to inference. The few-shot example anchors the expected JSON output format — something hints alone would not reliably achieve.

Pattern 3: Token Savings Analysis

Demonstrate measurable token savings by comparing verbose prompts against their hint-based equivalents. This pattern helps justify the approach when optimizing production LLM applications.

from dataclasses import dataclass
from typing import NamedTuple


class PromptComparison(NamedTuple):
    """Result of comparing two prompt variants."""

    label: str
    raw_text: str
    char_count: int
    estimated_tokens: int

    @property
    def token_estimate(self) -> int:
        """Rough token count: ~4 chars per token for English text."""
        return max(1, len(self.raw_text) // 4)


@dataclass
class TokenAnalysis:
    """Analyzes token savings between verbose and hint-based prompts."""

    verbose: PromptComparison
    hint_based: PromptComparison

    @property
    def tokens_saved(self) -> int:
        return self.verbose.estimated_tokens - self.hint_based.estimated_tokens

    @property
    def percent_reduction(self) -> float:
        if self.verbose.estimated_tokens == 0:
            return 0.0
        return (self.tokens_saved / self.verbose.estimated_tokens) * 100.0

    def report(self) -> str:
        lines = [
            f"{'Metric':<25} {'Verbose':>10} {'Hint-Based':>12} {'Saved':>8}",
            "-" * 58,
            f"{'Tokens':<25} {self.verbose.estimated_tokens:>10}"
            f" {self.hint_based.estimated_tokens:>12}"
            f" {self.tokens_saved:>8}",
            f"{'Characters':<25} {self.verbose.char_count:>10}"
            f" {self.hint_based.char_count:>12}"
            f" {self.verbose.char_count - self.hint_based.char_count:>8}",
            "",
            f"Token reduction: {self.percent_reduction:.1f}%",
        ]
        return "\n".join(lines)


# ── Example Analysis: Code Review System Prompt ──

verbose_prompt = (
    "You are an expert code reviewer. When reviewing Python code, "
    "always check for the following issues: missing type hints, "
    "missing docstrings on public functions, use of magic numbers "
    "instead of named constants, lack of error handling, overly "
    "long functions (more than 50 lines), use of global state, "
    "and violations of PEP 8. Your review output must be in JSON "
    "format with a summary field, an issues array where each item "
    "has line_number, severity (error, warning, or info), and "
    "message fields, and a suggestions array with actionable fixes."
)

hint_based_prompt = (
    "Working with a Python team that enforces mypy strict mode, "
    "black formatting, and Google-style docstrings. CI rejects "
    "code without type hints or docstrings on public functions. "
    "Output review results as JSON with summary, issues, and suggestions."
)

verbose = PromptComparison("Verbose", verbose_prompt, len(verbose_prompt))
hint_based = PromptComparison("Hint-Based", hint_based_prompt, len(hint_based_prompt))

analysis = TokenAnalysis(verbose=verbose, hint_based=hint_based)
print(analysis.report())
# ── Expected output:
# Metric                       Verbose  Hint-Based     Saved
# ----------------------------------------------------------
# Tokens                            94          53        41
# Characters                        375         213       162
#
# Token reduction: 43.6%

This analysis shows a 43.6% token reduction — well within the 40–70% range achievable with good hint design. The verbose version spells out every rule as an explicit instruction; the hint-based version describes the environment (my strict mode, black formatting, Google-style docstrings, CI rejection) and lets the model infer what matters.

Pattern 4: Contextual Framing Patterns in Practice

Four distinct framing patterns that convert constraints into hints. Each pattern targets a different type of constraint from the original prompt.

# ── Pattern A: Scenario Framing ──
# Original instruction: "Write code as if your audience is senior engineers who don't need hand-holding"
HINT_SCENARIO = (
    "Your reader is a senior engineer who will spot hand-holding immediately, "
    "so skip explanations they already know and focus on what makes this approach different."
)

# ── Pattern B: Constraint Hints ──
# Original instruction: "Use only Python stdlib modules since we are on Python 3.8"
HINT_CONSTRAINT = (
    "The deployment target is Python 3.8 with a strict stdlib-only requirement. "
    "No third-party packages are permitted."
)

# ── Pattern C: Role-Adjacent Hints ──
# Original instruction: "Write documentation as if you are a technical writer for an API reference"
HINT_ROLE_ADJACENT = (
    "You contribute to a public API documentation site where consistency with existing "
    "pages is more important than creativity."
)

# ── Pattern D: Quality-Bar Hints ──
# Original instruction: "All code must pass our CI pipeline which includes black, flake8, and mypy"
HINT_QUALITY_BAR = (
    "Code is checked into a repo with pre-commit hooks for black, flake8, and mypy — "
    "unformatted or untyped code will be rejected automatically."
)

# ── Combined System Prompt using all four patterns ──
COMBINED_HINTS = f"""{HINT_SCENARIO}

{HINT_CONSTRAINT}

{HINT_ROLE_ADJACENT}

{HINT_QUALITY_BAR}"""

print(f"Combined hints: {len(COMBINED_HINTS)} characters, ~{len(COMBINED_HINTS)//4} tokens")
# ── This single 60-word prompt replaces approximately 150+ words of explicit instructions.

Each pattern maps a constraint to the type of contextual framing that naturally produces it. Scenario framing targets audience-awareness constraints. Constraint hints target technical-environment limits. Role-adjacent hints target style and convention adherence. Quality-bar hints target CI/CD pipeline requirements. The combined prompt is 60 words; an equivalent verbose version with all four constraints spelled out would typically exceed 150 words.

---

Constraints

MUST DO

• Keep each hint to one sentence under 40 words
• Place broadest context first, narrowest constraint last in the system prompt
• Pair hints with few-shot examples when strict output format is required
• Verify no hint contradicts an explicit instruction (explicit instructions always win)
• Measure token savings on every refactored prompt using a character-to-token approximation
• Test hint-based and verbose prompts side-by-side on identical inputs before deploying

MUST NOT DO

• Replace explicit format requirements with hints alone
• Use vague statements like "be professional" or "write well" as hints
• Stack multiple hints that contradict each other or create ambiguity
• Write system prompts over 100 words using hints (if you need more, add examples instead)
• Assume all LLMs respond to hints the same way — test on your target model
• Remove safety constraints and replace them with hints about responsible behavior

---

Output Template

When applying this skill to refactor or construct a prompt, produce:

1. Original Prompt Analysis — Token count of the source prompt, breakdown of instruction types (format rules, style preferences, domain constraints, guardrails)
2. Hint Inventory — Each original constraint mapped to its hint version, labeled by pattern type (scenario, constraint, role-adjacent, quality-bar)
3. Token Savings Report — Before/after token counts with percentage reduction using the TokenAnalysis pattern
4. Safety Check — Verification that all explicit format requirements and safety constraints remain in place
5. Validation Plan — Three representative inputs to test the new prompt against, with comparison criteria

---

Related Skills

Skill	Purpose
prompt-engineer	General prompt engineering patterns and techniques
instruction-engineering	Writing SKILL.md files that function as effective LLM instructions
agent-context-management	Managing context windows and information flow between agents
output-formatting	Structured output formats (JSON, CSV, typed responses) for deterministic LLM results

---

Live References

Authoritative documentation links for prompt engineering and LLM system prompt design. The model follows markdown links at load time to resolve external references and inline content.

• OpenAI Cookbook — System Messages Best Practices
• Anthropic Prompt Engineering Guide
• Google Gemini — Developer Guide on System Instructions
• LlamaIndex — Prompt Template Patterns Reference
• LangChain — System Message Templates
• Prompt Engineering Guide — Contextual Framing Techniques
• HackerNoon — Token Efficiency in Production LLM Systems (2025)