Generate Refine Prompts

Generate Refine Prompts

Overview

Use this skill to create prompts that are executable and maintainable under real tool constraints. Favor small, testable prompt deltas over large rewrites.

Hard rule for this skill:

• Summarize and abstract source practices into reusable principles.
• Do not paste large raw prompt blocks from source projects into deliverables.

Quick Start

1. Define target runtime and task scope:

• Capture model role, tool surface, sandbox/approval model, and output channel.

2. Read references/full-coverage-synthesis.md:

• Start from full-corpus distilled takeaways (20-file coverage).

3. Read references/prompt-design-philosophy.md:

• Select the design posture that matches the task (strict execution, knowledge retrieval, UX coding, or hybrid).

4. Start from references/prompt-blueprints.md:

• Use the nearest blueprint and only fill sections required by the target runtime.

5. Run scripts/prompt_quality_check.py <prompt-file>:

• Detect missing contract sections and instruction conflicts before shipping.

6. Refine with minimal edits:

• Preserve good constraints, remove contradictions, and tighten failure handling language.

Workflow

1. Define the Prompt Contract

Establish non-negotiables before writing prose:

• Role and task boundary: State what the agent is and what it is not.
• Tool contract: Define when to call tools, batching strategy, and parameter strictness.
• Safety and policy: Define refusal boundaries, data handling, and prohibited actions.
• Output contract: Define verbosity, formatting, and required sections.

2. Compose a First Draft

Write sections in this order:

1. Identity and operating context
2. Global mandates and hard constraints
3. Tool protocol and sequencing rules
4. Task workflow and verification gates
5. Response format and style constraints

3. Run Structured Quality Checks

Run:

python3 scripts/prompt_quality_check.py path/to/prompt.txt

Interpret results:

• Missing sections: Add missing contract components before style tweaks.
• Conflicts: Resolve hard contradictions first, then soft tone conflicts.
• Score: Use as triage only; prioritize explicit findings.

4. Red-Team and Refine

Stress-test against edge cases:

• Ambiguous user intent
• Missing required tool parameters
• Conflicting instructions between system and developer layers
• Requests that should trigger clarification instead of immediate execution

Refine by patching only the minimal lines needed to recover determinism.

5. Produce Final Prompt Package

Return:

• Final prompt text
• Short changelog of edits
• Known tradeoffs and remaining risks

Design Heuristics From Sources

• Anthropic: Enforce concise style, clear proactiveness bounds, and convention-first code changes.
• Google Antigravity: Separate planning, execution, and verification modes with explicit status transitions.
• Notion AI: Use tool-first loops for non-trivial tasks and standardize citation/search behavior.
• Lovable: Encode platform/runtime constraints and default discussion-vs-implementation policy.
• Open Source prompts: Make tool schemas explicit, constrain edits, and define execution environment assumptions.

Resources

• references/full-coverage-synthesis.md Full-file coverage distilled into transferable writing philosophy.
• references/full-coverage-generated.md Auto-generated 20-file coverage report with structure/axis statistics.
• references/prompt-design-philosophy.md Comparative design patterns and anti-patterns.
• references/prompt-blueprints.md Reusable templates for generation and refinement.
• scripts/prompt_quality_check.py Fast static checks for missing sections and instruction conflicts.
• scripts/build_full_coverage_report.py Generate summarized full-coverage corpus reports without copying source text.

Deliverable Template

Use this shape when returning refined prompts:

## Prompt vN
<final prompt>

## Changes from vN-1
1. <change>
2. <change>

## Remaining Risks
1. <risk>
2. <risk>