agents-united 0.5.0

package/registry/skills/micro-interaction-design/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: micro-interaction-design
+description: Production-grade Micro Interaction Design playbook for design
+  operations, UX systems, and growth strategy.
+metadata:
+  author: agents-united
+  version: 2.0.0
+  icon: 💫
+disable-slash-command: true
+---
+
+# Micro Interaction Design
+
+## Overview & Purpose
+The Micro Interaction Design skill provides a deterministic framework for executing micro interaction design processes in modern software products.
+
+Following this skill ensures high usability, visual consistency, rapid iteration, and complete cross-functional team alignment.
+
+## Execution Triggers & Prerequisites
+### Execution Triggers
+- Direct request to execute Micro Interaction Design tasks.
+- Auditing existing product assets or workflows.
+- Standardizing micro-interaction-design procedures across team projects.
+- Preparing design handoffs or growth campaign launches.
+
+### Prerequisites
+- Project workspace configured with design system tokens or component libraries.
+- Target UI design specification or growth experiment hypothesis.
+- Testing and linting tools operational.
+- Clean git working directory.
+
+## Input & Output Requirements
+### Inputs
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `target_scope` | String | Yes | Target UI component, page, or campaign scope |
+| `config` | Object | Optional | Specific parameters and threshold configurations |
+| `output_dir` | Directory Path | Optional | Destination directory for generated artifacts |
+| `strict_mode` | Boolean | Optional | Enforce strict zero-warning validation |
+
+### Outputs
+| Artifact | Path / Format | Description |
+|---|---|---|
+| Specification Document | `docs/micro-interaction-design/spec.md` | Full specification and guidelines document |
+| Component / Asset Files | `src/micro-interaction-design/*` | Implemented design tokens, components, or campaign assets |
+| Audit Report | `reports/micro-interaction-design/summary.json` | Health check and audit metric results |
+
+## Step-by-Step Execution Runbook
+
+### Phase 1: Pre-Execution Discovery & Workspace Analysis
+1. Inspect workspace repository to locate relevant UI components, tokens, or campaign assets.
+   ```bash
+   find src/ docs/ -maxdepth 3 -type f
+   ```
+2. Analyze domain requirements and classify core UI elements, interaction flows, or growth metrics.
+3. Establish baseline quality metrics and target benchmarks.
+4. Verify working tree status to ensure clean git workspace.
+   ```bash
+   git status --short
+   ```
+5. Formulate initial execution plan.
+
+### Phase 2: Input Contract Validation & Strategy Selection
+1. Validate input parameters against technical feasibility and design system guidelines.
+2. Select implementation pattern matching component or campaign architecture.
+3. Establish verification rules and accessibility / conversion thresholds.
+4. Formulate atomic step-by-step execution sequence.
+5. Create temporary working directory if needed.
+
+### Phase 3: Core Step-by-Step Implementation Execution
+1. Author primary specification document at `docs/micro-interaction-design/spec.md`.
+2. Generate code, token, or layout implementation files.
+   ```bash
+   npm run typecheck
+   ```
+3. Apply automated formatting and linting tools.
+4. Execute unit or visual regression tests.
+   ```bash
+   npm test
+   ```
+5. Refactor asset structure for optimal performance and maintainability.
+
+### Phase 4: Verification, Testing & Quality Gate Checking
+1. Run full project verification suite.
+   ```bash
+   npm run typecheck && npm test && npm run build
+   ```
+2. Verify zero lint errors, type warnings, or broken references.
+3. Execute CLI health doctor check.
+   ```bash
+   node dist/cli.js doctor
+   ```
+4. Assert all acceptance criteria are satisfied.
+
+### Phase 5: Post-Execution Cleanup & Artifact Generation
+1. Generate execution summary report at `reports/micro-interaction-design/summary.md`.
+2. Clean up temporary build artifacts and scratch files.
+3. Commit generated files to git repository.
+   ```bash
+   git add docs/micro-interaction-design/ reports/micro-interaction-design/
+   git commit -m "feat(micro-interaction-design): implement Micro Interaction Design playbook artifacts"
+   ```
+4. Publish documentation for team review.
+
+## Code & Configuration Exemplars
+
+### Exemplar 1: Micro Interaction Design Configuration Specification
+```yaml
+version: "2.0.0"
+metadata:
+  skill: "micro-interaction-design"
+  author: "agents-united"
+rules:
+  strictValidation: true
+  reporting:
+    format: "json"
+    output: "reports/micro-interaction-design/summary.json"
+```
+
+### Exemplar 2: Micro Interaction Design Helper Module
+```typescript
+export function runMicroInteractionDesign(scope: string): boolean {
+  console.log('Running Micro Interaction Design on:', scope);
+  return true;
+}
+```
+
+## Edge Cases & Error Recovery Procedures
+
+### Scenario A: Validation Failure in Micro Interaction Design
+1. **Diagnosis**: Specification or code asset fails validation rules in micro-interaction-design.
+2. **Recovery Protocol**:
+   - Step 1: Inspect error log at reports directory.
+   - Step 2: Correct non-compliant syntax or structure.
+   - Step 3: Re-run verification pipeline.
+
+### Scenario B: Missing Resource for Micro Interaction Design
+1. **Diagnosis**: Target design token or configuration asset missing from workspace.
+2. **Recovery Protocol**:
+   - Step 1: Generate baseline resource file from standard template.
+   - Step 2: Update configuration references.
+   - Step 3: Resume runbook execution.
+
+## Verification & Validation Checklist
+- [ ] Frontmatter conforms strictly to `author: "agents-united"` and `version: "2.0.0"`.
+- [ ] All 7 mandatory sections present with explicit headers.
+- [ ] Step-by-Step Execution Runbook body contains >= 50 lines.
+- [ ] Code exemplars provided with valid syntax fencing.
+- [ ] Zero dummy placeholder strings or unpopulated template markers present.
+- [ ] Project build, test suite, and doctor check pass 100% cleanly.

