Beyond Copy-Paste: Giving AI Instructions a Shared Standard

Someone on your backend team writes a genuinely good code-review prompt. It knows which framework you use, which failure modes matter, and how strict to be about style versus correctness. It gets pasted into a Slack thread. Two other teams copy it. Someone tightens the security section. Someone else trims it because it was too long for their context window. Six weeks later there are four versions in circulation, one of them subtly wrong, and nobody can say which one the compliance review actually looked at.

Nothing here is exotic. It is the same thing that happens to any useful text that has no owner, no version, and no distribution mechanism. What makes it uncomfortable is that this text is now load-bearing: it shapes what gets flagged in a pull request, what an assistant refuses to answer, and which risks a workflow checks for. We have decades of practice managing that kind of dependency for code. We have almost none for instructions.

What an AI artifact actually is

An AI artifact is a reusable unit of operating knowledge that shapes AI-assisted work. In practice that means prompt templates, system instructions, workflow definitions, review guidelines, test patterns, knowledge articles, code templates, policy packs, and evaluation suites.

The important shift is not the vocabulary. It is treating these things as assets with an owner, a version, a compatibility statement, and a lifecycle — rather than as text that lives wherever it was last pasted.

OAI2 — the Open AI Artifact Interchange Initiative — is an open standard and registry for packaging, validating, sharing, and consuming those artifacts. (The name refers to AI artifact interchange; the project has no affiliation with OpenAI.)

The package and the registry

An OAI2 package is a directory with content plus an oai2.yaml manifest:

artifact/
├── oai2.yaml              # Manifest (required)
├── content/main.md        # Primary content (required)
├── variables.schema.json  # Variable definitions, JSON Schema 2020-12 (optional)
└── tests/cases.yaml       # Test cases (optional)

The manifest is where the file stops being a document and starts being a dependency. From the project’s TypeScript code-review sample:

oai2Version: "0.1"
kind: "PROMPT_TEMPLATE"

artifact:
  id: "org.acme.code-review.typescript"
  version: "1.2.0"
  title: "TypeScript Code Review Prompt"

ownership:
  maintainers: ["[email protected]"]
  team: "platform-engineering"

visibility:
  mode: "public"

compatibility:
  providers: ["openai", "anthropic", "azure-openai"]
  agentTargets: ["cli", "ide", "web"]
  minTokenContext: 8000

validation:
  profiles: ["oai2-core", "secure-prompting-v1"]

Identity, ownership, visibility, compatibility, validation profiles — declared once, machine-readable, and travelling with the content. Variables move out of the prose and into a schema, so strictness becomes an enum with a default rather than a sentence someone has to remember to edit.

The registry is the other half. It handles publishing, validation, search with visibility enforcement, controlled sharing, retrieval, and subscriptions. Artifacts sit in one of three visibility modes: public, private, or private-shareable — the last being the interesting one, where an artifact is invisible by default but grantable to named partner organizations.

flowchart LR
    A["Author package"] --> B["Validate against profiles"]
    B --> C["Publication gate"]
    C --> D["Registry: versioned, searchable"]
    D --> E["Share grant to named org"]
    D --> F["Subscription: notify on new release"]

The key point of the flow: validation is a gate, not a formality. A package that only parses can be stored, but publication requires it to pass the deterministic rule set.

An illustrative walkthrough

The following scenario is illustrative — it uses the project’s own sample artifacts and demo seed data, not a real customer.

Acme’s platform team owns that TypeScript review prompt. They package it, run oai2 validate locally, and publish. The registry checks the manifest, verifies the declared entrypoint actually exists in the archive, scans for secret patterns, computes a SHA-256 over the package, and — if the checks pass — publishes it as an immutable 1.2.0.

Globex wants it. Because the artifact is public, they find it via search, oai2 inspect it to see maintainers and compliance level, and oai2 pull a specific version. They then subscribe with a compliance filter, so when Acme ships 1.3.0 a signed webhook arrives rather than a rumour.

Now change one detail: Acme’s safety constraints artifact is private-shareable. Globex cannot find it at all until Acme creates an org-to-org grant, optionally scoped to a semver range and an expiry date. Same registry, same package format, different disclosure decision — expressed as configuration rather than as a forwarded email.

Who this is for, and what it solves

• Engineering leads get an answer to “which version of the review standard is this team actually using?” that does not depend on someone’s memory.
• AI platform teams get one distribution path instead of per-team copies, and a subscription mechanism so downstream teams learn about changes.
• Artifact maintainers get named ownership, immutable versions, and deprecation with a declared successor — so improving an artifact is not a broadcast-and-hope exercise.
• Governance functions get visibility modes, validation profiles, risk-tier declarations, and an audit log of state-changing operations.

What this adds over Git or a shared doc

Git already gives you history, review, and diffs, and for a single team that is often enough. What it does not give you is a manifest contract: a machine-readable declaration of identity, compatibility, and ownership that other systems can act on. Nor does it give you cross-organization discovery with visibility enforcement, validation as a publication gate, selective sharing with expiry, or update subscriptions to a repository you have no access to.

Two honest limits. Interoperability is a design objective, not a promise: the compatibility block declares intended providers and targets — it does not mean an artifact behaves identically across tools or models. And validation checks specified rules only: passing oai2-core means the package is well-formed and free of the patterns the rules describe. It is not a claim of correctness, safety, or reproducible model behaviour. The project’s own design principles put it plainly — AI-assisted validation is an assistive layer, not a guarantee.

Where the project actually stands

Implemented today: organization registration and API keys; artifact catalog with lifecycle states; versioned package upload with hashing; fifteen oai2-core manifest checks with a publication gate; full-text search with visibility scoping and facets; org-to-org share grants with version ranges and expiry; subscriptions with HMAC-signed webhook delivery; an audit log; a web UI; and a CLI covering login, validate, publish, search, inspect, pull, and subscribe.

Specified but not yet built: standards profile management, publisher domain verification, artifact signing and provenance attestations, deeper dependency resolution, and the extended CLI surface (share, fork, drift detection, upstream pull). That matters for the compliance ladder — Declared and Validated are reachable now; Verified and Trusted depend on the profile and trust work still ahead. The licensing model is also still open.

When you do not need this

If one team owns three prompts and everyone who uses them sits in the same standup, a versioned file in the repo is the right answer. The cost of packaging is only worth paying when artifacts cross a boundary — between teams, between an authoring group and its consumers, or between organizations — and when someone downstream needs to know that what they have is current, owned, and checked.

If that boundary exists in your organization, the four sample artifacts in the project repository are the fastest way to judge whether the model fits: a prompt template, a system instruction, a policy pack, and a workflow definition, each complete with manifest, variable schema, and test cases. Read one manifest end to end. Either it describes a problem you recognise, or it does not.