Skill: Publish NATS Message

Purpose

Let collaborating projects "produce messages correctly" — publish one message through the NATS MCP tools according to the cross-team contract, with subject / headers / payload / QoS aligned strictly to specs/nats-messaging.md. The first time an event has no contract, walk through generating one and write it into the producer repo.

Core Objective

Primary goal: publish one contract-conforming message through the NATS MCP tools; when the contract does not exist, generate it before sending.

Success criteria:

1. ✅ The project cache .cortex/nats.yaml was read (walk through creating it when it is absent)
2. ✅ The <event>-contract.md for the event is in place (read it when it exists; draft it and prompt for a commit when it does not)
3. ✅ The subject / headers / payload actually sent match the contract definition strictly
4. ✅ Nats-Msg-Id is a UUID v7 generated for this send (or the original ID reused when retrying the same message)
5. ✅ A JetStream send received its ack; at-most-once is fire-and-forget only
6. ✅ The user got the send result (success + a summary of the actual headers / failure + the reason)

Acceptance test: on the consumer side, consume-nats-message subscribes to the same subject and decodes headers + payload correctly, with no validation failure.

Scope Boundary

This skill owns:

• Reading the project cache and loading the contract
• Drafting the contract per specs/nats-messaging.md + specs/cross-team-contract.md when it is missing on first use
• Building the conforming message (subject + headers + payload)
• Carrying out publish / jetstream_publish / request through the NATS MCP tools
• Ack verification and retry on failure (per the contract's retry policy)

This skill does not own:

• Writing the actual publisher code → outside the Skill's remit (an application-engineering responsibility)
• Creating / modifying a JetStream stream / consumer / KV → an IaC responsibility (see spec §5.5.2)
• Subscribing to / consuming messages → use consume-nats-message

Preconditions

• A target NATS connection is identified. Discover its actual tools and signatures in Stage 5; stop there if no suitable publish capability is connected. The example names below are capability hints, not a required interface.
• The current working directory is the producer repo (for reading .cortex/nats.yaml and the contract file)
• The user can authorize publish permission on the broker

Execution

Stage 0: announce

"I am using the publish-nats-message skill to send a NATS message."

Stage 1: read the project cache

1. Read .cortex/nats.yaml (at the producer repo root)
2. Extract the fields: broker_url / service_source / default_stream / contract_dir / iac_owner
3. Cache absent: enter the "cache initialization subflow" — ask for the fields above, write .cortex/nats.yaml, and prompt the user to review and commit it; later steps reuse the values filled in here
4. Cache present but a field is missing: ask about the missing field only, and update the cache

Stage 2: locate the contract

1. Parse the event description the user gave ("send clarification.session.requested", for example)
2. Glob <contract_dir>/**/<event>-contract.md
3. Hit: read the contract → go to Stage 4
4. Miss: go to Stage 3 and draft the contract

Stage 3: contract drafting subflow (first time for a given event only)

Ask for the minimum information needed (the rest comes from the cache):

• The consumer name (one or several)
• The QoS choice (at-least-once by default; the user can pick at-most-once but must state where loss is acceptable)
• Whether this is a multi-turn session (if so → mark X-Correlation-Id conditionally required, and plan a slot for sessionId inside the subject)
• The business field table (a draft payload schema; the user can list the main fields, their types and whether each is required)
• DLQ + retry parameters (defaults: DLQ <subject>.dlq, max_deliver=5, exponential backoff base 1s max 30s)

Generate the contract file:

• Path: <contract_dir>/<consumer>/<event>-contract.md (the flat layout of cross-team-contract.md §3)
• The frontmatter carries contract_version: 1.0.0, and the first CHANGELOG entry is ### 1.0.0 — YYYY-MM-DD Initial Release
• The body follows the template in specs/nats-messaging.md §7.1

Afterwards:

• Prompt the user to review and commit the contract file
• Present a newly drafted contract for review and wait for the contract owner's acceptance before sending against it. A request for this specific publish already authorizes the send once the contract is accepted; do not ask for publish permission a second time. Ask only for missing material choices. A request for a preview stops before sending.

Stage 4: build the message

Fill the fields per the contract:

Validation fails → report the offending fields and send nothing.

Stage 5: send through the MCP NATS tools

1. List the connected NATS MCP tools. Map the contract's QoS to a capability that accepts a subject, payload and headers; for JetStream, require an acknowledgement-bearing publish operation. Inspect the actual argument names and response shape before calling it.
2. If the required capability is absent, stop without sending, name the missing operation and preserve the validated message for a later retry. Do not substitute a Core NATS publish for JetStream.
3. Call the mapped tool once with the validated subject, headers and payload. On an uncertain result, retry only under the contract's policy with the same message ID.

Example tool names by QoS:

The connected server's actual names and signatures control execution. A request-response tool is applicable only when the contract and user request call for a reply.

Stage 6: self-check and receipt

• JetStream: wait for the ack; a timeout / no ack → treat it as a failure
• Retry on failure: resend per the contract's retry policy, reusing the same Nats-Msg-Id (the broker deduplicates); still failing at max_deliver → report to the user
• Success receipt: emit
  • subject
  • the actual header values (sensitive fields can be redacted where present)
  • the ack information (JetStream sequence / stream / domain)
  • the elapsed time

Error Handling

Anti-Patterns

• ❌ Application code creating a Stream / Consumer / KV at runtime (a violation of spec §5.5.2) — report the error and point at IaC
• ❌ Cross-team messages going over Core NATS with no persistence — switch to JetStream by default; a downgrade takes an explicit user confirmation
• ❌ A fresh Nats-Msg-Id on retry — it must be reused, or the broker's deduplication stops working
• ❌ Stuffing metadata into the payload JSON envelope (id / source / time and the like) — it must go in the Headers
• ❌ Asking again for basics such as broker_url / service_source without reading the cache
• ❌ Sending with no contract in place — it must be drafted first, with a prompt to commit

Self-Check

• The cache and the correct event contract were read or created, a newly drafted contract was accepted, and all required fields were validated.
• The selected tool supports the contract's QoS, subject, headers and payload; no fallback weakened delivery.
• The publish was explicitly requested, and a preview request did not send.
• Retries reused the original Nats-Msg-Id, and JetStream success includes an actual acknowledgement.
• The receipt reports the outcome and redacts sensitive header values.

Examples

Existing contract, JetStream

Input: a user requests one orders.created event with a payload matching an existing at-least-once contract. Action: read the cache and contract, discover an acknowledgement-bearing JetStream publish tool, validate the message and send it. Output: report the actual ack, subject and redacted headers.

Missing publish capability

Input: the contract requires JetStream, but the connected server exposes only Core NATS publish. Action: preserve the validated message and stop before sending. Output: report that an acknowledgement-bearing JetStream publish capability is required; do not downgrade QoS.

Relation to Other Assets

• The structural contract yardstick: specs/nats-messaging.md — the authority on subject / headers / payload / QoS / validation rules
• The contract document skeleton: specs/cross-team-contract.md — apply its frontmatter and section structure when drafting a contract for the first time
• The consumer-side counterpart: consume-nats-message — the other end of the same contract
• The authority on broker behavior: https://docs.nats.io — the official docs govern the NATS protocol / JetStream / Services API