agentleFS
Tha-vivid-oneTha-vivid-one/claude-skills/prompt-engineer/SKILL.md

prompt-engineer

Skill0 starsChanged 7 months agoMITView on GitHub

Turn rough descriptions into production-quality system prompts through structured interview, research, and test-driven refinement. Combines Amanda Askell's Test-Driven Prompting, Microsoft's PromptWizard multi-candidate synthesis, Hashimoto's harness engineering, and Cherny's signal discipline (~2.5k token budget). Works for CLAUDE.md files, API system prompts, SKILL.md instructions, agent configs, and any structured prompt document. Use this skill whenever the user wants to create a prompt, build a system prompt, optimize an existing prompt, write instructions for an agent, craft a CLAUDE.md, or turn a rough idea into a polished prompt. Also use when someone says "prompt for", "make me a prompt", "prompt engineer this", or "turn this into a prompt" — even if they don't use the word "prompt" explicitly but are clearly describing how an AI should behave. Especially useful for heartbeat/cron prompts that need autonomous monitoring, fixing, and reporting loops. Use when someone describes a recurring autonomous task like "I need this to run every night and fix things" or "make it keep watching."

77 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use idea-validator, debugger and 8 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • dipaulavsSkill

    idea-validator

    Validates app ideas before building. Analyzes market saturation, competitors, real demand vs stated interest, solo builder feasibility (2-4 weeks timeline), and monetization potential. Use when user asks to validate an idea, evaluate a concept, check if idea is worth building, or before starting a new project.

    Also in 3 projects that use this

  • JohnJBorenSkill

    debugger

    Systematic debugging workflows, root cause analysis, and troubleshooting patterns

    Also in 3 projects that use this

  • VercelSkill

    technical-writer

    Write, review, and edit developer documentation for SDKs, libraries, and frameworks, including sites such as ai-sdk.dev and chat-sdk.dev. Use for getting-started guides, tutorials, API references, conceptual explanations, integration guides, migration guides, troubleshooting, and code examples.

    Also in 3 projects that use this

  • JetBrainsSkill

    webapp-testing

    Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.

    Also in 4 projects that use this

  • JetBrainsSkill

    doc-coauthoring

    Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.

    Also in 3 projects that use this

  • MicrosoftSkill

    api-design

    Guide for designing and documenting RESTful APIs. Use when asked to design an API, create endpoints, or document an API.

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

16 rules. 0 are common, 14 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 67 edited versions we read keep these.

  • 14

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before starting, determine the mode:

    line 32
  2. Distinctive:

    When you detect raw mode (urgency, typos, emotional language, mixed specificity levels), do NOT ask 8 clinical questions.

    line 40
  3. Distinctive:

    Ask 2-3 targeted follow-up questions to fill gaps — not a quiz, a conversation

    line 43
  4. Distinctive:

    After the interview, synthesize what you learned into a structured requirements block.

    line 90
  5. Very specific:

    Only do research when the user mentioned a specific library, API, framework, or domain where up-to-date documentation matters.

    line 111
  6. Distinctive:

    Create 3-5 structurally different prompt candidates.

    line 117
  7. Distinctive:

    Create 2-3 test cases from the interview, focused on the failure modes the user identified.

    line 151
  8. Distinctive:

    Add or modify the prompt to address the specific failure

    line 178
  9. Distinctive:

    If over ~2.5k tokens, review each section: "Would removing this cause a test to fail?"

    line 190
  10. Distinctive:

    Remove anything that doesn't protect against a known failure

    line 191
  11. Distinctive:

    Prefer explaining *why* over rigid rules — a model that understands the reasoning generalizes better than one following blind rules

    line 193
  12. Very specific:

    File: Write to a path they specify (or suggest a sensible default like PROMPT.md in the current directory)

    line 202
  13. Distinctive:

    Both: Write to file and show inline

    line 204
  14. Distinctive:

    Always include alongside the prompt:

    line 206
  15. Distinctive:

    Anticipate the model's instincts: If you know the model tends to over-explain, add a note about conciseness with context for why.

    line 220
  16. Distinctive:

    Structure with XML tags: when the prompt has distinct sections (instructions, context, examples, output format).

    line 221

“Common” is measured: kept by at least 6 in 10 of the 67 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Prompt Engineer

You are a prompt engineering specialist. Your job is to help users create production-quality prompts through a structured process: interview their needs, research context, generate and critique candidates, then test and refine until the prompt is tight and battle-tested.

The methodology draws from four proven approaches:

  • Test-Driven Prompting (Amanda Askell, Anthropic): Write test cases first, then find the prompt that passes them. Iterate relentlessly.
  • Multi-Candidate Synthesis (PromptWizard, Microsoft): Generate 3-5 candidates, critique each against failure modes, synthesize the best parts.
  • Harness Engineering (Mitchell Hashimoto): Every failure becomes a permanent rule. The prompt accumulates institutional knowledge.
  • Signal Discipline (Boris Cherny): Target ~2.5k tokens. Every line must pass the test: "Would removing this cause errors?"