package/registry/skills/microservices-architecture/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: microservices-architecture
+description: Production-grade Microservices Architecture playbook for resilient
+  distributed systems, event choreography, and observability.
+metadata:
+  author: agents-united
+  version: 2.0.0
+  icon: 🌐
+disable-slash-command: true
+---
+
+# Microservices Architecture, Service Mesh & Distributed Systems
+
+## Overview & Purpose
+The Microservices Architecture, Service Mesh & Distributed Systems skill provides a deterministic, battle-tested framework for executing microservices-architecture processes across the Agents United multi-agent ecosystem.
+
+Following this skill ensures high quality, zero-regression execution, rigorous testing gates, and seamless cross-functional team alignment.
+
+## Execution Triggers & Prerequisites
+### Execution Triggers
+- Direct request or workflow step invoking microservices-architecture.
+- Auditing, implementing, or standardizing microservices-architecture procedures.
+- Addressing technical debt, architectural reviews, or production readiness gates.
+- Preparing pull requests or automated release validations.
+
+### Prerequisites
+- Active project repository workspace with version control configured.
+- Operational testing, typechecking, and build toolchains.
+- Domain requirements, architectural constraints, or user stories defined.
+- Clean git working tree before beginning execution.
+
+## Input & Output Requirements
+### Inputs
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `target_scope` | String | Yes | Target module, service, component, or file path |
+| `config` | Object | Optional | Specific domain configurations, thresholds, and options |
+| `output_dir` | Directory Path | Optional | Destination directory for generated artifacts and reports |
+| `strict_mode` | Boolean | Optional | Enforce strict zero-warning validation and high test coverage |
+
+### Outputs
+| Artifact | Path / Format | Description |
+|---|---|---|
+| Specification Document | `docs/microservices-architecture/spec.md` | Full technical specification and architectural plan |
+| Implementation Files | `src/microservices-architecture/*` | Production-ready source code, tests, and configurations |
+| Execution Report | `reports/microservices-architecture/summary.json` | Verification metrics, test results, and audit summary |
+
+## Step-by-Step Execution Runbook
+
+### Phase 1: Bounded Context Decomposition & Service Sizing
+1. Apply Domain-Driven Design (DDD) strategic design to partition monolith into bounded contexts.
+2. Define service ownership boundaries around independent business capabilities.
+3. Ensure microservices own their private datastores to prevent shared-database anti-patterns.
+4. Evaluate asynchronous event choreography vs synchronous gRPC orchestration.
+5. Establish service dependency graph with zero circular dependencies.
+
+### Phase 2: Resiliency & Fault Tolerance Engineering
+1. Implement Circuit Breaker pattern (Cockatiel / Resilience4j) on all inter-service HTTP/gRPC calls.
+2. Configure exponential backoff retry policies with jitter to avoid thundering herds.
+3. Implement Transactional Outbox Pattern to guarantee atomic database updates and event publishing.
+4. Design idempotent event consumers using deduplication tables.
+5. Configure bulkhead isolation to prevent failure cascading across services.
+
+### Phase 3: Distributed Tracing & Observability Instrumentation
+1. Instrument OpenTelemetry (OTel) distributed tracing across all HTTP, gRPC, and messaging headers.
+2. Inject W3C TraceContext headers (traceparent, tracestate) across service boundaries.
+3. Expose standardized Prometheus metrics (/metrics): RED metrics (Rate, Errors, Duration).
+4. Configure structured JSON logging with uniform fields (trace_id, span_id, service_name).
+5. Set up centralized alerting on service latency and error budget consumption.
+
+### Phase 4: Service Mesh & API Gateway Configuration
+1. Configure API Gateway (Kong, Envoy, Traefik) for edge routing, SSL termination, and rate limiting.
+2. Deploy Istio / Linkerd service mesh for mutual TLS (mTLS) zero-trust service communication.
+3. Configure traffic splitting for canary and blue-green zero-downtime deployments.
+4. Run chaos engineering experiments (Chaos Mesh) simulating random network latency and pod kills.
+5. Validate system self-healing and service mesh rerouting.
+
+### Phase 5: CI/CD Pipeline & Contract Testing Deployment
+1. Implement Pact contract testing between consuming and providing services in CI.
+2. Configure independent automated deployment pipelines per microservice.
+3. Deploy canary release to production environment.
+4. Verify distributed trace completion across live traffic.
+5. Promote service version to 100% production traffic.
+
+## Code & Configuration Exemplars
+
+### Exemplar 1: Microservices Architecture, Service Mesh & Distributed Systems Configuration & Specification
+```yaml
+// Outbox message pattern for reliable event publishing
+export interface OutboxEvent {
+  id: string;
+  aggregateType: 'Order';
+  aggregateId: string;
+  eventType: 'OrderCreated';
+  payload: Record<string, unknown>;
+  createdAt: Date;
+  publishedAt?: Date;
+}
+```
+
+### Exemplar 2: Microservices Architecture, Service Mesh & Distributed Systems TypeScript Type Contract
+```typescript
+export interface MicroserviceTopology {
+  serviceName: string;
+  boundedContext: string;
+  communication: 'sync-grpc' | 'async-event';
+  circuitBreaker: {
+    timeoutMs: number;
+    errorThresholdPercentage: number;
+    resetTimeoutMs: number;
+  };
+  observability: {
+    distributedTracing: boolean;
+    metricsEndpoint: string;
+  };
+}
+```
+
+## Edge Cases & Error Recovery Procedures
+
+### Scenario A: Validation Failure in Microservices Architecture, Service Mesh & Distributed Systems
+1. **Diagnosis**: Static analysis, typechecking, or unit tests fail validation rules during execution.
+2. **Recovery Protocol**:
+   - Step 1: Inspect detailed error log output in test/build terminal.
+   - Step 2: Formulate targeted hypothesis and isolate failing line or assertion.
+   - Step 3: Implement surgical code fix and re-run verification suite.
+
+### Scenario B: Missing or Incompatible Dependency
+1. **Diagnosis**: Required toolchain binary or library dependency is missing from the environment.
+2. **Recovery Protocol**:
+   - Step 1: Verify `package.json` engine requirements and local environment versions.
+   - Step 2: Install required peer dependencies cleanly with lockfile sync.
+   - Step 3: Resume runbook from Phase 1.
+
+## Verification & Validation Checklist
+- [ ] Frontmatter conforms strictly to `author: "agents-united"` and `version: "2.0.0"`.
+- [ ] All 7 mandatory sections present with explicit headers.
+- [ ] Step-by-Step Execution Runbook body contains >= 50 lines.
+- [ ] Code exemplars provided with valid syntax fencing.
+- [ ] Zero dummy placeholder strings or unpopulated template markers present.
+- [ ] Project build, test suite, and doctor check pass 100% cleanly.

