prompt-forge

Turn a raw AI prompt into a structured, professional prompt — with a deterministic scorecard, automatic framework selection, and gap detection. Usable three ways: CLI, Node library, or ZCode skill.

© 2026 helal-muneer · MIT License

Why

Hastily written prompts produce weak AI output. prompt-forge fixes that: give it a rough idea, get back a scorecard (clarity, context, constraints, format), a recommended framework (RTF / APE / TAG / RACE / CO-STAR / CREATE / RISEN), and the gaps you should fill before sending.

Features

• Deterministic analyzer — scorecard across Clarity, Context, Constraints, Format; framework recommendation; gap detection; anti-pattern warnings. No network, no deps.
• Three surfaces: CLI (prompt-forge "<text>"), Node library (import { analyze }), and a ZCode skill (/improve-prompt).
• Adaptive output — Markdown for simple prompts, XML tags for complex ones.
• Presets — code-review, article, feature-plan, bug-fix.
• Bilingual — scorecard & explanation in Arabic; improved prompt in English by default.
• Variations — up to 3 alternative framings per request.

Install

As a CLI / library (npm)

npm install @helal-muneer/prompt-forge

Or run once without installing:

npx @helal-muneer/prompt-forge "write a launch announcement"

As a ZCode skill (from source)

git clone https://github.com/helal-muneer/prompt-forge ~/prompt-forge
cd ~/prompt-forge
./install.sh

install.sh symlinks the skill into ~/.agents/skills/improve-prompt and copies the /improve-prompt command into ~/.zcode/commands/.

CLI usage

npx @helal-muneer/prompt-forge "<prompt text>"          # → JSON scorecard + recommended framework
echo "<prompt>" | npx @helal-muneer/prompt-forge        # via stdin

After npm install -g @helal-muneer/prompt-forge, a prompt-forge binary is available:

prompt-forge "<prompt text>"

Example:

$ npx @helal-muneer/prompt-forge "write a launch announcement"
{
  "scorecard": { "clarity": 15, "context": 0, "constraints": 0, "format": 0, "total": 15, "rating": "weak" },
  "recommended_framework": "APE",
  "framework_reason": "very short task suits APE (Action, Purpose, Expectation)",
  "gaps": [ ... ],
  "warnings": []
}

Library usage

import { analyze, recommendFramework, detectGaps } from "@helal-muneer/prompt-forge";

const result = analyze("Write a 150-word launch announcement for AcmeApp (audience: developers, tone: formal, output: bullets + CTA). Avoid hype.");
console.log(result.scorecard.rating);        // "good"
console.log(result.recommended_framework);   // "CO-STAR"

Exports: analyze, recommendFramework, detectGaps, scoreClarity, scoreContext, scoreConstraints, scoreFormat, rate.

ZCode skill usage

/improve-prompt <text> [--framework=name] [--preset=name] [--lang=en|ar] [--variations=N] [--raw]

Examples:

• /improve-prompt write a launch announcement
• /improve-prompt "review this PR" --preset=code-review
• /improve-prompt "plan a payments feature" --framework=CO-STAR --lang=ar --variations=2

Flags: | Flag | Meaning | Default | |------|---------|---------| | --framework | Override recommended framework (RTF, APE, TAG, RACE, CO-STAR, CREATE, RISEN) | auto |

Requirements: Node.js ≥ 18.

git clone https://github.com/helal-muneer/prompt-forge ~/prompt-forge
cd ~/prompt-forge
./install.sh

install.sh symlinks the skill into ~/.agents/skills/improve-prompt and copies the /improve-prompt command into ~/.zcode/commands/.

Usage

/improve-prompt <text> [--framework=name] [--preset=name] [--lang=en|ar] [--variations=N] [--raw]

Examples:

• /improve-prompt write a launch announcement
• /improve-prompt "review this PR" --preset=code-review
• /improve-prompt "plan a payments feature" --framework=CO-STAR --lang=ar --variations=2

Flags: | Flag | Meaning | Default | |------|---------|---------| | --framework | Override recommended framework (RTF, APE, TAG, RACE, CO-STAR, CREATE, RISEN) | auto | | --preset | Apply a preset (code-review, article, feature-plan, bug-fix) | — | | --lang | Output language of the improved prompt | en | | --variations | Number of alternative versions (1–3) | 1 | | --raw | Skip scorecard & explanation; output the prompt only | off |

Develop

npm test                # run analyzer tests
npm run check:privacy   # verify no personal/commercial data
node scripts/analyze-prompt.mjs "<text>"   # inspect analyzer JSON

Layout

SKILL.md               # orchestrator
scripts/               # analyzer + tests + privacy guard (Node ESM, no deps)
references/            # frameworks.md, anti-patterns.md
presets/               # code-review, article, feature-plan, bug-fix
commands/              # /improve-prompt command template
install.sh             # symlink + command install

License

MIT © 2026 helal-muneer