✅ CORRECT Skill | Agent Skills

When to Use

Analyzing *.aurora.yaml files for quality and consistency
Editing YAML schemas (creating, updating, or deleting fields)
Validating field naming conventions and descriptions
Ensuring module descriptions explain purpose and context

Reference files (loaded on demand):

type-reference.md — Type selection guide, varchar lengths, relationship rules
examples.md — Common patterns, analysis workflow, change log template

Always combine with: aurora-cli, aurora-project-structure, conventional-commits

Critical Patterns

Module Description (REQUIRED)

Every *.aurora.yaml must have a description property before aggregateProperties:.

# ✅ CORRECT
version: 0.0.1
boundedContextName: iam
moduleName: permission
description: >
    Module containing the permissions associated with each bounded context, to
    be used to manage access to each API.
aggregateProperties:
    - name: id

Description should explain: (1) What the module contains, (2) What it's used for, (3) How it relates to other modules.

Mandatory Fields (REQUIRED in all modules)

Order: id → rowId → ... campos ... → createdAt → updatedAt → deletedAt

- name: rowId
  type: bigint
  index: unique
  autoIncrement: true
  nullable: false
  description: >
      Auto-incrementing sequential identifier for internal ordering and legacy compatibility.

- name: createdAt
  type: timestamp
  nullable: true
  description: Timestamp when the record was created. Part of audit trail.

- name: updatedAt
  type: timestamp
  nullable: true
  description: Timestamp when the record was last modified. Part of audit trail.

- name: deletedAt
  type: timestamp
  nullable: true
  description: Soft delete timestamp. NULL = active record.

Field Naming Conventions

| Pattern | Use For | Examples | | --------------------- | ------------------- | --------------------------------------- | | camelCase | All field names | firstName, orderDate, totalAmount | | is*, has*, can* | Boolean flags | isActive, hasChildren, canEdit | | *At | Timestamps | createdAt, updatedAt, publishedAt | | *Date | Date-only fields | birthDate, startDate, endDate | | *Id | Foreign keys | authorId, categoryId, parentId | | sort | Display/UI ordering | sort (NOT displayOrder or order) |

Anti-patterns: stat → status, dt → createdAt, qty → quantity, active → isActive

Field Descriptions (MANDATORY)

Every field MUST have a description that explains WHY, not WHAT:

# ❌ BAD
- name: price
  type: decimal
  description: The price of the book

# ✅ GOOD
- name: price
  type: decimal
  decimals: [10, 2]
  description: >
      Retail price in the store's base currency. Does not include taxes or
      discounts. Used as base for price calculations.

ID Fields (CRITICAL RULE)

Fields of type id MUST NOT have a length property.

# ✅ CORRECT
- name: id
  type: id
  primaryKey: true

# ❌ INCORRECT
- name: id
  type: id
  length: 36  # ← DELETE THIS
  primaryKey: true

Relationship Fields (CRITICAL RULE)

| Side | Has FK? | Use | | ------------------------- | ------- | ---------------------------------------- | | Child/Many (invoice-line) | YES | type: id + relationship block inside | | Parent/One (invoice) | NO | type: relationship (navigation only) | | Many-to-many | NO | type: relationship + pivot config |

⚠️ NEVER define both invoiceId (type: id) AND invoice (type: relationship) in the SAME module.

# ✅ child.aurora.yaml - ONLY the FK field
- name: parentId
  type: id
  relationship:
      type: many-to-one
      field: parent
      aggregateName: MyParent
      modulePath: my-context/parent

# ✅ parent.aurora.yaml - ONLY the navigation property
- name: children
  type: relationship
  relationship:
      type: one-to-many
      aggregateName: MyChild
      modulePath: my-context/child
      key: parentId

Cross-Module Consistency

Use the same field names across ALL modules:

- name: id        # Not: ID, _id, uuid, identifier
- name: createdAt # Not: created, createdDate, createTime
- name: updatedAt # Not: updated, modifiedAt, updateTime
- name: deletedAt # Not: deleted, removedAt, deletionDate
- name: isActive  # Not: active, enabled, status

Index Names (63-char limit)

PostgreSQL limits index names to 63 characters. Use indexName with abbreviated name:

- name: administrativeAreaLevel1Id
  type: id
  index: index
  indexName: bpp_partner_addr_admin_area_lvl1_id

Analysis Checklist

[ ] Module has description before aggregateProperties
[ ] Has rowId, createdAt, updatedAt, deletedAt
[ ] All fields have meaningful descriptions (WHY, not WHAT)
[ ] Field names follow conventions (camelCase, boolean prefixes)
[ ] No id type fields have length property
[ ] Enum values are documented
[ ] Types are appropriate for use case → see type-reference.md
[ ] No duplicate relationship definitions
[ ] Consistency with similar modules

Commands

fd -e yaml aurora                                     # Find all Aurora YAMLs
rg -L "^description:" cliter/ -g "*.aurora.yaml"      # Missing module descriptions
rg -L "name: rowId" cliter/ -g "*.aurora.yaml"        # Missing rowId
rg -A2 "type: id" cliter/ -g "*.aurora.yaml" | rg "length:"  # id fields with length (bad)

Anti-Patterns

| ❌ Don't | ✅ Do | | ----------------------------------------- | ------------------------------------------------- | | Skip module description | Always add description before aggregateProperties | | Skip mandatory fields | Always include rowId + timestamps | | Use abbreviations (dt, qty) | Full words (createdAt, quantity) | | Name booleans without prefix | Use is*/has*/can* prefix | | Add length to id type fields | Never specify length for id type | | Write "The price" as description | Explain context and usage | | Use float for money | Use decimal with proper scale | | Duplicate relationship definitions | FK side: type: id, inverse: type: relationship|

Related Skills

| Skill | When to Use Together | | -------------------------- | ------------------------------------------------------------- | | aurora-cli | After editing YAML, regenerate with aurora load back module | | aurora-project-structure | To locate YAML files in correct directories | | conventional-commits | When committing schema changes |

Agent Skills: ✅ CORRECT

Install this agent skill to your local

Skill Files