package/registry/skills/mobile-android-design/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: mobile-android-design
+description: Android Material 3 design conventions, Jetpack Compose layouts,
+  edge-to-edge support, and responsive window size classes.
+metadata:
+  author: wshobson (wshobson/agents)
+  version: 1.0.0
+  source: https://skills.sh/wshobson/agents/mobile-android-design
+  icon: 🤖
+disable-slash-command: true
+---
+
+# Android Material 3 & Jetpack Compose Playbook
+
+## Overview & Purpose
+`mobile-android-design` defines design patterns and implementation rules for native Android applications utilizing Google's Material Design 3 system and Jetpack Compose.
+
+## Rules & Constraints
+1. **Material 3 Theming** — Utilize `MaterialTheme.colorScheme` and dynamic tonal palettes.
+2. **Edge-to-Edge Design** — Enable edge-to-edge rendering with `enableEdgeToEdge()` and handle window insets with `Modifier.safeDrawingPadding()`.
+3. **Touch Targets** — Maintain minimum touch targets of 48x48dp for all interactive elements.
+4. **Adaptive Layouts** — Support Compact, Medium, and Expanded window size classes for foldable devices and tablets.
+
+## Step-by-Step Execution Runbook
+
+### Phase 1 — Compose Scaffold Setup
+- Structure screens using `Scaffold` with `TopAppBar`, `FloatingActionButton`, and `NavigationBar`.
+- Apply appropriate content padding to prevent clipping behind status or navigation bars.
+
+### Phase 2 — State Hoisting & Recomposition
+- Hoist state parameters out of child composables into ViewModels.
+- Mark immutable domain classes with `@Immutable` / `@Stable`.
+
+### Phase 3 — Verification
+- Test composables in Compose Preview across Phone and Tablet device configurations.
+
+## Verification Checklist
+- [ ] 48x48dp minimum touch target met.
+- [ ] Safe drawing insets properly respected.
+- [ ] Material 3 color tokens used throughout.

