From trogonstack-nats
Design NATS subject hierarchies for messaging patterns (pub/sub, request/reply, streaming). Apply naming conventions, segmentation strategies, and wildcard patterns to create scalable subject architectures. Use when designing NATS messaging systems, planning multi-tenant communication, or auditing existing subject hierarchies. Do not use for: (1) NATS server configuration or cluster setup, (2) client library implementation or connection code, (3) debugging connectivity or performance issues, (4) choosing between NATS and other messaging systems.
How this skill is triggered — by the user, by Claude, or both
Slash command
/trogonstack-nats:nats-design-subjectThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Design a subject architecture that subscribers can efficiently navigate using wildcards, with proper segment ordering, tenant isolation, and growth path.
Design a subject architecture that subscribers can efficiently navigate using wildcards, with proper segment ordering, tenant isolation, and growth path.
Skip interview if ALL of these are already specified:
Always interview if: Migrating existing subjects (needs anti-pattern audit first)
Scope — "Is this greenfield design or migrating existing subjects?"
Multi-Tenancy & Scale — "Do you need: (A) Single tenant, (B) Multi-tenant with isolation, (C) Massive scale with regions/shards?"
Messaging Patterns — "Which patterns do you use? (A) Pub/Sub only, (B) Request/Reply, (C) Streaming/JetStream, (D) All/mix?"
Security — "Do you need subject-based authorization or tenant isolation?"
Persistence — "Do you need JetStream persistence or core NATS only?"
List all business domains involved (orders, payments, inventory, etc.). Each domain becomes a top-level subject segment.
Match the user's scenario to a pattern:
| Use Case | Pattern | Example |
|---|---|---|
| Simple Domain | {domain}.{action}.{scope} | orders.created.us-west |
| Multi-Region | {domain}.{action}.{region}.{id} | devices.telemetry.us-east.sensor-456 |
| Multi-Tenant SaaS | {tenant}.{domain}.{action}.{id} | acme-corp.analytics.processed.report-123 |
| Multi-Tenant AI | agents.{action}.{tenant}.{agent-id}.{task-id} | agents.task-assigned.tenant-abc.agent-xyz.task-123 |
| Request/Reply | {service}.request / {service}.reply | orders.request / orders.reply |
| Event Sourcing | {aggregate}.{action}.v{version}.{id} | orders.order.created.v1.order-123 |
For full pattern details with subscriber paths and scaling guidance, read references/patterns.md.
Apply these rules when ordering segments left-to-right:
✓ GOOD: orders.created.us-west.order-123
↑ ↑
low-card high-card
✗ BAD: orders.order-123.us-west.created
↑
high-card early (kills wildcard filtering)
Why this matters: NATS wildcard matching scans left-to-right. High-cardinality values on the left force subscribers into inefficient orders.*.us-west.created patterns that must match thousands of IDs.
For common ordering mistakes and migration strategies, read references/anti-patterns.md.
For each domain, document how subscribers will filter:
orders.> → All order events
orders.created.> → All order creation events
orders.created.us-west.> → Orders created in US West
orders.created.us-west.order-123 → Specific order
Design subjects for subscribers, not publishers. Subscribers determine how you organize — a good hierarchy lets them efficiently filter with wildcards.
If the user needs tenant isolation or role-based access:
acme-corp.>)_admin.> for platform ops)For authorization patterns and tenant isolation examples, read references/security.md.
If the user needs JetStream:
For stream design, consumer patterns, and migration from core NATS, read references/jetstream.md.
Present the design using this template:
# NATS Subject Architecture: [System Name]
## Domain Overview
[Describe the domains and their interactions]
## Subject Hierarchy
### Domain: [Name]
- `domain.action.{scope}.{id}`
- `domain.action.{scope}.{id}`
Subscriber paths:
- `domain.>` — All events
- `domain.action.>` — Specific action
[Repeat for each domain]
## Multi-Tenancy Model
[How tenant isolation works via subjects, if applicable]
## Security Model
[Authorization rules per role/service, if applicable]
## JetStream Streams
[Stream definitions and consumer filters, if applicable]
## Quality Validation
[Run checklist below]
# NATS Subject Architecture: IoT Smart Building Platform
## Domain Overview
Smart building system with 10,000+ sensors across multiple regions sending temperature, humidity, and occupancy data. Needs real-time monitoring, regional aggregation, and alerting.
## Subject Hierarchy
### Domain: Devices
- `devices.telemetry.{region}.{device-id}.{metric}`
- `devices.telemetry.us-west.sensor-456.temperature`
- `devices.telemetry.us-west.sensor-456.humidity`
- `devices.telemetry.eu-central.sensor-789.occupancy`
Subscriber paths:
- `devices.telemetry.>` — All telemetry (global monitoring)
- `devices.telemetry.us-west.>` — Regional dashboard (US West)
- `devices.telemetry.>.>.temperature` — All temperature readings
### Domain: Alerts
- `alerts.triggered.{severity}.{region}.{device-id}`
- `alerts.triggered.critical.us-west.sensor-456`
Subscriber paths:
- `alerts.triggered.critical.>` — Critical alerts only
- `alerts.triggered.>.us-west.>` — Regional alert dashboard
## Multi-Tenancy Model
Not applicable (single organization)
## Security Model
- Building operators: `devices.telemetry.>`, `alerts.>` (subscribe only)
- Alert service: `alerts.>` (publish + subscribe)
- Admin: `>` (full access)
## JetStream Streams
Stream: `telemetry-us-west`
Subjects: `devices.telemetry.us-west.>`
Retention: 24h (high volume)
Stream: `alerts`
Subjects: `alerts.>`
Retention: 30d
## Quality Validation
✓ All segments follow broad-to-specific order
✓ Device IDs at rightmost position
✓ Naming consistent (lowercase, hyphens)
✓ Regional filtering efficient
✓ 4 segments (within 4-6 limit)
For complete real-world examples across microservices, IoT, SaaS, event sourcing, and agentic AI platforms, read references/use-cases.md.
If you're designing a simple single-domain system without multi-tenancy:
{domain}.{action}.{id}orders.created.order-123, payments.authorized.payment-456For multi-region, multi-tenant, or event-sourcing needs, continue with full workflow and read references as needed.
The skill includes 5 detailed reference documents — read them as needed during workflow steps:
Don't read all references upfront — use them progressively as the workflow requires.
orders.created ✓orders_created ✗Orders.Created ✗{domain}.{action}.{scope}.{id})orders.created.123 vs orders.123.created)Validate your subject hierarchy before deployment:
# Start local NATS server
nats-server -D
# Test subscriber wildcards
nats sub "orders.>" # Should match all order subjects
nats sub "orders.created.>" # Should match only creations
nats sub "orders.created.us-west.>" # Should match region-specific
# Test publishing
nats pub "orders.created.us-west.order-123" "test message"
# Verify JetStream streams (if applicable)
nats stream info orders-stream
nats consumer info orders-stream order-consumer
For existing deployments, audit current subjects:
# List active subjects (requires monitoring enabled)
nats server report jetstream
# Check subject permissions
nats server check connection --account <account-name>
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub trogonstack/agentskills --plugin trogonstack-nats