🚀 Prompt Optimizer — Pure Textual Tri-CLI Skill

A state-of-the-art, stateless, zero-dependency, pure-textual prompt optimization skill. Engineered for seamless cross-compatibility across Claude Code, Codex, and Gemini CLI using dedicated adapter configurations and an idempotent, multi-target installer.

---

🌟 Key Features

• R-O-C-V-F Framework Integration: Automatically structures raw queries using the robust Role-Objective-Context-Constraints-Format framework.
• Auto-Adaptive Profiles: Detects user intent and switches between core and specialized profiles (developer, writer, analyst, general, marketing, researcher, business).
• Zero-Hallucination Ambiguity Handling: If the input is too vague, it refrains from inventing details. Instead, it asks 1-3 highly concise questions to clarify constraints and context.
• Transparent Language Preservation: Evaluates user prompts in their original language (e.g., English, Italian, Spanish) and outputs the optimized prompt in that same language.
• Pure Clean Output: Delivers only the optimized prompt inside a single fenced text block. No preambles, follow-up remarks, or conversational fluff.

---

🛠 The R-O-C-V-F Optimization Framework

The skill transforms raw inputs into highly precise system instructions based on the following structure:

1. Role (R): Instills an expert identity or perspective inside the LLM.
2. Objective (O): Defines a precise, action-oriented goal.
3. Context (C): Provides the background and assumptions necessary for a high-quality response.
4. Constraints (V): Restricts boundaries (e.g., tone, style, length, forbidden approaches).
5. Format (F): Explicitly guides the response layout or structure.

Tip

The optimizer only builds R-O-C-V-F sections that add real value for the specific query. Avoiding fluff sections is the cornerstone of good prompt engineering.

---

📁 Repository Architecture

This project strictly follows the standard Tri-CLI modular architecture:

prompt-optimizer/
├── SKILL.md                      # Frontmatter & core optimizer workflow instructions
├── agents/
│   ├── openai.yaml               # Metadata UI configuration consumed by Codex/OpenAI
│   └── claude.yaml               # Symmetry documentation-only file for Claude Code
├── references/
│   ├── framework.md              # R-O-C-V-F methodology details, worked & negative examples
│   ├── profiles.md               # Dynamic profile triggers and emphasis definitions
│   ├── claude-adapter.md         # Deployment & activation notes for Claude Code
│   ├── codex-adapter.md          # Deployment & activation notes for Codex
│   └── gemini-adapter.md         # Deployment & activation notes for Gemini CLI
└── scripts/
    ├── install-skill.sh          # Idempotent, safe multi-target installer
    └── package-skill.sh          # Clean, reproducible .skill package generator

---

🚀 Installation & Setup

Deploy the skill to all supported CLI environments concurrently in just one command:

bash scripts/install-skill.sh

Advanced Installation Options

• Dry Run (Preview changes):

  bash scripts/install-skill.sh --dry-run

• Install to a Custom Target:

  bash scripts/install-skill.sh --target /path/to/custom/skills/prompt-optimizer

🛡️ Smart Backup Protection

To ensure safety and reliability:

• The installer automatically backs up existing divergent installations.
• Backups are written to a dedicated skill-backups/ directory outside of the active skills/ path (e.g., ~/.claude/skill-backups/). This prevents CLI loaders from indexing backup folders as phantom duplicate skills.
• Includes a robust automatic rollback routine if copying fails.

---

🔌 CLI Compatibility & Activation

Since LLM clients load skills differently, the project provides native configurations for each platform:

CLI Tool	Loading Mechanism	Default Directory	Project Integration Guide
Claude Code	Automatic via description	~/.claude/skills/	references/claude-adapter.md
Codex	Via agents/openai.yaml	~/.codex/skills/ + ~/.agents/skills/	references/codex-adapter.md
Gemini CLI	Directive or forced activation	~/.gemini/skills/	references/gemini-adapter.md

Workspace Integration Directive

To ensure the prompt optimizer is always-on for a project workspace, place the following directive in your root configuration file (CLAUDE.md, AGENTS.md, or GEMINI.md):

When the user provides a raw prompt to improve, read the skill definition at `~/.gemini/skills/prompt-optimizer/SKILL.md` (and its referenced files under `references/` in the same directory if needed) and apply it: use Role-Objective-Context-Constraints-Format, pick the best-fit profile, and return only the optimized prompt in a fenced text block in the user's input language.

---

📊 Qualitative Validation & Performance

The skill has been thoroughly verified across multiple edge cases. Below is an example of a simple raw query and its optimized output:

Case 1: Creative Writer (Italian)

• Raw Input: scrivimi una lettera commerciale per chiedere la disdetta di un abbonamento
• Optimized Prompt Output:

  ## ROLE
  Agisci come un esperto di comunicazione aziendale e relazioni con i clienti.
  
  ## OBJECTIVE
  Redigi una lettera commerciale formale, chiara e concisa per richiedere la disdetta di un abbonamento.
  
  ## CONTEXT
  La lettera deve comunicare formalmente la volontà di interrompere un abbonamento attivo, richiedere la cessazione di eventuali addebiti futuri e sollecitare una conferma scritta dell'avvenuta ricezione e della data effettiva di disdetta.
  
  ## CONSTRAINTS
  - Usa un tono formale, professionale e assertivo.
  - Non includere lamentele o giustificazioni personali per la disdetta.
  - Inserisci segnaposto chiari (es. [Nome], [Codice Abbonamento]) per i dati che il mittente dovrà completare.
  
  ## FORMAT
  Struttura la lettera commerciale standard con:
  1. Intestazione (Mittente / Destinatario)
  2. Data e Luogo
  3. Oggetto
  4. Corpo della lettera (Dichiarazione di disdetta e riferimenti contrattuali)
  5. Richiesta di conferma
  6. Formula di chiusura e firma
  

---

🤝 Collaboration & Standards

This project has been collaboratively developed by autonomous agents under the cli-collaboration protocol, maintaining full documentation integrity, explicit ownership limits, and a clean Git workflow.

License

This project is licensed under the MIT License - see the LICENSE file for details.