package/registry/skills/mobile-first-design/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: mobile-first-design
+description: Production-grade Mobile First Design playbook for design
+  operations, UX systems, and growth strategy.
+metadata:
+  author: agents-united
+  version: 2.0.0
+  icon: 📱
+disable-slash-command: true
+---
+
+# Mobile First Design
+
+## Overview & Purpose
+The Mobile First Design skill provides a deterministic framework for executing mobile first design processes in modern software products.
+
+Following this skill ensures high usability, visual consistency, rapid iteration, and complete cross-functional team alignment.
+
+## Execution Triggers & Prerequisites
+### Execution Triggers
+- Direct request to execute Mobile First Design tasks.
+- Auditing existing product assets or workflows.
+- Standardizing mobile-first-design procedures across team projects.
+- Preparing design handoffs or growth campaign launches.
+
+### Prerequisites
+- Project workspace configured with design system tokens or component libraries.
+- Target UI design specification or growth experiment hypothesis.
+- Testing and linting tools operational.
+- Clean git working directory.
+
+## Input & Output Requirements
+### Inputs
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `target_scope` | String | Yes | Target UI component, page, or campaign scope |
+| `config` | Object | Optional | Specific parameters and threshold configurations |
+| `output_dir` | Directory Path | Optional | Destination directory for generated artifacts |
+| `strict_mode` | Boolean | Optional | Enforce strict zero-warning validation |
+
+### Outputs
+| Artifact | Path / Format | Description |
+|---|---|---|
+| Specification Document | `docs/mobile-first-design/spec.md` | Full specification and guidelines document |
+| Component / Asset Files | `src/mobile-first-design/*` | Implemented design tokens, components, or campaign assets |
+| Audit Report | `reports/mobile-first-design/summary.json` | Health check and audit metric results |
+
+## Step-by-Step Execution Runbook
+
+### Phase 1: Pre-Execution Discovery & Workspace Analysis
+1. Inspect workspace repository to locate relevant UI components, tokens, or campaign assets.
+   ```bash
+   find src/ docs/ -maxdepth 3 -type f
+   ```
+2. Analyze domain requirements and classify core UI elements, interaction flows, or growth metrics.
+3. Establish baseline quality metrics and target benchmarks.
+4. Verify working tree status to ensure clean git workspace.
+   ```bash
+   git status --short
+   ```
+5. Formulate initial execution plan.
+
+### Phase 2: Input Contract Validation & Strategy Selection
+1. Validate input parameters against technical feasibility and design system guidelines.
+2. Select implementation pattern matching component or campaign architecture.
+3. Establish verification rules and accessibility / conversion thresholds.
+4. Formulate atomic step-by-step execution sequence.
+5. Create temporary working directory if needed.
+
+### Phase 3: Core Step-by-Step Implementation Execution
+1. Author primary specification document at `docs/mobile-first-design/spec.md`.
+2. Generate code, token, or layout implementation files.
+   ```bash
+   npm run typecheck
+   ```
+3. Apply automated formatting and linting tools.
+4. Execute unit or visual regression tests.
+   ```bash
+   npm test
+   ```
+5. Refactor asset structure for optimal performance and maintainability.
+
+### Phase 4: Verification, Testing & Quality Gate Checking
+1. Run full project verification suite.
+   ```bash
+   npm run typecheck && npm test && npm run build
+   ```
+2. Verify zero lint errors, type warnings, or broken references.
+3. Execute CLI health doctor check.
+   ```bash
+   node dist/cli.js doctor
+   ```
+4. Assert all acceptance criteria are satisfied.
+
+### Phase 5: Post-Execution Cleanup & Artifact Generation
+1. Generate execution summary report at `reports/mobile-first-design/summary.md`.
+2. Clean up temporary build artifacts and scratch files.
+3. Commit generated files to git repository.
+   ```bash
+   git add docs/mobile-first-design/ reports/mobile-first-design/
+   git commit -m "feat(mobile-first-design): implement Mobile First Design playbook artifacts"
+   ```
+4. Publish documentation for team review.
+
+## Code & Configuration Exemplars
+
+### Exemplar 1: Mobile First Design Configuration Specification
+```yaml
+version: "2.0.0"
+metadata:
+  skill: "mobile-first-design"
+  author: "agents-united"
+rules:
+  strictValidation: true
+  reporting:
+    format: "json"
+    output: "reports/mobile-first-design/summary.json"
+```
+
+### Exemplar 2: Mobile First Design Helper Module
+```typescript
+export function runMobileFirstDesign(scope: string): boolean {
+  console.log('Running Mobile First Design on:', scope);
+  return true;
+}
+```
+
+## Edge Cases & Error Recovery Procedures
+
+### Scenario A: Validation Failure in Mobile First Design
+1. **Diagnosis**: Specification or code asset fails validation rules in mobile-first-design.
+2. **Recovery Protocol**:
+   - Step 1: Inspect error log at reports directory.
+   - Step 2: Correct non-compliant syntax or structure.
+   - Step 3: Re-run verification pipeline.
+
+### Scenario B: Missing Resource for Mobile First Design
+1. **Diagnosis**: Target design token or configuration asset missing from workspace.
+2. **Recovery Protocol**:
+   - Step 1: Generate baseline resource file from standard template.
+   - Step 2: Update configuration references.
+   - Step 3: Resume runbook execution.
+
+## Verification & Validation Checklist
+- [ ] Frontmatter conforms strictly to `author: "agents-united"` and `version: "2.0.0"`.
+- [ ] All 7 mandatory sections present with explicit headers.
+- [ ] Step-by-Step Execution Runbook body contains >= 50 lines.
+- [ ] Code exemplars provided with valid syntax fencing.
+- [ ] Zero dummy placeholder strings or unpopulated template markers present.
+- [ ] Project build, test suite, and doctor check pass 100% cleanly.