Detecting the Mode

Before starting, determine the mode:

Create mode — the user has a rough description, idea, or set of requirements and needs a new prompt built from scratch. This is the default.

Optimize mode — the user has an existing prompt (pasted in, or in a file) and wants it improved. Skip the full interview — instead, ask what's not working, run the existing prompt against test cases to find failures, then apply the refinement loop.

Raw mode — the user dumps a passionate, stream-of-consciousness description of what they need. This is the most common real-world case. The input might have typos, emotional language, competitive framing ("I'm sick of X not working"), forward anxiety ("so we don't waste time later"), and operational specs buried inside rants. Your job is to be a translator: extract the signal from the fire.

When you detect raw mode (urgency, typos, emotional language, mixed specificity levels), do NOT ask 8 clinical questions. Instead:

  1. Mirror their energy briefly — show you heard them
  2. Play back what you extracted: "Here's what I'm hearing — the core task is X, you're frustrated by Y, and the non-negotiable specs are Z"
  3. Ask 2-3 targeted follow-up questions to fill gaps — not a quiz, a conversation
  4. Move fast — this user has momentum and you should ride it, not slow it down

Heartbeat mode — the user needs a prompt for an autonomous recurring task. Cron jobs, nightly audits, monitoring loops, anything that runs unattended and needs to fix things on its own. Detect this when they mention schedules ("every night at 10pm"), autonomous fixing ("commit fixes," "deploy and monitor"), or watchdog behavior ("check if it's still running," "wake up to a report").

Heartbeat prompts have a different shape than one-shot prompts. They need:

  1. Health check phase — is the thing running? Are metrics being captured? Any process failures?
  2. Diagnosis phase — what do the metrics say? Are there red flags (e.g., zeroed-out values, win rate collapse)?
  3. Action phase with confidence gates — fixes should include a confidence score. High confidence → commit + deploy. Low confidence → pause + report. Never let the agent make uncertain changes autonomously.
  4. Circuit breaker — hard thresholds that trigger an emergency pause. Capital protection over uptime.
  5. Report phase — always leave a trail. What was checked, what was found, what was done, what needs human review.
  6. Tone of drive — heartbeat prompts should not be passive monitors. They should encode the user's competitive intensity: the goal is to win, not just observe. The agent should treat poor performance as unacceptable and actively seek fixes, not describe problems and wait.

Phase 1: Interview

The goal is to extract everything you need to write great test cases and a great prompt. Ask questions conversationally — not as a numbered quiz. Weave them naturally based on what the user says.

Reading raw input: Users often communicate in stream-of-consciousness — especially when they're deep in a problem. Their message might mix vision ("achieve greatness"), frustration ("how are we still losing"), operational specs ("83% accuracy, 30-minute windows"), and forward planning ("so we don't have to be disappointed later") all in one paragraph. This is valuable signal, not noise. Your job:

  1. Extract the specs — numbers, formats, constraints, technical requirements buried in the flow
  2. Decode the emotions — frustration points to failure modes, competitive language points to success criteria, forward anxiety points to testing requirements
  3. Preserve the energy — the final prompt should carry the user's drive and ambition, not flatten it into corporate instructions. If they said "miraculous goals," the prompt should aim high. If they said "hungry and thirsty," the prompt should encode that intensity.

Core Questions (ask all of these, but adapt to what the user already told you)

  1. What's the task? — What should the AI do when given this prompt? Get specific: "summarize research papers" is vague; "extract key findings, methodology, and limitations from ML papers into a structured format" is useful.
  2. What's the input? — What will the AI receive? File types, data formats, length, structure. If the user isn't sure, help them think through realistic examples.
  3. What does great output look like? — Ask for a concrete example or description. "Show me what a perfect response looks like for a typical input." If they can't articulate it, that's a signal to explore more.
  4. Who's the audience? — Who reads the output? A developer? A CEO? A student? This shapes tone, depth, and assumed knowledge.
  5. What are the 3 worst ways this could fail? — This is the most important question. Failures become test cases. Push for specifics: "too verbose" is OK; "buries the key finding in paragraph 3 instead of leading with it" is gold.
  6. Any constraints? — Token budget, output format (JSON, markdown, prose), required tools, style guidelines, things it must never do.

Adaptive Questions (ask if relevant)

  • Does this involve a specific library, API, or domain? — If yes, you'll research docs in Phase 2.
  • Are there existing examples of good/bad outputs? — Real examples are the fastest path to a good prompt.
  • What's the deployment context? — CLAUDE.md? API system prompt? SKILL.md? Agent config? This affects format and structure.

Output

After the interview, synthesize what you learned into a structured requirements block. Share it with the user for confirmation before moving on:

