jonathan-vella/apex/apex-vendor-prompting

Vendor Prompting Best Practices

Manual-only: use /apex-vendor-prompting explicitly for this audit workflow. Do not load this skill automatically or read its body to bypass the invocation flag. The thin authoring instructions and required vendor validators remain mandatory without this skill.

Audit-grade reference for the prompting patterns published by Anthropic (Claude Opus 5.5, Sonnet 5.5) and OpenAI (GPT-6, GPT-5.6), plus explicitly identified APEX conventions. Used to author and audit .agent.md and .prompt.md files in this repository.

The machine-readable source of truth is rules.json — every rule has an ID, source citation, severity, applies-to, and validator-check binding. The skill prose, the thin enforcement instruction vendor-prompting.instructions.md, and validate-agents.mjs all reference rule IDs from that file.

When to Use This Skill

• Authoring a new .agent.md or .prompt.md and wanting the right

vendor patterns up front.

• Auditing an existing agent against vendor best practices (the

audit procedure is in audit-procedure.md).

• Investigating a finding from npm run lint:vendor-prompting —

every finding includes a ruleId that maps to a rule in rules.json and back to a reference here.

• Choosing the right model family for a new agent (decision rules in

family-support.md).

Do NOT load this skill for routine edits where the format is already known. The thin instruction vendor-prompting.instructions.md auto-loads on *.agent.md / *.prompt.md edits and carries the hard-rule shortlist.

Decision Tree

I am editing or reviewing a *.agent.md / *.prompt.md ...
├── Which model is in the frontmatter?
│   ├── Claude Opus / Sonnet 5.5   → load references/claude-best-practices.md
│   ├── GPT-6 Sol / Luna (copilot) → load references/openai-prompting.md
│   ├── GPT-5.6 Terra (copilot)    → load references/openai-prompting.md
│   ├── MAI-Code-1.1-Flash         → reviewer-only; structural checks still run
│   └── Missing on prompt          → resolve custom-agent or picker inheritance
│
├── Is this a .prompt.md (single string model:) or .agent.md (array)?
│   ├── prompt → load references/checklists.md "prompt" column
│   └── agent  → load references/checklists.md "agent" column
│
└── Want the full audit procedure (5-15 min, produces written report)?
    → load references/audit-procedure.md and assets/audit-template.md

Model-Family Detection

classifyModel() lower-cases the model: value and matches it to a family (claude-opus-5.5 / claude-sonnet-5.5 / gpt-6-sol / gpt-6-luna / gpt-5.6-terra / mai-code / unknown). Retired labels classify as unknown. Validate every ordered fallback label and distinct family. Classification does not authorize a label: ordinary labels must exactly match the catalog. Only handoff overrides allow documented platform qualification.

Full match table, severity status per family (enforced / warn-only / reviewer-only / out-of-scope), and rule subsets per family live in `references/family-support.md`.

Reference Index

Load only the references your task needs. Most audits need 1-2.

Rules

• Source of truth is `rules.json` — every rule has an ID, severity, source citation,

applies-to, and validator-check binding; this skill prose only references it.

• Check every fallback without adding one; see Model-Family Detection.
• Missing prompt models may be inherited; unknown explicit labels and unknown custom-agent targets fail validation.
• Array agent models and string prompt models are APEX conventions, not YAML limitations.

Parentheses are valid YAML scalar content.

• Markdown outcome contracts for GPT are an APEX convention that mirrors the GPT-5.6

suggested prompt structure and extends it to GPT-6. Preserve exact catalog labels; unknown release/tier metadata stays unknown.

• Claude main agents use the APEX Claude contract: one H1, a nonempty ## Role, and

nonempty <scope_fencing>, <output_contract> and <stop_conditions> XML blocks.

• Vendor autonomy advice does not remove APEX gates — approval gates, the security

baseline and governance constraints stay required stops; consolidate their wording instead.

• Leaf workers use role contracts, not mandatory personality or main-agent sections.

Convert XML wrappers without deleting their safety or workflow content.

• Do NOT load this skill for routine edits — the auto-loaded thin instruction

vendor-prompting.instructions.md carries the hard-rule shortlist.

• Run `npm run lint:vendor-prompting` before opening a PR; every finding includes

a ruleId that maps to a rules.json entry.

• Verdict thresholds — APPROVED if zero errors and ≤ 5 warns; otherwise NEEDS_REVISION with per-rule remediation
• Out of scope: routine prompt edits where rules are already known, generic markdown style (see markdown.instructions.md)

Steps

This is the canonical audit procedure (full version with templates lives in audit-procedure.md).

1. Read frontmatter of the target .agent.md / .prompt.md.

Capture name, model, user-invocable, agents, handoffs[].

1. Classify model family using the table above. Note the family's

status for every fallback from family-support.md.

1. Load the matching checklist from

checklists.md: pick the agent or prompt column, then the family-specific section.

1. Run the validator:

node tools/scripts/validate-agents.mjs --only=vendor-prompting --format=json and filter by file path. Capture rule IDs + severities.

1. Manual pass: walk the checklist. Each Yes/No carries a rule ID

and a verification hint (grep pattern, command, or visual cue).

1. Produce a report using

assets/audit-template.md. Combine automated findings (step 4) + manual findings (step 5). Verdict = APPROVED if zero errors and ≤ 5 warns; otherwise NEEDS_REVISION with per-rule remediation.

Source Citations

Every rule in rules.json cites the upstream source by source_id. All sources are live vendor docs fetched as Markdown (.md suffix):

• Anthropic Claude prompting best practices —

claude-prompting-best-practices.

• Anthropic Prompting Claude Opus 5.5 —

prompting-claude-opus-5-5: effort calibration, thinking-disabled migration, unattended runs, pasted text, progress updates.

• Anthropic Prompting Claude Opus 5 —

prompting-claude-opus-5: baseline the Opus 5.5 guide defers to — over-verification, task scope, subagent spawning, deliverable length.

• OpenAI Using GPT-6 —

latest-model/gpt-6-astra: family prompting best practices (written for Astra, starting point for Sol and Luna).

• OpenAI Using GPT-5.6 —

latest-model/gpt-5.6: Terra/Sol/Luna tiers, migration quickstart.

• OpenAI Prompting guidance for GPT-5.6 —

prompt-guidance-gpt-5p6: suggested prompt structure, autonomy boundaries, lean prompts.

OpenAI sources use model-pinned paths; latest-model without a model segment moves to the next generation silently. Hashes and fetch timestamps live in rules.json sources[].

Freshness

With explicit network authorization, run node tools/scripts/fetch-vendor-prompting-guides.mjs to refresh snapshots and emit a drift report. The fetch script (fetch-vendor-prompting-guides.mjs) fetches each vendor Markdown page anonymously. Snapshots are a gitignored local cache: when upstream is unavailable it falls back to a snapshot from an earlier successful run on the same machine. A clean checkout has no cache, so an offline refresh fails (exit 2) rather than falling back; rules.json hashes are the committed record.

Cached fallback preserves the last successful fetched_at and freshness date; attempted_at and the failure reason record the separate refresh attempt. Missing successful provenance remains unknown. An unchanged successful network response may advance freshness; cached reuse cannot establish upstream currency.

Review actual source diffs before updating normalized references and rule citations. There is no digest-generation step. Offline audits reuse cached sources without changing hashes, fetched timestamps, or claiming refreshed evidence. Source history does not establish model release, capabilities, cost tiers, or native harness behavior.