package/registry/skills/mobile-ios-design/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: mobile-ios-design
+description: iOS design system conventions, SwiftUI component patterns, Apple
+  Human Interface Guidelines, and navigation ergonomics.
+metadata:
+  author: wshobson (wshobson/agents)
+  version: 1.0.0
+  source: https://skills.sh/wshobson/agents/mobile-ios-design
+  icon: 🍏
+disable-slash-command: true
+---
+
+# iOS Design & SwiftUI Engineering Playbook
+
+## Overview & Purpose
+`mobile-ios-design` provides systemic guidance for designing native iOS applications adhering to Apple's Human Interface Guidelines (HIG) and SwiftUI architectural standards.
+
+## Rules & Constraints
+1. **Follow Apple HIG Standards** — Respect safe area insets, navigation bar titles, dynamic type, and native gestures.
+2. **Declarative State Flow** — Maintain single source of truth using `@State`, `@Binding`, and the `@Observable` macro.
+3. **Touch Targets & Ergonomics** — Ensure interactive elements have a minimum tappable area of 44x44 points.
+4. **Dark Mode & Dynamic Type** — Always utilize semantic system colors (`Color(.systemBackground)`, `Color.primary`) and semantic text styles (`.font(.title)`, `.font(.body)`).
+
+## Step-by-Step Execution Runbook
+
+### Phase 1 — Screen & Navigation Layout
+- Establish standard NavigationStack architecture with typed navigation destinations.
+- Wrap content in SafeAreaInsets and configure TabView for primary sections.
+
+### Phase 2 — Component Design
+- Design reusable SwiftUI view components with parameterizable `@Binding` properties.
+- Add `#Preview` with both Light and Dark mode variations.
+
+### Phase 3 — Verification
+- Audit view hierarchy on iPad, iPhone SE, and Dynamic Island devices.
+
+## Verification Checklist
+- [ ] View adheres to 44x44pt touch target minimum.
+- [ ] Dynamic type scales without text truncation.
+- [ ] Dark mode semantic colors applied.

