agy-prompting

Agy Prompting

Use this skill when agy:agy-rescue needs to ask Agy for help. Agy runs Claude and Gemini family models in print mode, so the prompt is the entire contract for the run.

Prompt Agy like an operator, not a collaborator. Keep prompts compact and block-structured with XML tags. State the task, the output contract, the follow-through defaults, and the small set of extra constraints that matter.

Core rules:

• Prefer one clear task per Agy run. Split unrelated asks into separate runs.
• Tell Agy what done looks like. Do not assume it will infer the desired end state.
• Add explicit grounding and verification rules for any task where unsupported guesses would hurt quality.
• Prefer better prompt contracts over picking a bigger model or adding long natural-language explanations.
• Use XML tags consistently so the prompt has stable internal structure.

Default prompt recipe:

• <task>: the concrete job and the relevant repository or failure context.
• <structured_output_contract> or <compact_output_contract>: exact shape, ordering, and brevity requirements.
• <default_follow_through_policy>: what Agy should do by default instead of asking routine questions.
• <verification_loop> or <completeness_contract>: required for debugging, implementation, or risky fixes.
• <grounding_rules> or <citation_rules>: required for review, research, or anything that could drift into unsupported claims.

When to add blocks:

• Coding or debugging: add completeness_contract, verification_loop, and missing_context_gating.
• Review or adversarial review: add grounding_rules, structured_output_contract, and dig_deeper_nudge.
• Research or recommendation tasks: add research_mode and citation_rules.
• Write-capable tasks: add action_safety so Agy stays narrow and avoids unrelated refactors.

How to choose prompt shape:

• Use the plugin's review or adversarial-review commands when the job is reviewing local git changes. Those prompts already carry the review contract.
• Use task when the task is diagnosis, planning, research, or implementation and you need to control the prompt more directly.
• Use task --resume-last for follow-up instructions on the same Agy conversation. Send only the delta instruction instead of restating the whole prompt unless the direction changed materially.

Model fit (no effort flag — effort tiers are baked into the labels):

• Default (unset): Gemini 3.5 Flash (High) — fast, fine for bounded diagnosis and narrow fixes.
• pro / pro-high: larger Gemini tier for long-context investigation or multi-file work.
• sonnet / opus: Claude thinking models for the hardest reasoning, design judgment, or adversarial review.
• gpt-oss: lightweight alternative for simple mechanical tasks.
• Only pass --model when the user asked for one; otherwise leave it unset.

Working rules:

• Prefer explicit prompt contracts over vague nudges.
• Use stable XML tag names that match the block names from the reference file.
• Do not escalate the model first. Tighten the prompt and verification rules before escalating.
• Ask Agy for brief, outcome-based progress updates only when the task is long-running or tool-heavy.
• Keep claims anchored to observed evidence. If something is a hypothesis, say so.

Prompt assembly checklist:

1. Define the exact task and scope in <task>.
2. Choose the smallest output contract that still makes the answer easy to use.
3. Decide whether Agy should keep going by default or stop for missing high-risk details.
4. Add verification, grounding, and safety tags only where the task needs them.
5. Remove redundant instructions before sending the prompt.

Reusable blocks live in references/prompt-blocks.md. Concrete end-to-end templates live in references/agy-prompt-recipes.md. Common failure modes to avoid live in references/agy-prompt-antipatterns.md.