# SOL ENGINE
**Production prompt engineering for GPT-5.6.**
**Audit. Optimize. Evaluate. Ship.**
[简体中文](README.zh-CN.md)
[](LICENSE)
[](https://agentskills.io/)
[](https://github.com/wp-a/gpt-5.6-prompt-engine/actions/workflows/validate.yml)
SOL ENGINE combines an installable agent skill with two local, deterministic tools: a static prompt audit and an evaluation regression gate. The skill supplies the engineering workflow; the tools make selected checks repeatable. They do not call a model, rewrite files, or decide whether a prompt is better on their own.
Use it to remove behavioral ambiguity while preserving output schemas, permissions, tool contracts, and business rules. A shorter prompt is a candidate, not proof of improvement.
## Before and after
An illustrative cleanup, not a measured model result:
**Before**
```text
Always inspect the repository before editing. Be concise. Think carefully.
Always inspect the repository before editing. Complete the requested implementation,
then run the relevant tests. Preserve existing user changes unrelated to the request.
Return JSON with exactly these keys:
- summary: concise description of the changes
- tests: validation commands run and their outcomes
Do not modify files outside the repository.
```
**Candidate**
```text
Inspect the repository before editing.
Work only inside the repository. Preserve existing user changes unrelated to the
request. Complete the requested implementation, then run the relevant tests.
Return JSON with exactly these keys:
- summary: concise description of the changes
- tests: validation commands run and their outcomes
```
The candidate removes duplication and vague style instructions while retaining the permission boundary, completion behavior, and output contract. Compare it against the original on representative cases before rollout.
## Capabilities
| Capability | What it provides | Boundary |
| --- | --- | --- |
| Prompt audit | Stable findings for duplication, vague directives, long tool descriptions, and profile-specific contract gaps | Heuristics require review |
| Surgical optimization | A workflow for separating behavior from redundant procedure | Preserves explicit contracts and trust layers |
| Migration review | Required compatibility changes separated from optional measured candidates | Does not guess runtime defaults |
| Evaluation gate | Baseline/candidate aggregation with quality, token, latency, and cost thresholds | Uses measurements you supply |
| Source grounding | A dated map to official OpenAI documentation | Changeable facts must be rechecked |
## Install
### Agent Skills CLI
Install the nested skill from the public repository:
```bash
npx skills add wp-a/gpt-5.6-prompt-engine --skill gpt-5-6-prompt-engine -g -y
```
### Codex
Ask Codex to use its built-in `$skill-installer` with the GitHub tree URL:
```text
$skill-installer install https://github.com/wp-a/gpt-5.6-prompt-engine/tree/main/skills/gpt-5-6-prompt-engine
```
The Codex installer places the skill under `$CODEX_HOME/skills/gpt-5-6-prompt-engine` and makes it available on the next turn. Start a new turn or restart a client that does not hot reload skills.
`main` tracks the latest repository state. Immutable tag pins will be documented once a release exists.
## Use the skill
Invoke it by name and provide the prompt, tool stack, migration, or evaluation goal:
```text
Use $gpt-5-6-prompt-engine to audit this coding-agent prompt, preserve its JSON
schema and write boundary, and return findings plus a minimal candidate rewrite.
```
The skill's default sequence is audit, classify constraints, optimize surgically, evaluate against a controlled baseline, and ship only after the gate passes. See the complete examples:
- [Coding agent](examples/coding-agent.md)
- [Research agent](examples/research-agent.md)
- [Customer support](examples/customer-support.md)
## CLI tools
Both CLIs use only the Python 3.10+ standard library and have zero dependencies beyond Python. They need no API key and make no network request.
### Static prompt audit
[`audit_prompt.py`](skills/gpt-5-6-prompt-engine/scripts/audit_prompt.py) accepts a text prompt or a JSON tool stack, writes findings to stdout, and leaves the input unchanged. Profiles are `general`, `agent`, and `research`; output can be Markdown or JSON.
```bash
python skills/gpt-5-6-prompt-engine/scripts/audit_prompt.py tests/fixtures/duplicate-prompt.txt --profile agent
```
Use `-` as the input path to read plain text from stdin. Findings are deterministic review signals, not semantic proof of a defect.
### Evaluation regression gate
[`compare_eval_runs.py`](skills/gpt-5-6-prompt-engine/scripts/compare_eval_runs.py) compares records with matching IDs, aggregates available metrics, and exits with status `2` when a configured regression gate fails.
```bash
python skills/gpt-5-6-prompt-engine/scripts/compare_eval_runs.py examples/eval-data/baseline.jsonl examples/eval-data/candidate.jsonl --max-success-rate-drop 0 --max-token-increase-pct 5
```
Additional gates cover mean latency and cost per successful task. Quality, required evidence, and reliability should pass before efficiency metrics justify rollout.
## Evaluation JSONL
Store one attempt per line in each JSONL file. `id` and `success` are required. Resource fields are optional, but a metric is comparable only when it is present for every record in both runs.
```json
{"id":"case-001","success":true,"latency_ms":842,"input_tokens":910,"output_tokens":184,"reasoning_tokens":96,"cost_usd":0.0124}
```
Use the same non-empty ID set for baseline and candidate. `success` must represent a predeclared task contract, not a post-hoc judgment. Token counts are nonnegative integers; latency and cost are nonnegative finite numbers. Start with the checked-in [baseline JSONL sample](examples/eval-data/baseline.jsonl).
## Update and remove
### Agent Skills CLI-managed installs
Keep lifecycle operations in the same manager that created the global install:
```bash
npx skills update gpt-5-6-prompt-engine -g -y
```
```bash
npx skills remove gpt-5-6-prompt-engine -g -y
```
These commands apply only to installs managed by Agent Skills CLI.
### Codex installs
The Codex installer deliberately refuses to overwrite an existing destination. Remove an existing Codex-managed copy with the controls available in that Codex client, then invoke the `main` URL for the latest repository state. The Agent Skills CLI lifecycle commands above do not manage Codex installs.
Start a new turn or restart clients that cache installed skills.
### Manual installs
Only if you copied the skill manually, update it by replacing that copied `gpt-5-6-prompt-engine` directory and remove it by deleting only that directory. This filesystem guidance does not apply to manager-owned installs. Removing an installed copy does not delete this repository or evaluation data stored elsewhere.
## Repository map
```text
skills/gpt-5-6-prompt-engine/
SKILL.md installable workflow
agents/openai.yaml interface metadata
references/ patterns, migration, evaluation, sources
scripts/ deterministic audit and comparison CLIs
examples/
*.md end-to-end prompt examples
eval-data/ baseline/candidate JSONL samples
tests/ unit, structure, and forward-test artifacts
```
## Source grounding
The [official source map](skills/gpt-5-6-prompt-engine/references/official-source-map.md) records the verified date and maps local guidance to canonical pages. Start with OpenAI's [GPT-5.6 model guidance](https://developers.openai.com/api/docs/guides/latest-model), then check the relevant official page for reasoning, tool calling, caching, structured outputs, or the Responses API.
Model IDs, parameters, defaults, availability, pricing, and beta status can change. Recheck the official documentation before making a current claim or production migration.
## Verification
The repository uses standard-library `unittest`, the Agent Skills validator, CLI smoke tests, and six documented forward scenarios. The forward scenarios are manually assessed for semantic behavior; they are not a benchmark or a claim of model-level gains.
See [CONTRIBUTING.md](CONTRIBUTING.md) for the exact local checks.
## Limitations
- Static audit findings identify review candidates; they cannot prove intent or prompt correctness.
- The comparator aggregates supplied measurements; it does not run GPT-5.6, grade outputs, estimate missing metrics, or validate the quality of a success label.
- Example prompts and thresholds are starting points, not universal defaults.
- SOL ENGINE does not guarantee better quality, fewer tokens, lower latency, or lower cost.
- Prompts, tool descriptions, and evaluation files may contain sensitive data; review them before sharing reports.
SOL ENGINE is an independent open-source project and not an official OpenAI product. OpenAI and GPT-5.6 are referenced only to describe compatibility and source grounding.
Released under the [MIT License](LICENSE). Read [CONTRIBUTING.md](CONTRIBUTING.md) before proposing changes and [SECURITY.md](SECURITY.md) before reporting a vulnerability.