Skip to content
Back to search

prompt-improver

Claude Code skill that transforms vague AI prompts into clear, specific, actionable ones. Includes Aristotelian First Principles mode for proof-based prompt design.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ndpvt-web--prompt-improver/badge.svg)](/listings/ndpvt-web--prompt-improver)

HTML

<a href="/listings/ndpvt-web--prompt-improver"><img src="/api/listings/ndpvt-web--prompt-improver/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/ndpvt-web/prompt-improver.git
cp -r prompt-improver ~/.claude/skills/prompt-improver

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 66 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: prompt-improver
  3. description: Optimize prompts for better AI responses. Use when user asks to improve a prompt, refine a prompt, make a prompt better, optimize prompting, "Aristotelian", "first principles", or "proof-based" , review their prompt, or says "/improve-prompt". Transforms vague requests into clear, specific, actionable, logic-based prompts.
  4. ---
  5. # Prompt Improver
  6. Transform vague prompts into clear, specific, actionable ones for better AI responses.
  7. ## Workflow
  8. 1. **Gather context** - Use AskUserQuestion as many times as needed to resolve any doubts or assumptions
  9. 2. **Analyze** - Identify what's unclear, missing, or ambiguous
  10. 3. **Improve** - Apply the Aristotelian framework
  11. 4. **Present** - Show improved prompt with key changes explained
  12. 5. **Refine** - Ask if user wants adjustments
  13. ## Aristotelian Mode (First Principles)
  14. Always actived. produce a prompt that **instructs the receiving LLM to reason from first principles** when executing the task.
  15. The prompt-improver does NOT do the Aristotelian reasoning itself. It crafts a prompt that tells the LLM to:
  16. 1. **Gather context from user** - Ask what system capabilities, tools, and constraints exist. Bake known context (root access, AI model, available tools, domain) directly into the prompt as given axioms.
  17. 2. **Embed the reasoning directive** - The improved prompt tells the LLM to:
  18. - Identify the atomic, irreducible truths of the task before acting
  19. - Interrogate each truth: "Can this be decomposed further? If removed, does the task break? Does it contradict anything?"
  20. - Discard anything that is not strictly necessary
  21. - Build the solution deductively, where every action traces to a stated axiom
  22. - Verify the result against the axioms at the end
  23. 3. **Structure the output prompt** with these sections:
  24. ```
  25. REASONING DIRECTIVE: [Instruct the LLM to use first-principles reasoning]
  26. GIVEN AXIOMS: [Known truths about system, capabilities, domain -- baked in]
  27. TASK: [What to accomplish]
  28. METHOD: [Tell LLM to discover task-specific axioms, interrogate them, then build deductively]
  29. VERIFICATION: [Tell LLM to check its result against its axioms]
  30. ```
  31. **Output format for Aristotelian mode:**
  32. ```markdown
  33. ## Analysis
  34. [What context was embedded and why]
  35. ## Improved Prompt (Aristotelian)
  36. [The complete prompt with reasoning directive, given axioms, task, method, and verification]
  37. ## What This Prompt Does
  38. - Tells the LLM to [specific reasoning behavior]
  39. - Bakes in [specific context] so the LLM does not hallucinate it
  40. ```
  41. See references/aristotelian.md for the full methodology and prompt structure.
  42. ## References
  43. - **Aristotelian mode**: See references/aristotelian.md for the proof-based first principles methodology
  44. - **Examples**: See references/examples.md for before/after transformations
  45. - **Anti-patterns**: See references/anti-patterns.md for common issues to fix
  46. - **Framework details**: See references/framework.md for the 6-principle improvement framework
