ai-prompt-tune

---
name: ai-prompt-tune
description: "Optimizes prompts, system messages, and skill descriptions using explicit-over-implicit, show-do-not-tell, and rationale-embedding techniques. Trigger for 'this prompt is not working', 'optimize this skill description', 'improve triggering', 'rewrite this instruction', 'CSO-optimize'. Pass `--skill name` to optimize any skill's description field. Not for creating new skills; use /ai-scaffold instead. Not for evolving the entire skill body; use /ai-skill-improve instead."
effort: mid
argument-hint: "[text]|--skill [name]"
mode: agent
tags: [meta, optimization, prompts]
model_tier: sonnet
mirror_family: copilot-skills
generated_by: ai-eng sync
canonical_source: .claude/skills/ai-prompt-tune/SKILL.md
edit_policy: generated-do-not-edit
---



# Prompt Tune

## Purpose

Prompt optimization and creation. Improves prompts, skill descriptions, and agent instructions using proven techniques: explicit over implicit, examples over rules, structured formatting, and positive framing. Can auto-enhance prompts for other skills or manually optimize user-provided text.

## Trigger

- Command: `/ai-prompt-tune "<text>"` (optimize text) or `/ai-prompt-tune --skill <name>` (optimize a skill's description)
- Context: writing a new prompt, improving an existing skill's description, crafting agent instructions.

## When to Use

- Writing or refining skill `description` fields (CSO optimization)
- Crafting system prompts for AI integrations
- Improving agent instruction clarity
- Before publishing any prompt-based artifact

## Optimization Techniques

Apply these in order of impact:

### 1. Be Explicit Over Implicit

| Before | After |
|--------|-------|
| "Handle errors properly" | "Wrap database calls in try/except, log the exception with stack trace, return a structured error response with HTTP 500" |
| "Follow best practices" | "Apply guard clauses for early return, extract methods over 20 lines, name variables by intent not type" |

### 2. Show, Do Not Tell

Replace rules with examples. One concrete example is worth five abstract instructions.

```
Bad:  "Use descriptive names"
Good: "Name variables by what they represent:
       - `user_count` not `n`
       - `is_valid` not `flag`
       - `retry_delay_seconds` not `delay`"
```

### 3. Structure with XML Tags or Markdown

Use clear structural markers for different sections. Group related instructions. Use tables for multi-dimensional comparisons.

### 4. Explain WHY for Each Rule

Rules without rationale get ignored or misapplied. Every constraint should include its motivation.

```
Bad:  "Max 3 retries"
Good: "Max 3 retries (beyond 3, the underlying issue is systemic, not transient -- escalate instead of retrying)"
```

### 5. Positive Framing

State what TO do, not what NOT to do. The brain processes positive instructions faster.

```
Bad:  "Don't use generic error messages"
Good: "Include the specific operation, input value, and expected format in every error message"
```

### 6. CSO Optimization (for skill descriptions)

The `description` field is a search query match surface. Optimize for triggering conditions, not capability summaries.

Pattern: `"Use when [specific situation + observable trigger]"`

```
Bad:  "Database migration planning tool"
Good: "Use when planning database schema changes, assessing migration locking impact, or designing rollback procedures"
```

### 7. Cialdini Principles (for discipline-enforcing skills)

For skills that enforce process (guard, verify, commit):
- **Authority**: cite specific standards and their rationale
- **Consistency**: reference past decisions and established patterns
- **Social proof**: "teams that skip this step spend 3x longer debugging"

## Workflow

### Optimizing text

1. **Analyze** -- identify which techniques are missing from the input.
2. **Apply** -- rewrite applying all relevant techniques.
3. **Compare** -- present before/after with annotations explaining each change.
4. **Validate** -- check the optimized version is not longer than necessary (concise beats comprehensive).

### Optimizing a skill description

1. **Read skill** -- load `.github/skills/ai-{name}/SKILL.md`.
2. **Extract current description** -- from frontmatter.
3. **CSO-optimize** -- rewrite using triggering-condition pattern.
4. **Present** -- show before/after for approval.
5. **Apply** -- update the frontmatter if approved.
6. **Sync mirrors** -- run `python scripts/sync_command_mirrors.py` to propagate the updated description to `.github/`, `.codex/`, and `.agents/` mirrors. Verify no tests break.

## Quick Reference

```
/ai-prompt-tune "check if the code follows our standards"   # optimize this text
/ai-prompt-tune --skill governance                            # optimize governance's description
/ai-prompt-tune --skill commit                                # optimize commit's description
```

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Optimizing for length (making it longer = better) | Concise and specific beats long and vague |
| Adding hedging language ("try to", "if possible") | Be direct: state the expected behavior |
| Removing context while shortening | Keep the WHY, remove the fluff |

## Examples

### Example 1 — optimize a vague text prompt

User: 'optimize this: "check if the code follows our standards"'

```
/ai-prompt-tune "check if the code follows our standards"
```

Rewrites to a specific, observable instruction (e.g. "Run ruff on the staged hunks; flag any violation of lines 1-N of `.ai-engineering/overrides/python/conventions.md`; report findings as a Markdown table"), shows before/after with annotations.

### Example 2 — CSO-optimize a skill's description

User: "optimize the description for /ai-governance"

```
/ai-prompt-tune --skill ai-governance
```

Reads `.github/skills/ai-governance/SKILL.md`, rewrites the description with explicit triggers + negative scoping, presents before/after, applies on approval, runs `sync_command_mirrors.py`.

## Integration

Called by: user directly, `/ai-skill-improve` (Phase 4 rewrite). Calls: `python scripts/sync_command_mirrors.py` (after `--skill` updates). See also: `/ai-scaffold` (new skills), `/ai-skill-improve` (full skill rewrite from pain).

$ARGUMENTS