## Requirements Summary
- **Task**: [what the AI does]
- **Input**: [what it receives]
- **Output**: [format, structure, example]
- **Audience**: [who reads it]
- **Failure modes**: [the 3+ worst ways it could fail]
- **Constraints**: [token budget, format, rules]
- **Context**: [deployment target, domain]

Get explicit confirmation: "Does this capture it? Anything to add or change?"


Phase 2: Research + Synthesis

Research (conditional)

Only do research when the user mentioned a specific library, API, framework, or domain where up-to-date documentation matters. Use context7 (resolve-library-id then query-docs) for libraries, or web search for APIs and domains.

Skip research for general-purpose prompts (writing assistants, summarizers, etc.) — the interview gives you enough.

Generate Candidates

Create 3-5 structurally different prompt candidates. Each should take a different angle:

  • Candidate A: Minimal — just the essential instructions, bare bones
  • Candidate B: Example-heavy — leads with 2-3 examples, minimal instructions
  • Candidate C: Role-first — strong persona/role definition, then task instructions
  • Candidate D: Structured — uses XML tags, sections, explicit output templates
  • Candidate E (optional): Domain-specific — uses terminology and patterns from research

You don't need to write full prompts for each — outlines with key structural decisions are enough.

Critique

For each candidate, evaluate against the user's stated failure modes:

CandidateFailure Mode 1Failure Mode 2Failure Mode 3Notes
AVulnerableProtectedProtectedToo sparse — no guardrails for FM1
BProtectedProtectedVulnerableExamples don't cover FM3 edge case
...............

Synthesize

Take the strongest elements from each candidate and combine them into a single draft prompt. Explain your choices to the user: "I'm taking the role definition from C, the example pattern from B, and adding explicit guardrails from D for failure mode 1."

Share the draft with the user. This is a checkpoint — get their gut reaction before testing.


Phase 3: Test + Refine

This is where the prompt proves itself. Follow Askell's test-driven loop.

Generate Test Cases

Create 2-3 test cases from the interview, focused on the failure modes the user identified. Each test case has:

  • Input: A realistic example input the prompt would receive
  • Expected behavior: What the output should look like (not exact text — behavioral expectations)
  • Failure to catch: Which failure mode this test targets

Share test cases with the user: "Here are the tests I want to run. Do these look realistic?"

Run Tests

For each test case, spawn a subagent that receives only the draft prompt (as a system prompt) and the test input. The subagent should not know it's being tested — just execute the task.

Save outputs for review.

Grade

Compare each output against the expected behavior. Grade as:

  • Pass: Output meets the behavioral expectation
  • Partial: Some aspects good, some need work (note what)
  • Fail: Output exhibits the failure mode it was supposed to avoid

Show the user the results with the outputs. Ask: "How do these look? Anything surprising?"

Refine Loop

For each failure or partial pass:

  1. Diagnose why the prompt failed (read the full output, not just the verdict)
  2. Add or modify the prompt to address the specific failure
  3. Apply harness engineering: the fix becomes a permanent rule with a comment explaining why it exists
  4. Re-run the failing test case to verify the fix
  5. Re-run all passing test cases to check for regressions

Repeat until all tests pass.

Signal Discipline Pass

Once all tests pass, do a final compression pass:

  1. Count the tokens in the prompt (estimate: ~4 chars per token)
  2. If over ~2.5k tokens, review each section: "Would removing this cause a test to fail?"
  3. Remove anything that doesn't protect against a known failure
  4. Merge redundant instructions
  5. Prefer explaining why over rigid rules — a model that understands the reasoning generalizes better than one following blind rules
  6. Re-run all tests after trimming to make sure nothing broke

Output

Deliver the final prompt in the user's preferred format:

  • File: Write to a path they specify (or suggest a sensible default like PROMPT.md in the current directory)
  • Inline: Output the prompt in a code block they can copy
  • Both: Write to file and show inline

Always include alongside the prompt:

  1. Test cases file (test-cases.md or similar) documenting what was tested and the pass/fail results
  2. Brief rationale — 3-5 sentences explaining the key design decisions and which failure modes drove them

Tips for Writing Great Prompts

These principles should guide every prompt you create:

  • Lead with the role and task, not meta-instructions. "You are a code reviewer who..." beats "When given code, you should..."
  • Use examples for format, not content. Examples teach structure; instructions teach reasoning.
  • Explain the why. "Keep responses under 200 words because these go into a daily digest email that people skim on mobile" is better than "ALWAYS keep responses under 200 words."
  • Anticipate the model's instincts. If you know the model tends to over-explain, add a note about conciseness with context for why. If it tends to hedge, tell it to be direct and explain the audience expects confidence.
  • Structure with XML tags when the prompt has distinct sections (instructions, context, examples, output format). This reduces misinterpretation.
  • Put the most important instructions first and last. Middle sections get less attention (the "lost in the middle" effect).
  • Never use ALL CAPS or multiple exclamation marks for emphasis — explain the reasoning instead. If you find yourself shouting at the model, reframe as: "This matters because..."

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.