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)