@agentuity/skills 3.1.1

package/README.md

@@ -0,0 +1,51 @@
+# @agentuity/skills
+
+Official [Agent Skills](https://agentskills.io/) for AI coding agents working with the Agentuity SDK.
+
+Skills ship inside this npm package under `skills/` and are discovered by [skills-npm](https://github.com/antfu/skills-npm) when installed as a project dependency.
+
+## Skills
+
+| Skill | Description |
+|-------|-------------|
+| **agentuity-project** | Create, import, run, build, and deploy framework apps |
+| **agentuity-frameworks** | Put routes, pages, server functions, config, and service clients in framework-native files |
+| **agentuity-ai** | Build model-backed features with AI Gateway, structured output, streaming, tools, and app-owned state |
+| **agentuity-services** | Choose and use Agentuity service clients from server-side app code |
+| **agentuity-database** | Use Agentuity-managed Postgres through `DATABASE_URL`, `pg`, Drizzle, or trusted admin scripts |
+| **agentuity-background-work** | Add queues, schedules, webhooks, tasks, durable output, and status handles |
+| **agentuity-cloud** | Manage deployments, logs, env, regions, resources, SSH, and debugging through the CLI |
+| **agentuity-cli** | Use CLI auth, profiles, JSON, schemas, structured input, and command discovery |
+
+## Install (npm)
+
+```bash
+npm i -D @agentuity/skills skills-npm
+npx skills-npm setup
+```
+
+Or use the Agentuity CLI in an existing project:
+
+```bash
+agentuity skills install
+```
+
+New Agentuity projects scaffold with skills wiring enabled by default.
+
+## Install (Git registry)
+
+```bash
+npx skills add agentuity/sdk/skills
+npx skills add agentuity/sdk/skills --skill agentuity-ai
+npx skills add agentuity/sdk/skills -a cursor
+```
+
+The repo-root [`skills/`](../../skills/) directory is synced from this package on release.
+
+## Claude Code plugin
+
+Deployment-opinionated skills for Claude Code ship separately in `@agentuity/claude-code` — not in this package.
+
+## License
+
+Apache-2.0

package/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "@agentuity/skills",
+	"version": "3.1.1",
+	"license": "Apache-2.0",
+	"author": "Agentuity",
+	"description": "Agent Skills for AI coding agents working with the Agentuity SDK",
+	"type": "module",
+	"agentuity": {
+		"sourceOnly": true
+	},
+	"files": [
+		"README.md",
+		"skills"
+	],
+	"scripts": {
+		"prepublishOnly": "bun ./scripts/sync-root-skills.ts",
+		"sync:root": "bun ./scripts/sync-root-skills.ts"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"sideEffects": false,
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/agentuity/sdk.git",
+		"directory": "packages/skills"
+	}
+}

package/skills/agentuity-ai/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: agentuity-ai
+description: >-
+  Use when building model-backed Agentuity features, AI routes, structured
+  output, chat, streaming, tool calling, or app-owned state and memory. Covers
+  plain server functions, AIGatewayClient, provider SDK choices, validation,
+  KV-backed history, and safe tool execution.
+license: Apache-2.0
+metadata:
+  author: agentuity
+  version: "1.0.0"
+---
+
+# Agentuity AI Features
+
+An Agentuity agent is model-backed app code with a clear task. Put the task in a
+plain server-side function, validate its inputs and outputs, then call it from
+the framework route, worker, schedule, script, or queue handler that owns the
+trigger.
+
+## Minimal Shape
+
+```bash
+npm install @agentuity/aigateway @agentuity/keyvalue zod
+```
+
+```typescript
+import { AIGatewayClient } from '@agentuity/aigateway';
+import { KeyValueClient } from '@agentuity/keyvalue';
+import { z } from 'zod';
+
+const gateway = new AIGatewayClient();
+const kv = new KeyValueClient();
+const TRIAGE_MODEL = 'googleai/gemini-3-flash-preview';
+
+const triageSchema = z.object({
+  priority: z.enum(['low', 'normal', 'high']),
+  summary: z.string(),
+});
+
+type TriageResult = z.infer<typeof triageSchema>;
+
+export async function triageMessage(
+  customerId: string,
+  message: string
+): Promise<TriageResult> {
+  const previous = await kv.get<TriageResult>('support-triage', customerId);
+
+  const { data } = await gateway.completeStructured({
+    model: TRIAGE_MODEL,
+    messages: [
+      {
+        role: 'system',
+        content: 'Classify support messages for a product engineering team.',
+      },
+      {
+        role: 'user',
+        content: [
+          `Customer message: ${message}`,
+          previous.exists ? `Previous summary: ${previous.data.summary}` : '',
+        ].filter(Boolean).join('\n\n'),
+      },
+    ],
+    response_schema: {
+      name: 'triage_result',
+      schema: triageSchema,
+    },
+  });
+
+  const output = triageSchema.parse(data);
+  await kv.set('support-triage', customerId, output, { ttl: 60 * 60 * 24 * 30 });
+  return output;
+}
+```
+
+Keep the route thin:
+
+```typescript
+import { triageMessage } from '@/lib/triage';
+import { z } from 'zod';
+
+const inputSchema = z.object({
+  customerId: z.string(),
+  message: z.string(),
+});
+
+export async function POST(request: Request): Promise<Response> {
+  const input = inputSchema.parse(await request.json());
+  const result = await triageMessage(input.customerId, input.message);
+  return Response.json(result);
+}
+```
+
+## Model Choice
+
+Use the live Gateway catalog before hardcoding model IDs:
+
+```bash
+agentuity cloud aigateway models --recommended
+agentuity cloud aigateway models --ids
+agentuity cloud aigateway models --provider openai
+```
+
+Use `AIGatewayClient` when model choice should be project configuration. Use a
+provider SDK or AI SDK provider when the feature depends on provider-specific
+APIs.
+
+| Need | Use |
+|---|---|
+| Plain text response | `gateway.completeText()` |
+| Provider-agnostic JSON | `gateway.completeStructured()` plus validation |
+| Raw provider-shaped response | `gateway.complete()` |
+| SSE passthrough | `gateway.streamRequest()` |
+| Automatic tool loop | AI SDK or provider SDK |
+
+`AIGatewayClient` reads Agentuity project credentials from the environment. The
+model ID is app config, not an extra secret.
+
+## Chat and Streaming
+
+Use streaming when users should see output as it arrives. Store chat state
+explicitly, usually after the stream completes:
+
+```typescript
+import { AIGatewayClient } from '@agentuity/aigateway';
+import { KeyValueClient } from '@agentuity/keyvalue';
+
+interface ChatMessage {
+  role: 'user' | 'assistant';
+  content: string;
+}
+
+const gateway = new AIGatewayClient();
+const kv = new KeyValueClient();
+const DEFAULT_MODEL = 'deepseek/deepseek-v4-flash';
+
+export async function streamChat(
+  conversationId: string,
+  message: string
+): Promise<Response> {
+  const stored = await kv.get<ChatMessage[]>('chat-history', conversationId);
+  const history = stored.exists ? stored.data : [];
+  const next = [...history, { role: 'user' as const, content: message }];
+
+  const { stream } = await gateway.streamRequest({
+    path: '/',
+    body: { model: DEFAULT_MODEL, stream: true, messages: next },
+  });
+
+  return new Response(stream, {
+    headers: { 'content-type': 'text/event-stream' },
+  });
+}
+```
+
+If you need to persist the assistant turn, tee the stream and parse the copy in a
+background promise owned by your route or worker.
+
+## Tools
+
+Tools should be bounded app functions:
+
+| Good tool | Avoid |
+|---|---|
+| Read one KV or database record | Broad unbounded scans |
+| Create a small task or enqueue a job | Long-running work inside the model call |
+| Return compact typed data | Returning huge files or transcripts |
+| Propose a risky action for approval | Irreversible side effects without a gate |
+
+Use an idempotency key or stored approval record for side effects. Never let a
+model directly execute irreversible work without an app-owned decision boundary.
+
+## State and Memory
+
+State belongs to the app:
+
+| State need | Store |
+|---|---|
+| Browser session identity | Signed cookie or auth session |
+| Compact memory or preferences | Key-Value Storage |
+| Relational user data | Database |
+| Generated files or transcripts | Durable Streams or Object Storage |
+| Async job status | KV status record plus Queue |
+
+Validate data when reading from KV or databases. Old records, manual test data,
+and partial writes are normal production boundaries.
+
+## Common Mistakes
+
+| Mistake | Better approach |
+|---|---|
+| Putting model calls directly in UI components | Call a server route or server function |
+| Trusting structured model data as typed | Validate with Zod, Valibot, ArkType, or another schema library |
+| Storing full transcripts in KV forever | Store summaries or pointers; use DB or durable streams for large data |
+| Running long jobs inside a request | Enqueue work and return a status handle |
+| Hardcoding an unverified model ID | Read the Gateway catalog first |
+
+## Useful Docs
+
+- Agents: https://agentuity.dev/build/agents
+- AI Gateway: https://agentuity.dev/services/ai-gateway
+- Chat and streaming: https://agentuity.dev/build/agents/chat-and-streaming
+- Tool calling: https://agentuity.dev/build/agents/tool-calling
+- State and memory: https://agentuity.dev/build/agents/state-and-memory

package/skills/agentuity-background-work/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: agentuity-background-work
+description: >-
+  Use when adding async jobs, queue workers, cron schedules, webhook ingestion,
+  task tracking, long-running workflows, status polling, durable output, or
+  idempotent background processing to an Agentuity app.
+license: Apache-2.0
+metadata:
+  author: agentuity
+  version: "1.0.0"
+---
+
+# Agentuity Background Work
+
+Use background work when a request starts something slow: report generation,
+webhook fan-out, email preparation, model evaluation, file processing, or
+external API retries. The common pattern is: enqueue work, return a handle,
+process asynchronously, and expose status.
+
+## Choose the Work Boundary
+
+| Need | Use |
+|---|---|
+| Async message handoff to a worker route | Queue |
+| Cron-style recurring call | Schedule |
+| External event ingestion | Webhook |
+| Human or agent-visible work item | Task |
+| Generated output that should survive the request | Durable Stream or Object Storage |
+| Bounded command execution | Sandbox |
+| Status for a client to poll | Key-Value Storage or database |
+
+Use sandbox execution for bounded commands or coding-agent runtimes. Do not use
+sandbox as the default replacement for queues, schedules, or webhooks.
+
+## Request, Worker, Status
+
+```bash
+npm install @agentuity/queue @agentuity/keyvalue @agentuity/stream zod
+```
+
+```typescript
+import { QueueClient } from '@agentuity/queue';
+import { KeyValueClient } from '@agentuity/keyvalue';
+import { StreamClient } from '@agentuity/stream';
+import { z } from 'zod';
+
+const queue = new QueueClient();
+const kv = new KeyValueClient();
+const streams = new StreamClient();
+
+const requestSchema = z.object({
+  accountId: z.string(),
+  reportMonth: z.string(),
+});
+
+const jobSchema = requestSchema.extend({
+  jobId: z.string(),
+});
+
+type ReportJob = z.infer<typeof jobSchema>;
+
+type ReportStatus =
+  | { readonly kind: 'queued'; readonly messageId: string }
+  | { readonly kind: 'processing' }
+  | { readonly kind: 'done'; readonly streamUrl: string }
+  | { readonly kind: 'failed'; readonly message: string };
+```
+
+Request route:
+
+```typescript
+export async function POST(request: Request): Promise<Response> {
+  const input = requestSchema.parse(await request.json());
+  const jobId = crypto.randomUUID();
+  const job: ReportJob = { jobId, ...input };
+
+  const message = await queue.publish('report-jobs', job, {
+    idempotencyKey: jobId,
+  });
+
+  await kv.set<ReportStatus>('report-status', jobId, {
+    kind: 'queued',
+    messageId: message.id,
+  });
+
+  return Response.json({ jobId, statusUrl: `/api/reports/${jobId}` }, { status: 202 });
+}
+```
+
+Status route:
+
+```typescript
+export async function getReportStatus(jobId: string): Promise<Response> {
+  const result = await kv.get<ReportStatus>('report-status', jobId);
+
+  if (!result.exists) {
+    return Response.json({ error: 'Report job not found' }, { status: 404 });
+  }
+
+  return Response.json(result.data);
+}
+```
+
+Worker function:
+
+```typescript
+export async function processReportJob(body: unknown): Promise<Response> {
+  const job = jobSchema.parse(body);
+
+  await kv.set<ReportStatus>('report-status', job.jobId, { kind: 'processing' });
+
+  try {
+    const stream = await streams.create('monthly-reports', {
+      contentType: 'text/csv',
+      metadata: {
+        accountId: job.accountId,
+        reportMonth: job.reportMonth,
+      },
+      ttl: 60 * 60 * 24 * 90,
+    });
+
+    try {
+      await stream.write('account_id,report_month,total\n');
+      await stream.write(`${job.accountId},${job.reportMonth},42817\n`);
+    } finally {
+      await stream.close();
+    }
+
+    await kv.set<ReportStatus>('report-status', job.jobId, {
+      kind: 'done',
+      streamUrl: stream.url,
+    });
+
+    return Response.json({ ok: true });
+  } catch (error) {
+    await kv.set<ReportStatus>('report-status', job.jobId, {
+      kind: 'failed',
+      message: error instanceof Error ? error.message : 'Report generation failed',
+    });
+
+    return Response.json({ ok: false }, { status: 500 });
+  }
+}
+```
+
+## Queue Destinations
+
+Create the queue and HTTP destination from the CLI:
+
+```bash
+agentuity cloud queue create report-jobs --max-retries 3 --visibility-timeout 120
+agentuity cloud queue destinations create report-jobs \
+  --type http \
+  --name report-worker \
+  --url https://<your-app-host>/api/workers/report-jobs
+```
+
+The platform only calls your worker route when a destination points at a
+reachable public URL. `localhost` is not reachable from the queue service; use a
+public tunnel during local testing or the deployed app URL.
+
+## Schedules
+
+Use schedules for recurring HTTP calls or sandbox destinations:
+
+```bash
+agentuity cloud schedule create nightly-report \
+  --cron "0 2 * * *" \
+  --url https://<your-app-host>/api/workers/nightly-report
+```
+
+Keep schedule handlers idempotent. A retry should not duplicate emails, charges, or external writes.
+
+## Webhooks
+
+Use webhooks for external event ingestion. Validate signatures or shared secrets
+in the route before publishing follow-up work to a queue.
+
+```typescript
+export async function handleWebhook(request: Request): Promise<Response> {
+  const event = await request.json();
+  const eventId = String(event.id ?? crypto.randomUUID());
+
+  await queue.publish('webhook-events', event, {
+    idempotencyKey: eventId,
+  });
+
+  return Response.json({ accepted: true }, { status: 202 });
+}
+```
+
+## Tasks
+
+Use tasks when work should be visible as a trackable item for humans or agentic tools:
+
+```typescript
+import { TaskClient } from '@agentuity/task';
+
+const tasks = new TaskClient();
+
+await tasks.create({
+  title: 'Review monthly report',
+  description: 'Validate generated totals before customer delivery.',
+  tags: ['reporting'],
+});
+```
+
+## Common Mistakes
+
+| Mistake | Better approach |
+|---|---|
+| Doing slow work before responding to the user | Enqueue and return `202 Accepted` with a status URL |
+| Publishing without an idempotency key | Use a stable job ID or upstream event ID |
+| Assuming queue workers can call `localhost` | Configure a public tunnel or deployed app URL |
+| Losing job status after retries | Persist status after each durable step |
+| Using one queue for unrelated workloads | Separate queues by retry policy and destination |
+
+## Useful Docs
+
+- Background work: https://agentuity.dev/build/apps-and-apis/background-work
+- Queues: https://agentuity.dev/services/queues
+- Schedules: https://agentuity.dev/services/schedules
+- Webhooks: https://agentuity.dev/services/webhooks
+- Tasks: https://agentuity.dev/services/tasks
+- Durable Streams: https://agentuity.dev/services/storage/durable-streams

package/skills/agentuity-cli/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: agentuity-cli
+description: >-
+  Use when working with the Agentuity CLI itself: installation, authentication,
+  profiles, JSON output, command discovery, schema inspection, non-interactive
+  automation, structured input, and deciding which Agentuity command family to
+  use.
+license: Apache-2.0
+metadata:
+  author: agentuity
+  version: "1.0.0"
+---
+
+# Agentuity CLI
+
+The `agentuity` CLI manages project setup, local development, deploys, cloud
+resources, auth, profiles, and agent-friendly command schemas. When unsure about
+flags or response shapes, ask the CLI instead of guessing.
+
+## First Checks
+
+```bash
+agentuity --version
+agentuity auth whoami
+agentuity --help
+```
+
+If the user is not authenticated:
+
+```bash
+agentuity auth login
+```
+
+Headless environments should use documented API-key environment variables or a
+configured profile. A first-class API-key login flow is tracked as an SDK issue;
+do not invent unsupported auth commands.
+
+## Command Discovery
+
+Use these before guessing flags:
+
+```bash
+agentuity <command> --help
+agentuity --help json
+agentuity ai schema show
+agentuity ai capabilities show
+agentuity ai intro
+```
+
+Per-command schema:
+
+```bash
+agentuity cloud deployment logs --describe
+agentuity project import --describe
+```
+
+The CLI schema is useful for agentic tools because commands declare arguments, options, tags, and response shapes.
+
+## JSON and Structured Input
+
+Use `--json` for machine-readable output:
+
+```bash
+agentuity --json project show
+agentuity --json cloud deployment list
+agentuity --json cloud session list --success=false --count=25
+```
+
+Use `--fields` to reduce output:
+
+```bash
+agentuity --json --fields id,name,region project list
+```
+
+Use `--input` when building commands programmatically:
+
+```bash
+agentuity --input '{"name":"my-app","framework":"nextjs","confirm":true}' project create
+```
+
+Use `--validate` with `--input` to check shape without executing when the command supports validation:
+
+```bash
+agentuity --validate --input '{"name":"my-app"}' project import
+```
+
+## Command Families
+
+| Need | Command family | Skill |
+|---|---|---|
+| Create/import/run/build/deploy an app | `project`, `dev`, `build`, `deploy` | `agentuity-project` |
+| Manage deployments, logs, env, resources, SSH | `cloud` | `agentuity-cloud` |
+| Use service clients from app code | package installs | `agentuity-services` |
+| Build model-backed features | AI Gateway and provider SDK commands | `agentuity-ai` |
+| Add relational data | `cloud db`, `project add database` | `agentuity-database` |
+| Add async work | `cloud queue`, `cloud schedule`, `cloud webhook`, `cloud task` | `agentuity-background-work` |
+| Manage cloud coding sessions | `coder` | Agentuity Coder docs |
+
+## Auth and Profiles
+
+Useful auth commands:
+
+```bash
+agentuity auth login
+agentuity auth logout
+agentuity auth whoami
+agentuity auth org select
+agentuity auth ssh add --file ~/.ssh/id_rsa.pub
+```
+
+Profiles let users switch account, org, and region context:
+
+```bash
+agentuity profile list
+agentuity profile use <name>
+```
+
+If profile commands do not appear in normal help, use the docs and
+`agentuity ai schema show` to inspect current support. Profile discoverability is
+tracked as an SDK issue under the `agentic flow` label.
+
+## Non-Interactive Automation
+
+For CI and autonomous agents:
+
+```bash
+agentuity --json project show
+agentuity project import --name my-app --org-id <org-id> --confirm
+agentuity deploy --json --message "Automated deploy"
+```
+
+Prefer explicit context:
+
+| Context | Prefer |
+|---|---|
+| Project | run from the app directory or pass `--dir` / `--project-id` |
+| Organization | pass `--org-id` or select it in auth/profile setup |
+| Region | pass `--region` or select one before automation |
+| Destructive commands | pass `--force` or `--confirm` when supported |
+
+The CLI has strong JSON support, but a few command gaps remain. Use bounded
+polling and explicit timeouts when waiting for deployments or logs.
+
+## Error Handling
+
+Use JSON error output in scripts:
+
+```bash
+agentuity --json --error-format json project show
+```
+
+If a command fails:
+
+1. Re-run with `--help` to verify flags.
+2. Re-run with `--describe` to inspect schema.
+3. Add `--json` for structured output.
+4. Add explicit `--project-id`, `--org-id`, and `--region` if context resolution failed.
+5. For deploy/debug flows, switch to `agentuity-cloud`.
+
+## Common Mistakes
+
+| Mistake | Better approach |
+|---|---|
+| Guessing CLI flags from memory | Run `agentuity <command> --help` or `--describe` |
+| Parsing human tables in automation | Use `--json` and `--fields` |
+| Relying on implicit org/region in CI | Pass `--org-id`, `--region`, and project context explicitly |
+| Assuming every prompt is safe in non-TTY | Use explicit confirm/force flags where available |
+| Teaching unsupported commands | Verify with help or schema output first |
+
+## Useful Docs
+
+- CLI reference: https://agentuity.dev/reference/cli
+- Getting started: https://agentuity.dev/reference/cli/getting-started
+- Profiles: https://agentuity.dev/reference/cli/profiles
+- Deployment: https://agentuity.dev/reference/cli/deployment
+- Debugging: https://agentuity.dev/reference/cli/debugging
+- AI commands: https://agentuity.dev/reference/cli/ai-commands