Cross-Harness Skills

Build one portable skill core for Claude Code and Codex without flattening their different model and runtime behavior into vague advice. The common SKILL.md defines the task contract. Harness-only invocation, metadata, hooks, permissions, and path features stay in adapters or installation documentation.

Quick Start

1. Classify the request. A review-only request returns findings and does not edit files; a create, improve, or modernize request authorizes in-scope edits.
2. Identify the intended model in each harness from the request or active configuration; do not substitute a model merely because this guide names it. Record unavailable combinations rather than treating one successful run as proof for both.
3. Read references/model-prompting-contract.md for the shared prompt contract and the model-specific behaviors that must not leak into domain skills.
4. Read references/harness-portability.md before using a path, invocation syntax, tool name, frontmatter key, hook, subagent feature, or environment variable.
5. Write the portable core first. Add only domain knowledge, fragile procedure, authority boundaries, evidence requirements, output preservation, and real stop or fallback rules.
6. Move a capability into an adapter when the other harness cannot interpret it with the same meaning. The core must still complete correctly without that adapter.
7. Apply references/review-gate.md to the package and its directly linked resources. In change mode, patch measured defects; do not rewrite a passing skill to mention model names.
8. Validate packaging and changed executable resources. Run model comparisons only when requested; reuse existing traces when available and distinguish static findings from behavior exercised in either harness.

Portable Prompt Contract

Keep the normal path compact and include only fields that change behavior: