Skip to content

Domains

Important

Strict Reservation Notice: The domain-* skill prefix is strictly reserved for the author and maintainers of the instantiated project. The Zenith template intentionally ships with zero domain-* skills out-of-the-box, ensuring that your application domain namespace remains clean and free of naming collisions with upstream template updates.

What Are Domain Skills?

While generic AI coding assistants understand Python syntax, pytest fixtures, and standard library modules, they have zero context about your proprietary business domain.

Without domain guidance, autonomous AI agents tend to:

  • Make invalid assumptions about customer billing calculations or subscription tiers.
  • Invent unauthorized order state transitions.
  • Misunderstand tenant isolation or authentication boundaries.
  • Implement business logic that violates regulatory compliance (such as HIPAA, GDPR, PCI-DSS).

Domain Skills (domain-*) codify business rules, domain invariants, entity lifecycles, and proprietary service logic into structured runbooks that AI agents load when working on domain code.

Anatomy of a Domain Skill

Domain skills follow the standard Zenith progressive disclosure architecture:

📁 .agents/skills/domain-billing/
 ├── SKILL.md          # Core business rules, state transitions, calculation logic
 ├── templates/        # JSON payload schemas, webhook response templates
 └── references/       # Payment gateway API specifications, pricing matrices

Example Frontmatter

---
name: domain-billing
description: >-
  Business logic, subscription tiers, prorating calculations, and webhook processing
  for customer billing. Use when modifying subscription models, invoice generators,
  Stripe webhook handlers, or pricing logic.
  Triggers: billing, subscription, invoice, stripe, pricing, prorate, refund, payment.
version: 1.0.0
---

Use tables and state diagrams to make domain rules easy for agents to apply.

Invariant Tables

Define core domain constraints in clear, non-negotiable tables:

Subscription Tier Seat Limit API Request Cap Storage Quota
Starter Up to 5 10,000 / month 5 GB
Professional Up to 25 100,000 / month 50 GB
Enterprise Unlimited Custom Unlimited

State Machine Lifecycles

Document valid state transitions so agents never introduce illegal states:

stateDiagram-v2
    [*] --> Draft
    Draft --> PendingPayment: Submit Order
    PendingPayment --> Paid: Webhook Confirmed
    PendingPayment --> Canceled: Payment Failed
    Paid --> Fulfilled: Inventory Dispatched
    Fulfilled --> [*]

Edge Case Matrices

Document how the domain handles boundary conditions (for example, leap year billing, fractional cent rounding, concurrent subscription upgrades).

Common Domain Skills

Here are typical domain skills you can scaffold in your Zenith project:

  • domain-auth: Session lifecycles, JWT claims, OAuth2 token refreshing, and RBAC permission hierarchies.
  • domain-billing: Subscription models, tax calculation rules, discount codes, and payment retry schedules.
  • domain-order-fulfillment: Cart checkout workflows, shipping provider dispatching, and refund approval thresholds.
  • domain-data-ingestion: Sensor telemetry normalization, schema migration invariants, and dead-letter queue routing.
  • domain-compliance: PII masking protocols, audit log retention requirements, and data export contracts.

Authoring Domain Skills

Use the Skill Creator (workflow-skill-creator) workflow:

  1. Create the skill directory:
mkdir -p .agents/skills/domain-<name>/{templates,references}
  1. Author SKILL.md with active voice, concise rules, and explicit triggers following ASD-STE100.
  2. Register the skill in your project's AGENTS.md.
  3. Validate compliance:
uv run poe check-skills