feat: add nats skill

Author: yordis

.claude-plugin/marketplace.json

@@ -25,6 +25,14 @@
       "skills": [
         "./skills/gh-enrich-pr-description"
       ]
+    },
+    {
+      "name": "nats",
+      "description": "NATS messaging skills for designing subject hierarchies, applying naming conventions, segmentation strategies, and wildcard patterns to create scalable pub/sub, request/reply, and streaming architectures",
+      "source": "./",
+      "skills": [
+        "./skills/nats-design-subject"
+      ]
     }
   ]
 }

README.md

@@ -18,6 +18,8 @@ claude plugin install diataxis@trogonstack
 | Plugin | Description |
 |--------|-------------|
 | `diataxis` | Documentation skills following the Diataxis framework — generate READMEs and reorganize docs into tutorials, how-to guides, reference, and explanation sections |
+| `gh` | GitHub workflow skills for enriching PR descriptions, automating code review context, and streamlining collaboration through the gh CLI |
+| `nats` | NATS messaging skills for designing subject hierarchies, naming conventions, and wildcard patterns for scalable pub/sub, request/reply, and streaming architectures |
 
 ## Contributing
 

skills/nats-design-subject/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: designing-nats-subjects
+description: 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 or planning multi-tenant communication.
+allowed-tools: AskUserQuestion, Write
+---
+
+## Interview Phase (Optional)
+
+**When to Interview**: Skip if the user has specified: messaging patterns (pub/sub vs request/reply), multi-tenancy needs, and scale expectations. Interview when unclear which subjects matter most or what patterns are needed.
+
+### Critical Questions
+
+1. **Multi-Tenancy & Scale** (Impact: Determines subject segmentation strategy)
+   - Question: "Do you need: (A) Single tenant, (B) Multi-tenant with isolation, (C) Massive scale with regions/shards?"
+   - Why it matters: Multi-tenant systems need tenant isolation in subjects; large scale needs region/shard segmentation
+
+2. **Messaging Patterns** (Impact: Determines subject organization for different use cases)
+   - Question: "Which patterns do you use? (A) Pub/Sub only, (B) Request/Reply, (C) Streaming/JetStream, (D) All/mix?"
+   - Why it matters: Different patterns have different subject hierarchy needs
+
+---
+
+## Purpose
+
+Design effective NATS subject hierarchies that scale across messaging patterns (pub/sub, request/reply, JetStream streaming). Create subject architecture that's easy to navigate for subscribers while supporting multi-tenancy, security, and growth.
+
+## When to Use
+
+Apply this skill when:
+- Designing a new NATS messaging system
+- Planning multi-tenant subject isolation
+- Organizing device telemetry or event streams
+- Setting up request/reply patterns across microservices
+- Defining event subject structure for event-sourced systems
+- Building agentic AI platforms with inter-agent messaging
+
+## Core Principles
+
+### 1. The Subscriber-First Philosophy
+
+**Design subjects for subscribers, not publishers.**
+
+Publishers can publish to any subject, but subscribers determine how you organize. A good subject hierarchy groups related messages so subscribers can efficiently filter with wildcards.
+
+Bad: `publish.order.123.created` (published topic order)
+Good: `orders.created.region.us-west` (grouped for subscribers)
+
+### 2. Segment Ordering Strategy
+
+Order segments left-to-right from broad to specific. This enables natural wildcard filtering:
+
+```
+Pattern: {domain}.{action}.{scope}.{identifier}
+
+orders.created.us-west.order-123
+  ↑       ↑      ↑       ↑
+domain  action scope   identifier
+(broad)                (specific)
+```
+
+**Subscriber paths**:
+- `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
+
+### 3. Cardinality Consideration
+
+**Place high-cardinality segments on the right.** High-cardinality means many unique values (IDs, timestamps). Low-cardinality means few values (regions, actions).
+
+```
+✓ GOOD: orders.created.us-west.order-123
+                            ↑          ↑
+                       low-card    high-card
+  Subscribers: orders.created.us-west.> (1000s of specific orders)
+
+✗ BAD: orders.order-123.us-west.created
+                ↑
+           high-card early (kills hierarchy)
+  Subscribers: orders.*.us-west.created (wildcard must match thousands of IDs)
+```
+
+### 4. Consistency and Casing
+
+Use lowercase with hyphens (never underscores or mixed case):
+- `orders.created` ✓
+- `orders_created` ✗
+- `Orders.Created` ✗
+
+## Quick Decision Matrix
+
+Choose patterns based on your use case:
+
+| 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` |
+
+## Subject Design Framework
+
+### Step 1: Identify Domain Boundaries
+
+What business domains are involved? (orders, payments, inventory, etc.)
+
+### Step 2: Choose Segment Layers
+
+Determine your hierarchy depth (3-6 segments typical):
+- Layer 1: Domain (always)
+- Layer 2: Action/event type
+- Layer 3: Scope (region, tenant, context)
+- Layer 4+: Identifiers (add only as needed)
+
+### Step 3: Order Segments Strategically
+
+- Broad categories first (most subscribers filter here)
+- Specific identifiers last (high-cardinality)
+- Never put IDs or UUIDs before actions
+
+### Step 4: Plan Subscriber Paths
+
+List how subscribers will filter:
+
+```
+Subscriber: orders.created.>
+  Gets: All order creation events (any region/ID)
+
+Subscriber: orders.created.us-west.>
+  Gets: All order creation events in US West region
+
+Subscriber: orders.>
+  Gets: All order events (any action, region, ID)
+```
+
+### Step 5: Validate Against Quality Checklist
+
+Run the checklist (see below) before implementation.
+
+## Key Insights
+
+**Why Segment Order Matters**: NATS wildcard matching scans left-to-right. If high-cardinality values are on the left, subscribers must use more specific filters, losing the benefit of hierarchical organization.
+
+**Wildcard Gotcha**: `orders.*.*.order-123` works but defeats the purpose (subscribers can't say "all orders from a region"). Put identifiers last.
+
+**Hierarchy Depth**: Keep to 4-6 segments. Beyond that, use properties in JetStream consumer filters instead of subject complexity.
+
+**Multi-Tenancy Pattern**: For SaaS, tenant ID as first segment enables subject-based authorization:
+- Tenant A users can only see: `tenant-a.>`
+- Tenant B users can only see: `tenant-b.>`
+- Admin can see: `>`
+
+## Output Format
+
+Present your subject design as:
+
+```markdown
+# NATS Subject Architecture: [System Name]
+
+## Domain Overview
+[Describe the domains and their interactions]
+
+## Subject Hierarchy
+
+### Domain: Orders
+- `orders.created.{region}.{order-id}`
+- `orders.updated.{region}.{order-id}`
+- `orders.cancelled.{region}.{order-id}`
+
+Subscriber paths:
+- `orders.>` - All order events
+- `orders.created.us-west.>` - Orders created in US West
+
+### Domain: Payments
+[Similar structure]
+
+## Multi-Tenancy Model
+[How tenant isolation works via subjects]
+
+## Quality Validation
+- [x] All segments ordered (broad to specific)
+- [x] No high-cardinality before action
+- [x] Consistent naming (lowercase, hyphens)
+- [x] Subscriber paths documented
+```
+
+## Quality Checklist
+
+Validate your design before implementation:
+
+- [ ] All segments follow `{domain}.{action}.{scope}.{id}` order (broad to specific)
+- [ ] No UUID/ID fields appear before action/scope segments
+- [ ] Naming consistent (all lowercase, hyphens, no underscores)
+- [ ] Documented subscriber wildcard paths for each domain
+- [ ] No subjects deeper than 6 segments (consider JetStream consumer filters)
+- [ ] Multi-tenancy isolation is clear (tenant ID positioning documented)
+- [ ] Security subjects defined for admin/monitoring access
+- [ ] No conflicting patterns (e.g., `orders.created.123` vs `orders.123.created`)
+- [ ] High-cardinality decision documented (why ID placement chosen)
+
+## Reference Documentation
+
+For comprehensive guidance on specific topics:
+
+- **[Patterns](references/patterns.md)**: 6 hierarchy patterns with real-world examples for each use case
+- **[Anti-Patterns](references/anti-patterns.md)**: 8 common mistakes with fixes and migration strategies
+- **[Security & Multi-Tenancy](references/security.md)**: Authorization patterns and tenant isolation
+- **[JetStream Design](references/jetstream.md)**: Stream filters, consumer subjects, and event patterns
+- **[Use Cases](references/use-cases.md)**: Domain-specific examples (microservices, IoT, SaaS, events, AI platforms)
+
+## Version History
+
+- **v1.0** (2026-01-24): Initial release with core principles, decision matrix, quality checklist