package/registry/skills/mobile-platform-offline-validate/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: mobile-platform-offline-validate
+description: Offline-first architecture patterns, background sync, local
+  database persistence, and conflict resolution strategies for mobile
+  applications.
+metadata:
+  author: Salesforce (forcedotcom/sf-skills)
+  version: 1.0.0
+  source: https://skills.sh/forcedotcom/sf-skills/mobile-platform-offline-validate
+  icon: 📶
+disable-slash-command: true
+---
+
+# Mobile Offline-First & Sync Playbook
+
+## Overview & Purpose
+`mobile-platform-offline-validate` guides the architecture of offline-first mobile applications, ensuring seamless local caching, optimistic UI updates, background synchronization, and conflict resolution.
+
+## Rules & Constraints
+1. **Optimistic UI Updates** — Mutate local state immediately and display pending sync indicators to the user.
+2. **Deterministic Conflict Resolution** — Implement Last-Write-Wins (LWW) or custom CRDT / vector clock merge strategies for simultaneous updates.
+3. **Network Resilience** — Queue failed outbound mutations in a persistent local queue with exponential backoff.
+4. **Data Encryption at Rest** — Protect local SQLite / Room databases with SQLCipher or platform keychains.
+
+## Step-by-Step Execution Runbook
+
+### Phase 1 — Persistence Layer Architecture
+- Establish local SQLite / Room / WatermelonDB schema mirroring critical cloud entities.
+- Add sync metadata columns (`dirty`, `version`, `last_modified_at`, `deleted_at`).
+
+### Phase 2 — Mutation Queue & Sync Worker
+- Implement background sync worker (Android WorkManager / iOS BGTaskScheduler) triggered on network reconnect.
+- Batch outbound mutations to optimize battery and bandwidth.
+
+### Phase 3 — Verification
+- Simulate airplane mode and intermittent packet loss to verify local CRUD operations and eventual consistency.
+
+## Verification Checklist
+- [ ] Application remains fully operational without active internet connection.
+- [ ] Optimistic mutations successfully reconcile upon reconnect.
+- [ ] Conflicts resolve deterministically without data loss.

