Silverquill

Site: silverquill.amccutcheon.com

Five prompt-engineering skills and a durable optimization loop. Install the skills into your agent with one command, or run the whole pipeline from the terminal with a fresh process per stage.

Release status: Silverquill 2.0.0 is pending npm publication. There is no silverquill package on npm yet; the last published release is promptzilla@1.0.0, the old MCP server. Use the source or the local build until 2.0.0 ships.

Silverquill does not call a model API itself and stores no credentials. The worker you choose — OpenCode, Claude Code or Codex — already has its own authentication.

Quick start

Until 2.0.0 is on npm, clone and build. The commands below run from the repository root.

git clone https://github.com/andymccutcheon/silverquill
cd silverquill && npm install && npm run build
node dist/cli.js install
node dist/cli.js run --request "Write a prompt for a meeting-notes summarizer"

Once 2.0.0 ships, npx silverquill install and npx silverquill run do the same two things without the clone.

install copies the five skills into the agent hosts it detects. run executes the full Compose → Judge → Revise loop and writes the approved prompt to ./prompts/<slug>.md.

Related MCP server: api_agent_mcp

Install the skills

Requires Node.js 22.12 or newer.

node dist/cli.js install

The command detects the agent hosts on this machine and copies all five skills into each one it finds:

If none are found it installs to Claude Code. Re-run the same command to update; the five skill folders are replaced. Upgrading from the pre-rename release also removes the five legacy folders (tasker, metapod, judge-dredd, brian-spillner, prompt-pipeline) when they are present. Use --target, --dir or --dry-run for control:

npx silverquill install --target all
npx silverquill install --target claude,opencode
npx silverquill install --dir ./.claude/skills
npx silverquill install --dry-run

The installed skills are brief, compose, judge, revise and loop. Supporting files for the manual pipeline (DRY-RUN.md, the Python helpers) are installed with loop.

Run the pipeline

Full mode turns a rough request into a prompt, then scores and rewrites it until Judge returns STOP at 9 or higher:

npx silverquill run --request "Write a prompt for a meeting-notes summarizer that returns five bullets"

Optimize-only mode starts from a prompt you already have:

npx silverquill run --prompt ./prompt.md

A trailing argument is shorthand for a Full request:

npx silverquill run "Write a prompt for a release-notes generator"

The default worker is opencode. Choose another and pass a model when you want one:

npx silverquill run --prompt ./prompt.md --worker claude --model claude-sonnet-4-5
npx silverquill run --request "..." --worker codex --model gpt-5

Useful flags:

Exit codes: 0 approved, 2 paused for a decision, 3 capped or blocked with a provisional candidate.

Where the prompt goes

On STOP, the scored prompt is written to ./prompts/<slug>.md (or --out). The file is the prompt itself — no frontmatter, no commentary, ready to paste.

If the run caps at four scoring rounds, blocks on invalid output, or pauses because the score stopped improving, the best scored candidate is written to ./prompts/<slug>.provisional.md and clearly reported as not approved. A plateau pause is resumable:

npx silverquill run --resume <run-id> --decision "Continue; resolve the count conflict first."

Every run also keeps a full record under ~/.silverquill/runs/<run-id>/: the original input, each stage file, retries, scorecards, provenance and run.json. Use --runs-dir to relocate it.

Workers

Each stage runs in a separate process with only that stage's packet. That is real isolation, not an attestation.

The worker must be installed and authenticated already. Silverquill never reads or stores provider keys.

Manual mode

An agent that cannot spawn a worker can still use the durable engine. start creates a run and prints the first dispatch; the agent executes dispatch.instructions with dispatch.input and submits the exact output.

npx silverquill start --request "Write a prompt for a meeting-notes summarizer" --json
npx silverquill status <run-id>
npx silverquill submit <run-id> --dispatch <dispatch-id> --output ./stage-output.md
npx silverquill pause <run-id> --reason "Need a user decision"
npx silverquill resume <run-id> --decision "Keep the current structure"
npx silverquill fix <run-id> --old "notes" --new "meeting notes"
npx silverquill export <run-id> --out ./prompts

