Publish Nats Message

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 NATS MCP server is connected (offering tools such as mcp__nats__publish / mcp__nats__jetstream_publish / mcp__nats__request; the exact tool names come from the connected server)
• 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
• Wait for the user to confirm the contract is fine before entering Stage 4 and sending for real (this avoids polluting the stream with a message sent against an unconfirmed contract)

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

Pick the tool by QoS:

The exact tool names come from the connected NATS MCP server; when a tool signature differs, the Skill maps onto it adaptively (the headers argument / the subject argument).

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

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