vendor-prompting

Vendor Prompting Best Practices

Audit-grade reference for the prompting patterns published by Anthropic (Claude family) and OpenAI (GPT-5.5 family). 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 / Claude Sonnet → load references/claude-best-practices.md
│   ├── Claude Haiku                → load references/claude-best-practices.md (warn-only)
│   ├── GPT-5.5                     → load references/gpt-5-prompting.md
│   ├── GPT-5.4                     → load references/gpt-5-prompting.md (shared OpenAI cohort)
│   ├── GPT-Codex / GPT-4o          → reviewer-only; minimal automated rules
│   └── Unknown / missing           → ERROR: force explicit model: in frontmatter
│
├── 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 substrings in priority order to assign a family (claude-opus / claude-sonnet / claude-haiku / claude / gpt-5.5 / gpt-5.4 / gpt-codex / gpt-4o / unknown). For agents with model: as an array, the first entry decides the family; bareword qualifiers (Claude Foo (suffix)) are forbidden — see rule frontmatter-model-style-001 in rules.json.

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
• Model family is decided by the FIRST entry in a model array (agents); the table in Model-Family Detection is canonical
• unknown family = ERROR — always require an explicit model: value that the validator can classify
• Bareword YAML for parenthetical model labels is forbidden (model: Claude Foo (suffix) — see rule frontmatter-model-style-001)
• 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[].
2. Classify model family using the table above. Note the family's v1 status from family-support.md.
3. Load the matching checklist from checklists.md: pick the agent or prompt column, then the family-specific section.
4. Run the validator: node tools/scripts/validate-agents.mjs --only=vendor-prompting --format=json and filter by file path. Capture rule IDs + severities.
5. Manual pass: walk the checklist. Each Yes/No carries a rule ID and a verification hint (grep pattern, command, or visual cue).
6. 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. The current source set:

• Anthropic Claude prompting best practices — live web doc at platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices. Refresh via npm run audit:vendor-prompting.
• Anthropic Claude Sonnet 5 prompting guide — live web doc at platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5. Sonnet-5-specific deltas from Sonnet 4.6 (adaptive thinking default, effort/xhigh, new tokenizer, literal instruction following, review harness coverage). Refresh via npm run audit:vendor-prompting.
• OpenAI GPT-5.5 prompting guide — pinned to openai/skills@724cd511c96593f642bddf13187217aa155d2554, prompting-guide.md, sha256 ecdf49b4a824a87367c7a6ec3c0218e2c5783dff951b30a101c3b6a95152aafa.
• OpenAI upgrade guide — same pin, upgrade-guide.md, sha256 563784eb13ad1b44c3a592f940aa7ac2086ebeb97df3f4a09ba038b2f1564d39.

Freshness

Run npm run audit:vendor-prompting to refresh snapshots and emit a drift report. The fetch script (fetch-vendor-prompting-guides.mjs) falls back from gh api (auth) → anonymous raw → cached committed prose if upstream is unavailable.

When upstream changes, regenerate this skill via node tools/scripts/generate-skill-digests.mjs and update the cited sha256 values in rules.json.