status --json includes the active dispatch, so the packet can be handed to a fresh worker without reading run.json. fix accepts repeated --old/--new pairs or --fixes FILE containing [{ "old": "...", "new": "..." }]. Fixes must be quoted exactly in a Judge recommendation, and a fresh Judge confirms the diff before approval.

The five skills

The installed files are the source of truth. The CLI pins each run to the exact skill text it started with, so editing a skill mid-run cannot change the current run.

Pipeline rules

• Compose must return one System Prompt and one Task Prompt with all required headings. It never performs the requested task.

• Judge returns section ratings with quoted evidence, one overall rating, a STOP or CONTINUE verdict, and numbered recommendations. STOP is valid only at 9 or higher; CONTINUE needs 3–5 recommendations.

• Revise returns the complete rewrite between one BEGIN and one END BODY marker plus a checklist accounting for every recommendation. Judge re-scores the body without seeing the checklist.

• A scoring round starts with Judge. Pass 1 counts toward the four-round cap.

• An invalid stage gets one retry. A second invalid output blocks the run and preserves the best scored candidate as provisional.

• A score that does not improve after two rewrites pauses for an explicit decision. It never invents one.

• Exact fixes after STOP are explicit, all-or-nothing, and confirmed by a fresh Judge.

Testing

npm test              # 66 unit, integration and CLI tests
npm run check         # build, type-check, coverage, Python helper tests
npm run test:package  # pack, install into a clean directory, run the pipeline
npm run test:live     # real model through the real three-skill pipeline

npm test uses authored fixtures and does not spend model tokens. npm run test:live runs Full mode against OpenCode and reports the score trajectory; it passes when the pipeline reaches a terminal or decision state with a final or provisional prompt. A blocked run — output that fails the stage contract twice — is a failure.

The live run proves the protocol, validation and state machine against real skill output. It does not prove that a particular prompt is good; Judge can legitimately cap at 8.

Library use

import { Catalog, Pipeline, executeRun, createWorker } from 'silverquill';

const pipeline = new Pipeline(await Catalog.load('./skills'), './runs');
const result = await executeRun({
  pipeline,
  worker: createWorker('claude', { model: 'claude-sonnet-4-5' }),
  mode: 'optimize-only',
  input: 'You summarize notes.',
  outDir: './prompts',
});

Pipeline exposes start, status, submit, pause, resume and applyFixes for manual orchestration. Catalog discovers and validates skill folders.

Package and release

The package publishes to npm as silverquill. Bump version, run npm run check, then npm publish --access public, or trigger the publish GitHub Actions workflow.

Security and limits

• No API keys, no provider accounts, no remote service. Workers use their own auth.

• Run directories are created with owner-only permissions; run files are mode 0600.

• Stage input is capped at 200,000 characters; worker output at 4 MB; each stage defaults to a 15-minute timeout.

• Symlinks, path traversal and artifact tampering are rejected.

• Prompt text stays on disk until you remove it. Run directories can contain private material.

Migrating from 1.x

Version 1.x was Promptzilla, an MCP server. Version 2 is Silverquill, a CLI and a library.

1. Remove the promptzilla entry from your MCP client configuration.

2. Run npx silverquill install.

3. Use npx silverquill run ... or the installed skills directly.

4. Old runs live under ~/.promptzilla-mcp/runs; read one with --runs-dir ~/.promptzilla-mcp/runs. New runs default to ~/.silverquill/runs.

5. The Cloudflare Worker, HTTP transport and MCP-specific tools, prompts and resources are gone. The durable pipeline engine and all five skills remain.

The implementation plan and acceptance criteria are in PLAN.md. Measured verification results are in TEST-RESULTS.md.