package/registry/skills/modal-serverless-python/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: modal-serverless-python
+description: Serverless Python applications, GPU function definitions (A10G,
+  H100), cold-start caching, and volume mounts on Modal.com.
+metadata:
+  author: Modal Labs / agents-united
+  version: 2.0.0
+  license: MIT
+  icon: ⚡
+disable-slash-command: true
+---
+
+# Modal Serverless Python Playbook
+
+## Overview & Purpose
+`modal-serverless-python` provides production best practices for authoring, deploying, and optimizing serverless Python AI workloads on Modal.com with hardware-accelerated GPU infrastructure and cold-start mitigations.
+
+## When to Trigger
+Trigger this skill whenever:
+- Designing serverless GPU inference functions (LLMs, Diffusion models, Whisper transcription).
+- Building fine-tuning or embedding generation pipelines requiring on-demand GPU clusters.
+- Optimizing Python container cold-start latency and GPU memory management.
+- Mounting persistent storage volumes for large machine learning model checkpoints.
+
+## Input & Output Requirements
+- **Inputs**: Model identifier (Hugging Face ID or local weights path), target GPU tier (`T4`, `A10G`, `A100`, `H100`), concurrency parameters, and environment secrets.
+- **Outputs**: Fully functional Modal Python scripts (`modal.App`), persistent volume definitions, deployment runbooks, and endpoint latency benchmarks.
+
+## Step-by-Step Execution Runbook
+
+### Phase 1 — Environment & Image Scaffolding
+- Define container images with minimal base layers and pinned PyTorch/CUDA wheels.
+- Pre-download model weights into container image layers using `image.run_function()`.
+
+### Phase 2 — GPU Function & Lifecycle Declaration
+- Decorate class-based functions with `@app.cls(gpu="A10G", container_idle_timeout=60)`.
+- Load weights into GPU VRAM once during container startup with `@modal.enter()`.
+
+### Phase 3 — Verification & Scale Testing
+- Execute test invocations using `modal run` before deploying production web endpoints (`modal deploy`).
+
+## Edge Cases & Boundary Conditions
+- **CUDA Out of Memory (OOM)**: Handle batch sizes dynamically based on available VRAM limits; fall back to gradient checkpointing or 4-bit quantization (bitsandbytes).
+- **Cold-Start Spikes**: Utilize warm pools and flash-attention container optimizations to keep cold start < 8s.
+- **Network Timeouts on Large Weight Downloads**: Split weight shards across persistent Modal Volumes.
+
+## Error Recovery & Fallbacks
+- If GPU capacity is unavailable in the primary region, configure fallback GPU selections (e.g. `gpu=["A10G", "A100"]`).
+- When secret loading fails, verify authentication with `modal secret list` and surface missing secret keys.
+
+## Code Exemplars & Patterns
+
+```python
+import modal
+
+app = modal.App("vllm-inference-service")
+
+vllm_image = (
+    modal.Image.debian_slim(python_version="3.11")
+    .pip_install("vllm==0.6.3", "torch==2.4.0", "transformers")
+)
+
+@app.cls(
+    image=vllm_image,
+    gpu="A10G",
+    scaledown_window=60,
+    timeout=300,
+)
+class ModelServer:
+    @modal.enter()
+    def load_model(self):
+        from vllm import LLM
+        self.llm = LLM(model="meta-llama/Llama-3.1-8B-Instruct")
+
+    @modal.method()
+    def generate(self, prompt: str) -> str:
+        from vllm import SamplingParams
+        sampling_params = SamplingParams(temperature=0.7, max_tokens=512)
+        outputs = self.llm.generate([prompt], sampling_params)
+        return outputs[0].outputs[0].text
+```