zach-prompting

Files (3)

• SKILL.md
• openai.yaml · agents/
• vendor-guidance.md · references/

SKILL.md (first lines)

# Zach Prompting

## Goal

Produce the smallest justified revision that makes an instruction artifact easier for an agent to follow without weakening its outcome, evidence, safety, permission, output, or validation contract.

Treat brevity as a means, not the success metric. Call a change an improvement only when its behavior is verified on representative work.

## Select the mode

- **Review:** Inspect and report findings. Do not edit when the user asked only for assessment.
- **Rewrite:** Return the revised artifact or apply an in-scope edit when the user asked for a change.
- **Debug:** Use real failures or traces to find a likely instruction-level cause, then propose or make a surgical change.
- **Migrate:** Establish the current and target model, runtime, endpoint when applicable, supported settings, prompt, tools, reasoning or effort setting, and eval baseline. Change one variable group at a time.

Infer the mode from the request. Ask only when choosing incorrectly would cause an unauthorized edit or materially different result.

## Preserve the requirements

1. **Recover intent.** Read the whole target plus governing instructions and any referenced files that affect its behavior. Identify the audience, runtime, model, request type, and the larger purpose the artifact serves.
2. **Map what must survive.** Record the user-visible outcome, success criteria, true invariants, evidence rules, authorization boundary, relevant tools, required output, validation, and stop conditions. Preserve explicit user values.
3. **Find behavioral friction.** Locate contradictions, repeated rules, outdated instructions, behavior-neutral examples, irrelevant tools, vague tone labels, unneeded absolutes, keyword shortcuts, hidden approval rules, unsupported claims, and missing completion criteria.
4. **Make a narrow revision.** Lead with the outcome. Keep one rule per behavior. Use absolutes only for invariants; use decision rules for judgment. State safe autonomy and approval boundaries once. Add detail only where it changes behavior.
5. **Check the result.** Compare the revision against the preserved contract. Run available representative evals or validation. For consequential or complex changes, prefer a fresh-context verifier over self-critique.

Do not force a small prompt into a large template. For complex artifacts, use this order when it helps: context, goal, success criteria, constraints, tools, output, stop rules.

## Editing rules

### Outcomes and completion

- Describe the destination and completion bar before prescribing process.
- Retain required calculations, evidence, citations, fields, and validation even when shortening.
- Define when to retry, use a fallback, ask for missing input, abstain, or finish.
- Carry the active goal through follow-up questions and corrections; replace it only when the user cancels or changes the objective. Finish authorized work before asking for a decision that remains blocked.

### Boundaries and autonomy

- Distinguish inspect/report requests from change/build requests.
- Permit safe, reversible, in-scope actions needed for an authorized change.
- Carry forward authorization already established in the session. Complete independent, authorized preparation before seeking permission for the remaining action. Pause when that action still needs permission under the governing instructions or when essential user-only information is missing. Do not infer authority for unrelated effects.
- When a skill causes a pause or diversion, identify the file and relevant rule, and distinguish its requirement from your interpretation. User instructions outrank skill guidelines within the governing instruction hierarchy.
- Keep research, design, implementation, review, and external coordination from silently bleeding into one another.
- Respect ownership and instruction hierarchy. For vendored, generated, protected, or out-of-scope artifacts, return a patch or bridge instead of modifying the source.

### Evidence and progress

- Define which claims need support and what sufficient evidence means.
- Treat missing evidence as unknown, not as proof of absence.
- Separate retrieved fact, user-provided fact, inference, and creative wording.
- Ground progress and completion claims in current tool results. Report failed, skipped, unverified, and completed checks plainly.
- Never invent names, dates, metrics, outcomes, capabilities, citations, or test results to strengthen an artifact.

### Tools and delegation

- Keep only task-relevant tools. State what each tool does, when to use it, important outputs, and meaningful failure behavior.
- Make prerequisites explicit. Parallelize independent reads; sequence dependent work; synthesize before acting.
- Use programmatic or batch tool calling only for bounded deterministic reduction. Keep approval, citations, semantic judgment, and final validation in direct model control.
- Make delegation conditional on runtime support and authorization. Specify useful independent tasks, bounded deliverables, and concurrency limits appropriate to the workflow.

### Reader-facing communication

- Define tone with observable choices instead of labels such as "friendly" or "professional."
- Lead final responses with the outcome. Preserve material facts, decisions, caveats, and next actions; remove repetition and optional background first.
- Prefer clear sentences over fragments, jargon, or dense shorthand.
- Do not ask the model to expose, reproduce, or transcribe private chain-of-thought. Request conclusions, evidence, assumptions, and concise rationale instead.

## Keep vendor guidance conditional

Read the relevant section of [vendor guidance](references/vendor-guidance.md) for model-specific prompting or migration, reasoning or effort settings, long-run runtime behavior, or source-backed rationale. Verify current guidance for the exact target model and runtime before applying provider controls.

Do not copy model-specific settings into a general artifact unless the named runtime uses them. Prefer shared behavioral rules in portable skills and keep provider controls in scoped sections.

## Return the result

Match the requested mode and native artifact format. Include only what helps the user evaluate the change:

1. the revised artifact, applied diff, or review findings;
2. a compact change map: preserved, removed, clarified, and conditionalized;
3. unresolved conflicts or missing context;
4. validation performed and observable results; and
5. status: `validated`, `awaiting-evals`, `no-change-needed`, or `blocked`.

Run required checks and tests relevant to the changed behavior. Repeat or broaden them only for a new change, failure, or unresolved risk. Distinguish structural validation from behavioral evidence.

Do not claim `validated` without real checks. If no eval can run, label the revision `awaiting-evals` and provide the smallest representative test set with explicit pass conditions.

From ThatGuySam/skills, MIT.

More from ThatGuySam/skills