Optional HTML body
" + }' +``` + +Optional fields: `cc`, `bcc` (string arrays), `inReplyTo`, `references` (strings for threading), `attachments` (array of `{filename, contentType, content}` where content is base64). + +### Read inbox + +```bash +# List messages +curl https://api.theagentmail.net/v1/accounts/{accountId}/messages \ + -H "Authorization: Bearer am_..." + +# Get full message (with body and attachments) +curl https://api.theagentmail.net/v1/accounts/{accountId}/messages/{messageId} \ + -H "Authorization: Bearer am_..." +``` + +### Check karma + +```bash +curl https://api.theagentmail.net/v1/karma \ + -H "Authorization: Bearer am_..." +``` + +Response: `{"data": {"balance": 90, "events": [...]}}` + +### Register webhook (real-time inbound) + +```bash +curl -X POST https://api.theagentmail.net/v1/accounts/{accountId}/webhooks \ + -H "Authorization: Bearer am_..." \ + -H "Content-Type: application/json" \ + -d '{"url": "https://my-agent.example.com/inbox"}' +``` + +Webhook deliveries include two security headers: +- `X-AgentMail-Signature` -- HMAC-SHA256 hex digest of the request body, signed with the webhook secret +- `X-AgentMail-Timestamp` -- millisecond timestamp of when the delivery was sent + +Verify the signature and reject requests with timestamps older than 5 minutes to prevent replay attacks: + +```typescript +import { createHmac } from "crypto"; + +const verifyWebhook = (body: string, signature: string, timestamp: string, secret: string) => { + if (Date.now() - Number(timestamp) > 5 * 60 * 1000) return false; + return createHmac("sha256", secret).update(body).digest("hex") === signature; +}; +``` + +### Download attachment + +```bash +curl https://api.theagentmail.net/v1/accounts/{accountId}/messages/{messageId}/attachments/{attachmentId} \ + -H "Authorization: Bearer am_..." +``` + +Returns `{"data": {"url": "https://signed-download-url..."}}`. + +## Full API reference + +| Method | Path | Description | Karma | +|--------|------|-------------|-------| +| POST | `/v1/accounts` | Create email account | -10 | +| GET | `/v1/accounts` | List all accounts | | +| GET | `/v1/accounts/:id` | Get account details | | +| DELETE | `/v1/accounts/:id` | Delete account | +10 | +| POST | `/v1/accounts/:id/messages` | Send email | -1 | +| GET | `/v1/accounts/:id/messages` | List messages | | +| GET | `/v1/accounts/:id/messages/:msgId` | Get full message | | +| GET | `/v1/accounts/:id/messages/:msgId/attachments/:attId` | Get attachment URL | | +| POST | `/v1/accounts/:id/webhooks` | Register webhook | | +| GET | `/v1/accounts/:id/webhooks` | List webhooks | | +| DELETE | `/v1/accounts/:id/webhooks/:whId` | Delete webhook | | +| GET | `/v1/karma` | Get balance + events | | + +## Karma system + +Every action has a karma cost or reward: + +| Event | Karma | Why | +|---|---|---| +| `money_paid` | +100 | Purchase credits | +| `email_received` | +2 | Someone replied from a trusted domain | +| `account_deleted` | +10 | Karma refunded when you delete an address | +| `email_sent` | -1 | Sending costs karma | +| `account_created` | -10 | Creating addresses costs karma | + +**Important rules:** +- Karma is only awarded for inbound emails from trusted providers (Gmail, Outlook, Yahoo, iCloud, ProtonMail, Fastmail, Hey, etc.). Emails from unknown/throwaway domains don't earn karma. +- You only earn karma once per sender until the agent replies. If sender X emails you 5 times without a reply, only the first earns karma. Reply to X, and the next email from X earns karma again. +- Deleting an account refunds the 10 karma it cost to create. + +When karma reaches 0, sends and account creation return HTTP 402. Always check balance before operations that cost karma. + +## TypeScript SDK + +```typescript +import { createClient } from "@agentmail/sdk"; + +const mail = createClient({ apiKey: "am_..." }); + +// Create account +const account = await mail.accounts.create({ + address: "my-agent@theagentmail.net", +}); + +// Send email +await mail.messages.send(account.id, { + to: ["human@example.com"], + subject: "Hello", + text: "Sent by an AI agent.", +}); + +// Read inbox +const messages = await mail.messages.list(account.id); +const detail = await mail.messages.get(account.id, messages[0].id); + +// Attachments +const att = await mail.attachments.getUrl(accountId, messageId, attachmentId); +// att.url is a signed download URL + +// Webhooks +await mail.webhooks.create(account.id, { + url: "https://my-agent.example.com/inbox", +}); + +// Karma +const karma = await mail.karma.getBalance(); +console.log(karma.balance); +``` + +## Error handling + +```typescript +import { AgentMailError } from "@agentmail/sdk"; + +try { + await mail.messages.send(accountId, { to: ["a@b.com"], subject: "Hi", text: "Hey" }); +} catch (e) { + if (e instanceof AgentMailError) { + console.log(e.status); // 402, 404, 401, etc. + console.log(e.code); // "INSUFFICIENT_KARMA", "NOT_FOUND", etc. + console.log(e.message); + } +} +``` + +## Common patterns + +### Sign up for a service and read verification email + +```typescript +const account = await mail.accounts.create({ + address: "signup-bot@theagentmail.net", +}); + +// Use the address to sign up (browser automation, API, etc.) + +// Poll for verification email +for (let i = 0; i < 30; i++) { + const messages = await mail.messages.list(account.id); + const verification = messages.find(m => + m.subject.toLowerCase().includes("verify") || + m.subject.toLowerCase().includes("confirm") + ); + if (verification) { + const detail = await mail.messages.get(account.id, verification.id); + // Parse verification link/code from detail.bodyText or detail.bodyHtml + break; + } + await new Promise(r => setTimeout(r, 2000)); +} +``` + +### Send email and wait for reply + +```typescript +const sent = await mail.messages.send(account.id, { + to: ["human@company.com"], + subject: "Question about order #12345", + text: "Can you check the status?", +}); + +for (let i = 0; i < 60; i++) { + const messages = await mail.messages.list(account.id); + const reply = messages.find(m => + m.direction === "inbound" && m.timestamp > sent.timestamp + ); + if (reply) { + const detail = await mail.messages.get(account.id, reply.id); + // Process reply + break; + } + await new Promise(r => setTimeout(r, 5000)); +} +``` + +## Types + +```typescript +type Account = { id: string; address: string; displayName: string | null; createdAt: number }; +type Message = { id: string; from: string; to: string[]; subject: string; direction: "inbound" | "outbound"; status: string; timestamp: number }; +type MessageDetail = Message & { cc: string[] | null; bcc: string[] | null; bodyText: string | null; bodyHtml: string | null; inReplyTo: string | null; references: string | null; attachments: AttachmentMeta[] }; +type AttachmentMeta = { id: string; filename: string; contentType: string; size: number }; +type KarmaBalance = { balance: number; events: KarmaEvent[] }; +type KarmaEvent = { id: string; type: string; amount: number; timestamp: number; metadata?: Record{{ count() }}
`,
+})
+export class CounterComponent {
+ count = signal(0);
+}
+
+// WRONG - Default change detection
+@Component({
+ template: `{{ count }}
`, // Checked every cycle
+})
+export class CounterComponent {
+ count = 0;
+}
+```
+
+### Prefer Signals Over Mutable Properties
+
+```typescript
+// CORRECT - Signals trigger precise updates
+@Component({
+ template: `
+ {{ title() }}
+Count: {{ count() }}
+ `, +}) +export class DashboardComponent { + title = signal("Dashboard"); + count = signal(0); +} + +// WRONG - Mutable properties require zone.js checks +@Component({ + template: ` +{{ title }}
+Count: {{ count }}
+ `, +}) +export class DashboardComponent { + title = "Dashboard"; + count = 0; +} +``` + +### Enable Zoneless for New Projects + +```typescript +// main.ts - Zoneless Angular (v20+) +bootstrapApplication(AppComponent, { + providers: [provideZonelessChangeDetection()], +}); +``` + +**Benefits:** + +- No zone.js patches on async APIs +- Smaller bundle (~15KB savings) +- Clean stack traces for debugging +- Better micro-frontend compatibility + +--- + +## 2. Async Operations & Waterfalls (CRITICAL) + +### Eliminate Sequential Data Fetching + +```typescript +// WRONG - Nested subscriptions create waterfalls +this.route.params.subscribe((params) => { + // 1. Wait for params + this.userService.getUser(params.id).subscribe((user) => { + // 2. Wait for user + this.postsService.getPosts(user.id).subscribe((posts) => { + // 3. Wait for posts + }); + }); +}); + +// CORRECT - Parallel execution with forkJoin +forkJoin({ + user: this.userService.getUser(id), + posts: this.postsService.getPosts(id), +}).subscribe((data) => { + // Fetched in parallel +}); + +// CORRECT - Flatten dependent calls with switchMap +this.route.params + .pipe( + map((p) => p.id), + switchMap((id) => this.userService.getUser(id)), + ) + .subscribe(); +``` + +### Avoid Client-Side Waterfalls in SSR + +```typescript +// CORRECT - Use resolvers or blocking hydration for critical data +export const route: Route = { + path: "profile/:id", + resolve: { data: profileResolver }, // Fetched on server before navigation + component: ProfileComponent, +}; + +// WRONG - Component fetches data on init +class ProfileComponent implements OnInit { + ngOnInit() { + // Starts ONLY after JS loads and component renders + this.http.get("/api/profile").subscribe(); + } +} +``` + +--- + +## 3. Bundle Optimization (CRITICAL) + +### Lazy Load Routes + +```typescript +// CORRECT - Lazy load feature routes +export const routes: Routes = [ + { + path: "admin", + loadChildren: () => + import("./admin/admin.routes").then((m) => m.ADMIN_ROUTES), + }, + { + path: "dashboard", + loadComponent: () => + import("./dashboard/dashboard.component").then( + (m) => m.DashboardComponent, + ), + }, +]; + +// WRONG - Eager loading everything +import { AdminModule } from "./admin/admin.module"; +export const routes: Routes = [ + { path: "admin", component: AdminComponent }, // In main bundle +]; +``` + +### Use @defer for Heavy Components + +```html + +@defer (on viewport) { +
+ {{ item.name }}
+
+ No items
+} + + +{{ user.name }} +{{ data().name }}
`,
+})
+export class Component {
+ data = toSignal(this.service.data$, { initialValue: null });
+}
+
+// WRONG - Manual subscription
+@Component({
+ template: `{{ data?.name }}
`,
+})
+export class Component implements OnInit, OnDestroy {
+ data: Data | null = null;
+ private sub!: Subscription;
+
+ ngOnInit() {
+ this.sub = this.service.data$.subscribe((d) => (this.data = d));
+ }
+
+ ngOnDestroy() {
+ this.sub.unsubscribe();
+ }
+}
+```
+
+---
+
+## Quick Reference Checklist
+
+### New Component
+
+- [ ] `changeDetection: ChangeDetectionStrategy.OnPush`
+- [ ] `standalone: true`
+- [ ] Signals for state (`signal()`, `input()`, `output()`)
+- [ ] `inject()` for dependencies
+- [ ] `@for` with `track` expression
+
+### Performance Review
+
+- [ ] No methods in templates (use pipes or computed)
+- [ ] Large lists virtualized
+- [ ] Heavy components deferred
+- [ ] Routes lazy-loaded
+- [ ] Third-party libs dynamically imported
+
+### SSR Check
+
+- [ ] Hydration configured
+- [ ] Critical content renders first
+- [ ] Non-critical content uses `@defer (hydrate on ...)`
+- [ ] TransferState for server-fetched data
+
+---
+
+## Resources
+
+- [Angular Performance Guide](https://angular.dev/best-practices/performance)
+- [Zoneless Angular](https://angular.dev/guide/experimental/zoneless)
+- [Angular SSR Guide](https://angular.dev/guide/ssr)
+- [Change Detection Deep Dive](https://angular.dev/guide/change-detection)
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.
diff --git a/packages/llm/skills/angular-best-practices/metadata.json b/packages/llm/skills/angular-best-practices/metadata.json
new file mode 100644
index 00000000..633f57c6
--- /dev/null
+++ b/packages/llm/skills/angular-best-practices/metadata.json
@@ -0,0 +1,13 @@
+{
+ "version": "1.0.0",
+ "organization": "Antigravity Awesome Skills",
+ "date": "February 2026",
+ "abstract": "Performance optimization and best practices guide for Angular applications designed for AI agents and LLMs. Covers change detection strategies (OnPush, Signals, Zoneless), avoiding async waterfalls, bundle optimization with lazy loading and @defer, rendering performance, SSR/hydration patterns, and memory management. Prioritized by impact from critical to incremental improvements.",
+ "references": [
+ "https://angular.dev/best-practices",
+ "https://angular.dev/guide/performance",
+ "https://angular.dev/guide/zoneless",
+ "https://angular.dev/guide/ssr",
+ "https://web.dev/performance"
+ ]
+}
diff --git a/packages/llm/skills/angular-migration/SKILL.md b/packages/llm/skills/angular-migration/SKILL.md
new file mode 100644
index 00000000..760df3dc
--- /dev/null
+++ b/packages/llm/skills/angular-migration/SKILL.md
@@ -0,0 +1,431 @@
+---
+name: angular-migration
+description: "Migrate from AngularJS to Angular using hybrid mode, incremental component rewriting, and dependency injection updates. Use when upgrading AngularJS applications, planning framework migrations, or ..."
+risk: unknown
+source: community
+date_added: "2026-02-27"
+---
+
+# Angular Migration
+
+Master AngularJS to Angular migration, including hybrid apps, component conversion, dependency injection changes, and routing migration.
+
+## Use this skill when
+
+- Migrating AngularJS (1.x) applications to Angular (2+)
+- Running hybrid AngularJS/Angular applications
+- Converting directives to components
+- Modernizing dependency injection
+- Migrating routing systems
+- Updating to latest Angular versions
+- Implementing Angular best practices
+
+## Do not use this skill when
+
+- You are not migrating from AngularJS to Angular
+- The app is already on a modern Angular version
+- You need only a small UI fix without framework changes
+
+## Instructions
+
+1. Assess the AngularJS codebase, dependencies, and migration risks.
+2. Choose a migration strategy (hybrid vs rewrite) and define milestones.
+3. Set up ngUpgrade and migrate modules, components, and routing.
+4. Validate with tests and plan a safe cutover.
+
+## Safety
+
+- Avoid big-bang cutovers without rollback and staging validation.
+- Keep hybrid compatibility testing during incremental migration.
+
+## Migration Strategies
+
+### 1. Big Bang (Complete Rewrite)
+- Rewrite entire app in Angular
+- Parallel development
+- Switch over at once
+- **Best for:** Small apps, green field projects
+
+### 2. Incremental (Hybrid Approach)
+- Run AngularJS and Angular side-by-side
+- Migrate feature by feature
+- ngUpgrade for interop
+- **Best for:** Large apps, continuous delivery
+
+### 3. Vertical Slice
+- Migrate one feature completely
+- New features in Angular, maintain old in AngularJS
+- Gradually replace
+- **Best for:** Medium apps, distinct features
+
+## Hybrid App Setup
+
+```typescript
+// main.ts - Bootstrap hybrid app
+import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
+import { UpgradeModule } from '@angular/upgrade/static';
+import { AppModule } from './app/app.module';
+
+platformBrowserDynamic()
+ .bootstrapModule(AppModule)
+ .then(platformRef => {
+ const upgrade = platformRef.injector.get(UpgradeModule);
+ // Bootstrap AngularJS
+ upgrade.bootstrap(document.body, ['myAngularJSApp'], { strictDi: true });
+ });
+```
+
+```typescript
+// app.module.ts
+import { NgModule } from '@angular/core';
+import { BrowserModule } from '@angular/platform-browser';
+import { UpgradeModule } from '@angular/upgrade/static';
+
+@NgModule({
+ imports: [
+ BrowserModule,
+ UpgradeModule
+ ]
+})
+export class AppModule {
+ constructor(private upgrade: UpgradeModule) {}
+
+ ngDoBootstrap() {
+ // Bootstrapped manually in main.ts
+ }
+}
+```
+
+## Component Migration
+
+### AngularJS Controller → Angular Component
+```javascript
+// Before: AngularJS controller
+angular.module('myApp').controller('UserController', function($scope, UserService) {
+ $scope.user = {};
+
+ $scope.loadUser = function(id) {
+ UserService.getUser(id).then(function(user) {
+ $scope.user = user;
+ });
+ };
+
+ $scope.saveUser = function() {
+ UserService.saveUser($scope.user);
+ };
+});
+```
+
+```typescript
+// After: Angular component
+import { Component, OnInit } from '@angular/core';
+import { UserService } from './user.service';
+
+@Component({
+ selector: 'app-user',
+ template: `
+
+
+ `
+})
+export class UserComponent implements OnInit {
+ user: any = {};
+
+ constructor(private userService: UserService) {}
+
+ ngOnInit() {
+ this.loadUser(1);
+ }
+
+ loadUser(id: number) {
+ this.userService.getUser(id).subscribe(user => {
+ this.user = user;
+ });
+ }
+
+ saveUser() {
+ this.userService.saveUser(this.user);
+ }
+}
+```
+
+### AngularJS Directive → Angular Component
+```javascript
+// Before: AngularJS directive
+angular.module('myApp').directive('userCard', function() {
+ return {
+ restrict: 'E',
+ scope: {
+ user: '=',
+ onDelete: '&'
+ },
+ template: `
+ {{ user.name }}
+ +
+
+ `
+ };
+});
+```
+
+```typescript
+// After: Angular component
+import { Component, Input, Output, EventEmitter } from '@angular/core';
+
+@Component({
+ selector: 'app-user-card',
+ template: `
+ {{ user.name }}
+ +
+
+ `
+})
+export class UserCardComponent {
+ @Input() user: any;
+ @Output() delete = new EventEmitter{{ user.name }}
+ +Count: {{ counter.count() }}
+Doubled: {{ counter.doubled() }}
+ + `, +}) +export class CounterComponent { + counter = inject(CounterService); +} +``` + +### Pattern 2: Feature Signal Store + +```typescript +// stores/user.store.ts +import { Injectable, signal, computed, inject } from "@angular/core"; +import { HttpClient } from "@angular/common/http"; +import { toSignal } from "@angular/core/rxjs-interop"; + +interface User { + id: string; + name: string; + email: string; +} + +interface UserState { + user: User | null; + loading: boolean; + error: string | null; +} + +@Injectable({ providedIn: "root" }) +export class UserStore { + private http = inject(HttpClient); + + // State signals + private _user = signalWelcome, {{ user.name }}
+ + } + `, +}) +export class HeaderComponent { + private store = inject(Store); + + user = this.store.selectSignal(selectUser); + loading = this.store.selectSignal(selectUserLoading); + + logout() { + this.store.dispatch(UserActions.logout()); + } +} +``` + +--- + +## RxJS-Based Patterns + +### Component Store (Local Feature State) + +```typescript +// stores/todo.store.ts +import { Injectable } from "@angular/core"; +import { ComponentStore } from "@ngrx/component-store"; +import { switchMap, tap, catchError, EMPTY } from "rxjs"; + +interface TodoState { + todos: Todo[]; + loading: boolean; +} + +@Injectable() +export class TodoStore extends ComponentStore
+ ![]()
+
+ `,
+})
+export class ErrorStateComponent {
+ title = input("Something went wrong");
+ message = input("An unexpected error occurred");
+ retry = output{{ title() }}
+{{ message() }}
+ @if (retry.observed) { + + } +
+
+
+ `,
+})
+export class EmptyStateComponent {
+ icon = input("inbox");
+ title = input.required{{ title() }}
+{{ description() }}
+ @if (actionLabel()) { + + } +
+
+ `,
+})
+export class UserCardComponent {
+ // Signal inputs (read-only)
+ id = input.required{{ name() }}
+ {{ role() }} + +Count: {{ count() }}
+
+ `,
+})
+export class CounterComponent {
+ count = signal(0);
+
+ increment() {
+ this.count.update((v) => v + 1);
+ // No zone.js needed - Signal triggers change detection
+ }
+}
+```
+
+### Key Zoneless Benefits
+
+- **Performance**: No zone.js patches on async APIs
+- **Debugging**: Clean stack traces without zone wrappers
+- **Bundle size**: Smaller without zone.js (~15KB savings)
+- **Interoperability**: Better with Web Components and micro-frontends
+
+---
+
+## 4. Server-Side Rendering & Hydration
+
+### SSR Setup with Angular CLI
+
+```bash
+ng add @angular/ssr
+```
+
+### Hydration Configuration
+
+```typescript
+// app.config.ts
+import { ApplicationConfig } from "@angular/core";
+import {
+ provideClientHydration,
+ withEventReplay,
+} from "@angular/platform-browser";
+
+export const appConfig: ApplicationConfig = {
+ providers: [provideClientHydration(withEventReplay())],
+};
+```
+
+### Incremental Hydration (v20+)
+
+```typescript
+import { Component } from "@angular/core";
+
+@Component({
+ selector: "app-page",
+ standalone: true,
+ template: `
+
+
+ `
+})
+export class CardComponent {}
+
+// Usage
+
+
+
+
+
+
+ Title
+Body content
+Failed to load chart
+ } + ` +}) +``` + +### NgOptimizedImage + +```typescript +import { NgOptimizedImage } from '@angular/common'; + +@Component({ + imports: [NgOptimizedImage], + template: ` +Test
+ + + +<h1>Encoded</h1> +%3Ch1%3EURL%20Encoded%3C%2Fh1%3E + + +Hover me
+Test
", + "Bold", + "", + "Styled
",
+ "",
+ "",
+]
+
+for payload in payloads:
+ encoded = urllib.parse.quote(payload)
+ url = f"{target}?{param}={encoded}"
+
+ try:
+ response = requests.get(url, timeout=5)
+ if payload.lower() in response.text.lower():
+ print(f"[+] Possible injection: {payload}")
+ elif "" in response.text or "" in response.text: + print(f"[?] Partial reflection: {payload}") + except Exception as e: + print(f"[-] Error: {e}") +``` + +### Phase 10: Prevention and Remediation + +Secure coding practices: + +```php +// PHP: Escape output +echo htmlspecialchars($user_input, ENT_QUOTES, 'UTF-8'); + +// PHP: Strip tags +echo strip_tags($user_input); + +// PHP: Allow specific tags only +echo strip_tags($user_input, '
');
+```
+
+```python
+# Python: HTML escape
+from html import escape
+safe_output = escape(user_input)
+
+# Python Flask: Auto-escaping
+{{ user_input }} # Jinja2 escapes by default
+{{ user_input | safe }} # Marks as safe (dangerous!)
+```
+
+```javascript
+// JavaScript: Text content (safe)
+element.textContent = userInput;
+
+// JavaScript: innerHTML (dangerous!)
+element.innerHTML = userInput; // Vulnerable!
+
+// JavaScript: Sanitize
+const clean = DOMPurify.sanitize(userInput);
+element.innerHTML = clean;
+```
+
+Server-side protections:
+- Input validation (whitelist allowed characters)
+- Output encoding (context-aware escaping)
+- Content Security Policy (CSP) headers
+- Web Application Firewall (WAF) rules
+
+## Quick Reference
+
+### Common Test Payloads
+
+| Payload | Purpose |
+|---------|---------|
+| `Test
` | Basic rendering test |
+| `Bold` | Simple formatting |
+| `Link` | Link injection |
+| `` | Image tag test |
+| `
` | Style injection |
+| `