README.md · README · 178 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Prompt Improver
  2. A Claude Code skill that transforms vague AI prompts into clear, specific, actionable ones using Aristotelian first-principles reasoning.
  3. ## Installation
  4. ```bash
  5. git clone https://github.com/ndpvt-web/prompt-improver.git
  6. cp -r prompt-improver ~/.claude/skills/prompt-improver
  7. ```
  8. ## How It Works
  9. Invoke the skill with any prompt. Before improving it, the skill uses `AskUserQuestion` — as many times as needed — to clarify any doubts or assumptions about your context, platform, constraints, or goal. Nothing is assumed. Everything is confirmed.
  10. Once context is clear, it produces a prompt structured around Aristotelian first principles: baked-in axioms, reasoning directives, axiom discovery, interrogation, and verification steps.
  11. ---
  12. ## Example
  13. ### Input
  14. > Create a system that reads sales data and sends a weekly report
  15. ### What the skill asks (examples)
  16. - What format is the sales data in? (CSV, database, API?)
  17. - Where should the report be sent? (Email, Slack, dashboard?)
  18. - What defines a "week"? (Calendar week, rolling 7 days?)
  19. - Who is the audience — technical or non-technical?
  20. ### Output (Aristotelian prompt)
  21. > **Reasoning Directive:** Before acting, reason from first principles. Do not assume anything that cannot be traced to a verified ground truth.
  22. >
  23. > **Given Axioms:**
  24. > - Sales data is in CSV format, updated daily at midnight
  25. > - Report is delivered via email every Monday at 9am
  26. > - Audience is non-technical (no raw numbers — trends and summaries only)
  27. > - Python environment with pandas and smtplib available
  28. >
  29. > **Axiom Discovery:** Identify what must be true for this pipeline to succeed. What, if false, breaks it?
  30. >
  31. > **Task:** Build a weekly sales report pipeline
  32. >
  33. > **Method:** For each implementation decision, trace it back to an axiom. If you cannot justify a step, stop and identify what is missing.
  34. >
  35. > **Verification:** After completion, check the output against every axiom. Does it satisfy them all?
  36. ---
  37. ## Example 2: Vague App Idea → Production Brief
  38. ### Original prompt
  39. > I want to make an app that tracks my daily water intake — world class design, best possible app, millions of users at once
  40. ### What the skill asked (clarification dialogue)
  41. - What environment will this run in? *(Claude Code / HappyCapy workspace confirmed)*
  42. - What stack is available? *(static HTML, CDN frameworks, no npm confirmed)*
  43. - What's the scalability requirement? *(millions of concurrent users confirmed)*
  44. - What does "world class design" mean to you? *(WCAG AA, mobile-first, micro-animations confirmed)*
  45. > The axioms in the improved prompt below are not invented — each one came from the user answering a real question.
  46. ### Improved prompt (Aristotelian)
  47. ```
  48. REASONING DIRECTIVE:
  49. Before writing a single line of code or making any design decision, you must
  50. reason from first principles. Identify the atomic, irreducible truths of this
  51. task. Interrogate each: "Can this be decomposed further? If removed, does the
  52. core goal break? Does it contradict anything?" Discard anything not strictly
  53. necessary. Build the solution deductively — every decision must trace to a
  54. stated axiom. Verify the final architecture against your axioms before
  55. producing output.
  56. GIVEN AXIOMS (treat these as ground truth — do not re-derive):
  57. - Environment: Claude Code in a HappyCapy workspace with full bash, file
  58. write, and static file server access. No build step needed for static HTML.
  59. - Output path: ./outputs/ is served publicly as a static web server.
  60. - Stack available: HTML5, CSS3, vanilla JS, or any CDN-hosted framework
  61. (React via CDN, Chart.js, Tailwind via CDN, etc.) without npm.
  62. - Scalability target: Architecture must support millions of concurrent users.
  63. This means: stateless frontend, CDN-distributable assets, backend-agnostic
  64. data layer (localStorage for MVP, with a clear upgrade path to
  65. Supabase/Firebase/PostgreSQL).
  66. - Design bar: "World class" means: consistent design system, WCAG AA
  67. accessibility, sub-100ms interactions, mobile-first responsive layout,
  68. micro-animations that reinforce behavior, zero visual clutter.
  69. - Core domain truth: Water intake tracking has one irreducible job — reduce
  70. the cognitive load of remembering to drink water and make progress visible
  71. at a glance.
  72. TASK:
  73. Build a complete, production-quality daily water intake tracker web app and
  74. output it as a single self-contained file at ./outputs/water-tracker.html.
  75. METHOD (apply to this task):
  76. 1. AXIOM DISCOVERY — Before coding, state aloud the irreducible truths of
  77. this specific product:
  78. - What is the minimum data model that cannot be removed without breaking
  79. the app?
  80. - What is the minimum UI surface that cannot be removed without breaking
  81. the user's mental model?
  82. - What interactions are load-bearing vs. decorative?
  83. 2. INTERROGATE each axiom: "Is this truly atomic? Does removing it collapse
  84. the experience? Does it contradict scalability or simplicity?"
  85. 3. DEDUCTIVE BUILD — Every feature, component, and design decision must be
  86. derived from your axioms. No feature added from habit or assumption.
  87. 4. IMPLEMENT with these non-negotiable standards derived from the axioms:
  88. - Design system: define CSS custom properties (tokens) for color, spacing,
  89. typography FIRST — never hardcode values
  90. - Mobile-first: base styles for 375px, enhanced for 768px+
  91. - Performance: no blocking resources, all assets inline or CDN
  92. - Data: localStorage with a schema that mirrors what a real DB table would
  93. look like (so migration is trivial)
  94. - Animations: CSS transitions only, respects prefers-reduced-motion
  95. - Accessibility: semantic HTML, aria labels, keyboard navigable
  96. 5. FEATURES to derive deductively (include only what axioms justify):
  97. - Daily intake goal (configurable, default 2.5L)
  98. - Quick-add buttons (common cup/bottle sizes)
  99. - Visual progress indicator (ring or bar — choose based on axiom for
  100. "progress visible at a glance")
  101. - Daily history (last 7 days minimum)
  102. - Streak counter (behavioral reinforcement axiom)
  103. - Hydration reminders (browser Notification API)
  104. - Unit toggle (ml / oz)
  105. VERIFICATION:
  106. After building, check each decision against your stated axioms:
  107. - Does every UI element trace to an axiom?
  108. - Is there anything present that no axiom justifies? Remove it.
  109. - Does the data model support a million-user backend migration with zero
  110. schema changes?
  111. - Does the design pass the "glance test" — can a user know their status in
  112. under 2 seconds?
  113. - Run through the app as a first-time user with no instructions. Does it
  114. work without explanation?
  115. ```
  116. ---
  117. ## Quick Mode
  118. Say **"quick improve"** to skip the clarification questions. The skill makes reasonable assumptions and labels each one explicitly as ASSUMED (not confirmed).
  119. ---
  120. ## File Structure
  121. ```
  122. prompt-improver/
  123. SKILL.md # Main skill definition
  124. references/
  125. framework.md # 6-principle improvement framework
  126. aristotelian.md # First principles methodology
  127. examples.md # Before/after transformations
  128. anti-patterns.md # Common prompt issues and fixes
  129. ```
  130. ## License
  131. MIT
  132. ---
  133. ## Keywords
  134. For the search engines, the LLMs, and the curious humans who find things by typing random words into the void.
  135. prompt improvement tool, AI prompt optimizer, prompt engineering skill, Claude Code skill, Aristotelian reasoning AI, first principles prompting, prompt refinement tool, better AI prompts, prompt structure framework, axiom-based prompting, logical prompt design, discrete math AI reasoning, formal proof prompting, deductive AI instructions, LLM prompt builder, prompt clarification tool, interactive prompt refiner, context-aware prompt generator, AI prompt template, prompt engineering framework, vague to clear prompt, prompt best practices, AI reasoning directive, given axioms prompt pattern, prompt verification method, prompt anti-patterns, Claude skill install, Anthropic Claude prompt, AI task specification, structured AI instructions, prompt decomposition, irreducible prompt truths, prompt interrogation method, prompt deductive build, LLM instruction design, production-grade AI prompt, scalable AI prompt pattern, prompt discovery axioms, AI prompt grounding, constraint-aware prompting, AI brief generator, prompt improvement automation, no-assumption prompting, confirmed context prompting

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.