skills.rest
project-ax
project-axOFFICIAL
Explore all skills by this author →
GitHub

ax-conventions

Enforce AX plugin and hook design rules for safe coupling and boundaries.

1|Updated Apr 23, 2026
Search Tags:#service hooks#plugin manifest#ax plugins#hook bus#subscriber hooks#capability security
One-click install
npx skills add https://github.com/project-ax/ax-next --skill ax-conventions
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: ax-conventions
Source: https://github.com/project-ax/ax-next/tree/main/.claude/skills/ax-conventions
Command: npx skills add https://github.com/project-ax/ax-next --skill ax-conventions

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Standardizes how to write and modify AX plugins and hooks so they remain transport/storage agnostic, avoid unsafe coupling, and stay fully wired and correct across the system.

Core Features & Use Cases

  • The five invariants: enforce transport- and storage-agnostic hook payloads, prohibit cross-plugin imports, prevent half-wired plugins, ensure one source of truth per concept, and require explicit/minimized capabilities with untrusted content handling.
  • Plugin manifest format: document and implement manifest.registers, manifest.calls, manifest.optionalCalls, and manifest.subscribes so boot-time validation and dependency cycles behave predictably.
  • Hook bus mechanics: choose between service hooks (hooks.call) and subscriber hooks (hooks.fire), including timeout behavior, return-shape validation, and isolation of subscriber failures.
  • Boundary review checklist: guide signature changes and payload evolution with checks for alternative implementations, payload leak risks, subscriber risk around “opaque” tokens, and correct wire surface ownership.
  • Common patterns: apply opaque version tokens, lazy content fetchers in deltas, optimistic concurrency via parent, two-phase validation (pre-apply/applied), construction-time config, boot-time cycle detection, and tenant-scoped query helpers.

Quick Start

Use the ax-conventions skill when you are about to add a new hook signature or modify an existing AX plugin so you can validate your payload shape, dependencies, and security boundaries before merging.

Frequently Asked Questions about ax-conventions

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I prevent unsafe coupling when writing AX plugins and service hooks?▼

To prevent unsafe coupling in AX plugins, enforce the five invariants: keep hook payloads transport-agnostic, prohibit cross-plugin imports, ensure no half-wired plugins, maintain one source of truth, and require explicit minimized capabilities.

What is the difference between service hooks and subscriber hooks in a hook bus?▼

Service hooks use `hooks.call` for request-response patterns with return-shape validation, while subscriber hooks use `hooks.fire` for event broadcasting with subscriber failure isolation and specific timeout behaviors.

How do I configure a plugin manifest to detect dependency cycles at boot time?▼

Configure dependency cycles in a plugin manifest by documenting `manifest.registers`, `manifest.calls`, `manifest.optionalCalls`, and `manifest.subscribes`, which ensures boot-time validation and predictable cycle detection.

How do you handle untrusted content and opaque tokens during a boundary review?▼

Handle untrusted content during a boundary review by applying a security checklist that uses opaque version tokens, lazy content fetchers in deltas, and minimized capabilities to prevent payload leak risks and protect subscriber boundaries.

When should I use two-phase validation and optimistic concurrency in plugin design?▼

Use two-phase validation with `pre-apply` and `applied` stages alongside optimistic concurrency via `parent` when modifying AX plugins to ensure safe payload evolution and correct hook bus behavior across transport systems.

Related Skills

Explore More Software Engineering Skills→
arvindbattulaarvindbattula

api-contracts

Define stable API contracts for REST endpoints and TypeScript interfaces before implementation.

Community
Advanced
ysyecustysyecust
40

springboot-verification

Verify Spring Boot projects with builds, static analysis, tests, and security scans.

Community
Advanced
nextplus896nextplus896

laravel-multi-tenancy

Establish multi-tenant architecture with per-tenant databases in Laravel.

Community
Intermediate
erichugyerichugy

observer-pattern

Implement a typed publish/subscribe event bus with subscription management and cleanup.

Community
Intermediate