ai-prompting

Improve, rewrite, debug, evaluate, and compress prompts for any LLM agent.

ai-prompting ships in two layers — an Anthropic-style Skill that any compatible agent can apply semantically, and a deterministic Node.js CLI that runs without API keys, without LLM calls, and without runtime dependencies. The CLI is the verifiable baseline. The Skill is where the real semantic gains happen.

30-second quickstart

# Improve any prompt from your shell:
npx ai-prompting improve --prompt "Help me write a sales email"

# Or pipe one in:
echo "scrivi una mail di vendita" | npx ai-prompting improve --mode final_only

# Verify install health:
npx ai-prompting doctor

In a Claude Code session (or any host that supports Skills) the same logic is invokable as a slash command:

/ai-prompting:improve scrivi una mail al manager per chiedere un aumento --mode diagnostic

Table of contents

• What it does
• How it works
• Install
• CLI
• Install as a Skill
• Library API
• Output modes
• The 100-point rubric
• Agent compatibility
• Examples (input → output)
• Doctor
• FAQ
• Limitations
• Contributing
• Changelog
• License

What it does

You give it a vague, padded, or unstructured prompt. It returns a clearer, cheaper, more reliable version — calibrated to the target agent, task type, and output you need.

Concretely, on every prompt it:

1. Detects language (it/en) and task type (research, coding, writing, correspondence, analysis, data-extraction, agentic-workflow, creative, business, education, general).
2. Strips padding that hurts modern reasoning models — "you are a world-class…", "take a deep breath", "think step by step", "I will tip you…" plus Italian variants ("sei un esperto di livello mondiale", "fai un respiro profondo", "pensaci passo passo").
3. Decides whether to ask for clarification (only when info is critical, contradictions exist, or the domain is high-risk: legal, medical, financial, security, production code).
4. Rewrites with a canonical XML scaffold (<role>, <objective>, <context>, <task>, <constraints>, <output_format>, <quality_bar>), adding a section only when it has something true to say. A prompt that is already well specified — 25+ words that state their output format or at least two explicit constraints — keeps its own structure and only loses padding (--scaffold always forces the scaffold).
5. Scores structural coverage on a 100-point heuristic rubric (9 categories), before/after.
6. Surfaces every assumption it made as [ASSUMPTION: …] — so you can correct without rerunning.

How it works

       ┌─────────────────────────────┐
       │  USER: "improve my prompt"  │
       └──────────────┬──────────────┘
                      ▼
       ┌─────────────────────────────┐
       │  classify: lang, task type, │
       │  target agent (if declared) │
       └──────────────┬──────────────┘
                      ▼
                ╱╲ critical info ╱╲
               ╱   missing?       ╲
                ╲ yes ◄──► no    ╱
                 ▼              ▼
       ┌──────────────┐  ┌──────────────┐
       │ ask ≤ 3 Qs   │  │ proceed with │
       │ (multi-      │  │ [ASSUMPTION] │
       │  choice)     │  │  markers     │
       └──────┬───────┘  └──────┬───────┘
              └─────────┬───────┘
                        ▼
       ┌─────────────────────────────┐
       │  strip padding              │
       │  scaffold XML               │
       │  score 0-100                │
       └──────────────┬──────────────┘
                      ▼
       ┌─────────────────────────────┐
       │  return in chosen mode:     │
       │  final_only / compact /     │
       │  standard / diagnostic      │
       └─────────────────────────────┘

Two layers. The Skill (SKILL.md + references/) is read by a host agent (Claude Code, Codex CLI, Cursor, Gemini CLI, etc.); the agent applies the procedure with its own model. The CLI runs the same decisions deterministically, locally, with no LLM call — useful for batch jobs, CI gates, smoke tests, and as a verifiable baseline.

Install

Requires Node.js ≥ 18. No runtime dependencies.

# One-off use:
npx ai-prompting <command>

# Project install:
npm install --save-dev ai-prompting

# Global install:
npm install -g ai-prompting

From source:

git clone https://github.com/reasance/ai-prompting.git
cd ai-prompting
npm install
npm run build
node dist/src/cli.js doctor

CLI

ai-prompting improve --prompt "Help me write something good"
ai-prompting improve --file ./prompt.txt --mode diagnostic
ai-prompting improve --prompt "..." --task research --token-budget minimal
cat prompt.txt | ai-prompting improve --mode final_only
ai-prompting doctor
ai-prompting --help

This is the beginning of the README. Read the rest at the original. Read the full README ↗