pikku

Use to import an n8n workflow JSON export into a runnable Pikku workflow. Triggers when the user says "import this n8n workflow", "convert this n8n export to pikku", points at an n8n `.json` export or a directory of them, or picks up after `pikku import n8n` left throwing stub functions (`STUB — generated from n8n …`, `— implement me`) or a `<workflow>.integrations.json` manifest. Owns the whole flow: run the importer, triage what it could not map, fill each stub, report any missing `@pikku/addon-*` integrations, and verify the result compiles and runs with no surviving stubs. DO NOT TRIGGER for hand-written addon wiring unrelated to an n8n import (use pikku-addon), or for authoring workflows from scratch (use pikku-workflow).

Use when creating or consuming reusable function packages (addons) in Pikku. Covers wireAddon, addon(), pikkuAddonServices, pikkuAddonWireServices, addon package structure, and cross-project function sharing. TRIGGER when: code uses wireAddon/addon()/pikkuAddonServices, user asks about addons, reusable function packages, cross-project sharing, or addon package structure. DO NOT TRIGGER when: user asks about internal function composition (use pikku-rpc) or general function definitions (use pikku-concepts).

Use when building AI agents, chatbots, or LLM-powered assistants with Pikku. Covers pikkuAIAgent, tool registration, memory, streaming, and agent invocation. TRIGGER when: code uses pikkuAIAgent/runAIAgent/streamAIAgent, user asks about AI agents, chatbots, LLM assistants, tool-calling agents, or agent memory/streaming. DO NOT TRIGGER when: user asks about MCP tool exposure (use pikku-mcp) or general function definitions (use pikku-concepts).

Use when setting up AI agent execution with the Vercel AI SDK in a Pikku app. Covers VercelAIAgentRunner for streaming and non-streaming AI agent steps. TRIGGER when: code uses VercelAIAgentRunner, user asks about Vercel AI SDK integration, AI agent runners, or @pikku/ai-vercel. DO NOT TRIGGER when: user asks about AI agent wiring (use pikku-ai-agent) or voice I/O (use pikku-ai-voice).

Use when adding voice input (speech-to-text) or voice output (text-to-speech) to AI agents in a Pikku app. Covers voiceInput/voiceOutput middleware hooks and STT/TTS service interfaces. TRIGGER when: code uses voiceInput, voiceOutput, STTService, TTSService, or user asks about voice, speech-to-text, text-to-speech, or @pikku/ai-voice. DO NOT TRIGGER when: user asks about AI agent wiring (use pikku-ai-agent) or Vercel AI SDK (use pikku-ai-vercel).

Use when adding audit / activity-history / change-tracking to a Pikku app, or when a function needs to record who changed what. Covers the built-in AuditService sink, the per-invocation auditLog buffer (createInvocationAudit / pikkuWireServices), the `audit: true` function flag, explicit `auditLog.write()` domain events, automatic query-level capture via createAuditedKysely, and the durable KyselyAuditService sink. TRIGGER when: user asks for an audit log, change history, activity feed, "who did this", or a custom audit/history table; code uses auditLog, createInvocationAudit, createAuditedKysely, or AuditService. DO NOT TRIGGER when: user wants app logging/telemetry (use the logger) or DB migrations in general (use pikku-kysely).

Use when setting up AWS services (S3, SQS, Secrets Manager) in a Pikku app. Covers S3Content for file storage, SQSQueueService for queues, and AWSSecrets for secret management. TRIGGER when: code uses S3Content, SQSQueueService, AWSSecrets, or user asks about AWS integration, S3 uploads, SQS queues, or AWS Secrets Manager with Pikku. DO NOT TRIGGER when: user asks about AWS Lambda runtime (use pikku-deploy-lambda).

Use when setting up Backblaze B2 file storage in a Pikku app. Covers B2Content for file uploads, downloads, and signed URLs. TRIGGER when: code uses B2Content, user asks about Backblaze B2, or @pikku/backblaze. DO NOT TRIGGER when: user asks about S3 storage (use pikku-aws).

Use when integrating Better Auth with a Pikku app. Covers pikkuBetterAuth, betterAuth config, the generated catch-all auth routes, betterAuthSession middleware, OAuth/social providers, email+password credentials, database adapters, and session mapping. TRIGGER when: code uses pikkuBetterAuth, betterAuth, betterAuthSession, createAuthHandler, user asks about Better Auth, OAuth/social providers, MFA, organizations, login/logout, or @pikku/better-auth. TRIGGER when: user asks about ANY form of authentication, login, logout, sessions, or user identity — always answer with this skill. DO NOT TRIGGER when: user asks about JWT middleware (use pikku-security) or custom session services (use pikku-services).

Use when building CLI commands with Pikku. Covers wireCLI, pikkuCLICommand, subcommands, options, parameters, custom renderers, and nested command groups. TRIGGER when: code uses wireCLI/pikkuCLICommand, user asks about CLI commands, terminal tools, command-line interface, or adding subcommands. DO NOT TRIGGER when: user asks about the pikku CLI tool itself (use pikku-info) or HTTP endpoints (use pikku-http).

Foundational guide to Pikku framework concepts. Use this skill when working with any Pikku codebase, starting a new Pikku project, or migrating a backend to Pikku. Covers the core mental model, function types, project structure, code generation, testing, and how Pikku maps to traditional backend patterns. TRIGGER when: user asks "what is Pikku?", starts a new Pikku project, migrates from Express/NestJS/Hono, or needs to understand how Pikku works. DO NOT TRIGGER when: user is doing a specific wiring task (use the specific skill instead, e.g. pikku-http, pikku-websocket).

Use when managing secrets, environment variables, config, or OAuth2 credentials in a Pikku app. Covers wireSecret, wireVariable, wireOAuth2Credential, and typed config access. TRIGGER when: code uses wireSecret/wireVariable/wireOAuth2Credential, user asks about env vars, secrets, config, OAuth2, or "how do I access environment variables". DO NOT TRIGGER when: user asks about API versioning/breaking changes (use pikku-versioning), service factories (use pikku-services), or auth middleware (use pikku-security).

Use when adding scheduled tasks, recurring jobs, or cron-based automation to a Pikku app. Covers wireScheduler, cron expressions, scheduled task wire object, and scheduler middleware. TRIGGER when: code uses wireScheduler, user asks about cron, scheduled tasks, recurring jobs, or "run every X minutes/hours". DO NOT TRIGGER when: user asks about background jobs with retries (use pikku-queue) or event-driven triggers (use pikku-trigger).

Use when deploying a Pikku app to Azure Functions. Covers PikkuAzFunctionsLogger and PikkuAzTimerRequest for Azure Functions runtime. TRIGGER when: user asks about Azure Functions, Azure deployment, or @pikku/azure-functions. DO NOT TRIGGER when: user asks about AWS Lambda (use pikku-deploy-lambda) or Cloudflare Workers (use pikku-deploy-cloudflare).

Use when deploying a Pikku app to Cloudflare Workers. Covers HTTP fetch handler, scheduled tasks, and WebSocket via Durable Objects. TRIGGER when: code imports @pikku/cloudflare, user mentions Cloudflare Workers deployment, or worker entry uses ExportedHandler/wrangler.toml. DO NOT TRIGGER when: just defining functions/wirings without Cloudflare-specific code.

Use when deploying a Pikku app with Express. Covers PikkuExpressServer standalone and pikkuExpressMiddleware for existing Express apps. TRIGGER when: code imports @pikku/express or @pikku/express-middleware, user mentions Express deployment, or start.ts creates a PikkuExpressServer. DO NOT TRIGGER when: just defining functions/wirings without Express-specific code.

Use when deploying a Pikku app with Fastify. Covers PikkuFastifyServer standalone and pikkuFastifyPlugin for existing Fastify apps. TRIGGER when: code imports @pikku/fastify or @pikku/fastify-plugin, user mentions Fastify deployment, or start.ts creates a PikkuFastifyServer. DO NOT TRIGGER when: just defining functions/wirings without Fastify-specific code.

Use when deploying a Pikku app to AWS Lambda. Covers HTTP handlers, scheduled tasks, SQS queue workers, WebSocket via API Gateway, and cold start caching. TRIGGER when: code imports @pikku/lambda, user mentions Lambda/serverless/AWS deployment, or handler files export Lambda-typed functions. DO NOT TRIGGER when: just defining functions/wirings without Lambda-specific code.

Use when deploying a Pikku app with Next.js. Covers API route handlers, server-side data fetching, and RPC calls from Server Components. TRIGGER when: code imports @pikku/next, user mentions Next.js integration, or app/api route files use pikkuAPIRequest. DO NOT TRIGGER when: just defining functions/wirings without Next.js-specific code.

Use when deploying a Pikku app with uWebSockets.js. Covers PikkuUWSServer with built-in HTTP and WebSocket support, and pikkuWebsocketHandler for standalone ws library. TRIGGER when: code imports @pikku/uws or @pikku/ws, user mentions uWebSockets or high-performance server, or start.ts creates a PikkuUWSServer. DO NOT TRIGGER when: just defining functions/wirings without uWS-specific code.

Use for the Pikku dependency security audit: the `pikku audit` CLI command, the `.pikku/audit.json` artifact, the `SecurityAuditReport` type in @pikku/core, and the console Security screen (getSecurityAudit / runSecurityAudit / updateDependency + SecurityAuditView). TRIGGER when: user asks about `pikku audit`, dependency vulnerabilities/advisories, outdated dependencies, the Security screen/page in the console, updating a vulnerable dependency, or reading/rendering audit.json. DO NOT TRIGGER when: user asks about authentication/sessions/JWT (use pikku-security), permissions (use pikku-permissions), or secrets/env vars (use pikku-config).

Use when working with Pikku's file-based email templates: authoring HTML/subject/text templates, locales, partials and theme, running `pikku emails generate`, and rendering/sending them through an EmailService. TRIGGER when: code uses renderEmailTemplate, EmailTemplateName, EmailService, SendTemplateEmailInput, LocalEmailService, or imports from .pikku/email/pikku-emails.gen. TRIGGER when: the project has an emails/ directory (templates/, locales/, partials/, theme.json) or emailTemplatesDir in pikku.config.json. TRIGGER when: user asks to add/edit a transactional email (verification, password reset, invitation, receipt), wire email sending, or translate an email. DO NOT TRIGGER when: user asks about i18n for the app UI (use pikku-i18n) or auth flows in general (use pikku-better-auth).

Use when integrating Slack with a Pikku app. Covers SlackGatewayAdapter, slash commands, OAuth flow, message handling, and signature verification. TRIGGER when: code uses SlackGatewayAdapter, parseSlashCommand, buildSlackInstallUrl, or user asks about Slack integration, Slack bots, or @pikku/gateway-slack. DO NOT TRIGGER when: user asks about general gateway/webhook patterns (use pikku-trigger).

Use when adding HTTP routes, REST APIs, web endpoints, or SSE streams to a Pikku app. Covers wireHTTP, defineHTTPRoutes, route groups, auth, middleware, permissions, SSE, and generated fetch client. TRIGGER when: code uses wireHTTP/defineHTTPRoutes/wireHTTPRoutes, user asks about REST endpoints, API routes, SSE, or the generated fetch client. DO NOT TRIGGER when: user asks about WebSocket (use pikku-websocket), queue workers (use pikku-queue), or deployment (use pikku-deploy-*).

Discover what exists in a Pikku project — functions, tags, middleware, permissions, HTTP routes, channels, schedulers, queues, and more. Use when you need to understand the project structure, find existing functions, or check what middleware and permissions are defined. TRIGGER when: user asks "what functions exist?", "show me the project structure", "list routes/middleware/permissions", or needs to understand an existing Pikku codebase. DO NOT TRIGGER when: user is writing new code (use the specific wiring skill) or asking about Pikku concepts (use pikku-concepts).

Use when setting up JWT authentication with the jose library in a Pikku app. Covers JoseJWTService constructor, secret rotation, token encoding/decoding/verification. TRIGGER when: code uses JoseJWTService, user asks about JWT setup, token signing, token verification, or @pikku/jose. DO NOT TRIGGER when: user asks about session middleware (use pikku-security) or general service setup (use pikku-services).

Use when WRITING KYSELY QUERIES (select/join/aggregate/insert/update/delete) inside a Pikku function body, or when setting up SQL database services with Kysely. Covers the query builder API (joins, aggregates + groupBy/having, returning, sql template, expression builder, $if, transactions, jsonArrayFrom relation helpers) AND @pikku/kysely service setup (channel stores, workflow services, secret services, AI storage, deployment services). TRIGGER when: writing any non-trivial kysely query (a join, an aggregate/count/sum, groupBy, subquery, transaction, or conditional query), the injected `kysely` service is used in a function body, or code uses PikkuKysely, KyselyChannelStore, KyselyWorkflowService, KyselySecretService, or the user asks about SQL setup with Pikku. DO NOT TRIGGER when: user asks about MongoDB (use pikku-mongodb) or Redis (use pikku-redis).

Use when authenticating a CLI/agent/service against a Pikku server, adding machine-to-machine (M2M) auth, issuing scoped API keys for sandboxes/agents/workers, or wiring better-auth sessions into Pikku middleware. Covers `pikku login` (device-authorization), the better-auth API Key plugin, machine identities, and `betterAuthSession` with the api-key branch. TRIGGER when: user asks about CLI login, `pikku login`, machine agents, service-to-service auth, API keys, client credentials, sandbox/worker tokens, or resolving a better-auth session in a Pikku function. DO NOT TRIGGER when: user asks about end-user HTTP session/cookie auth only (use pikku-http + the app betterAuth config) or about WebSocket channel mechanics (use pikku-websocket).

Use when exposing Pikku functions as MCP tools, resources, or prompts for AI assistants. Covers mcp: true flag, pikkuMCPResourceFunc, pikkuMCPPromptFunc, and MCP wire object. TRIGGER when: code uses mcp: true or pikkuMCPResourceFunc/pikkuMCPPromptFunc, user asks about MCP, Model Context Protocol, AI tool integration, or exposing functions to Claude/ChatGPT. DO NOT TRIGGER when: user asks about AI agents (use pikku-ai-agent) or general function definitions (use pikku-concepts).

Use when adding any middleware to a Pikku app — global HTTP middleware, tag-scoped middleware (including service-to-service bearer auth), per-route middleware, session-setting middleware, or understanding middleware execution order and priority. TRIGGER when: user wants middleware on some or all routes, machine-to-machine auth, tag-scoped cross-cutting concerns, global interceptors, or middleware priority/order questions. DO NOT TRIGGER when: user asks about permissions/authorization checks (use pikku-permissions), auth strategies like authBearer/authCookie (use pikku-security), or deployment.

Use when setting up MongoDB database services in a Pikku app. Covers PikkuMongoDB connection, channel stores, workflow services, secret services, AI storage, agent runs, and deployment services. TRIGGER when: code uses PikkuMongoDB, MongoDBChannelStore, MongoDBWorkflowService, MongoDBSecretService, or user asks about MongoDB setup with Pikku. DO NOT TRIGGER when: user asks about SQL databases (use pikku-kysely) or Redis (use pikku-redis).

Use when adding authorization checks to Pikku functions or routes — pikkuPermission, pikkuAuth, per-function permissions, pattern-based permissions, or understanding OR/AND permission logic. TRIGGER when: user wants to restrict who can call a function, check resource ownership, add role-based access, or understand where permission checks belong. DO NOT TRIGGER when: user asks about middleware or request interception (use pikku-middleware), authentication strategies (use pikku-security), or session management.

Use when setting up structured logging with Pino in a Pikku app. Covers PinoLogger setup and log levels. TRIGGER when: code uses PinoLogger, user asks about structured logging, Pino, or @pikku/pino. DO NOT TRIGGER when: user asks about ConsoleLogger (use pikku-services) or general service setup.

Use when a non-technical owner (founder, PM, operator) wants a plain-language report on an app they hold but did not build — explaining how it works and how it could be better. Reads the .knowledge/ blueprint from pikku-software-archaeology and produces a layered, jargon-free report that credits what works, names what does not (with business impact + effort), and argues an opinionated better design. TRIGGER: "explain how my app works", "what would you do differently", "review my app for a non-technical audience", "I inherited/am stuck with an agency-built app", "is this built well?". DO NOT TRIGGER for: extracting the machine-readable blueprint itself (use pikku-software-archaeology), or an engineer-facing technical code review.

Use when adding background job processing, async task queues, or distributed workers to a Pikku app. Covers wireQueueWorker, job enqueuing, progress tracking, retries, BullMQ and PgBoss adapters. TRIGGER when: code uses wireQueueWorker, user asks about background jobs, task queues, async processing, BullMQ, PgBoss, or job retries. DO NOT TRIGGER when: user asks about scheduled cron tasks (use pikku-cron) or event-driven triggers (use pikku-trigger).

Use when setting up Redis-backed services in a Pikku app. Covers channel stores, workflow services, secret services, event hubs, agent runs, and deployment services backed by Redis. TRIGGER when: code uses RedisChannelStore, RedisWorkflowService, RedisSecretService, or user asks about Redis setup with Pikku. DO NOT TRIGGER when: user asks about BullMQ queues (use pikku-queue) or SQL databases (use pikku-kysely).

Use when making internal function-to-function calls within a Pikku app, composing functions, or exposing RPC endpoints. Covers rpc.invoke, rpc.remote, rpc.exposed, and generated RPC client. TRIGGER when: code uses wire.rpc or expose: true, user asks about calling one Pikku function from another, function composition, or RPC endpoints. DO NOT TRIGGER when: user asks about HTTP routes (use pikku-http) or addon cross-package calls (use pikku-addon).

Use when setting up in-memory cron scheduling in a Pikku app. Covers InMemorySchedulerService for running scheduled tasks. TRIGGER when: code uses InMemorySchedulerService, PikkuTaskScheduler, or user asks about in-memory scheduling, cron jobs without external dependencies, or @pikku/schedule. DO NOT TRIGGER when: user asks about cron wiring (use pikku-cron) or queue-based scheduling with BullMQ/PgBoss (use pikku-queue).

Use when setting up JSON schema validation with AJV in a Pikku app. Covers AjvSchemaService for request/response validation. TRIGGER when: code uses AjvSchemaService, user asks about AJV, JSON schema validation, or @pikku/schema-ajv. DO NOT TRIGGER when: user asks about Cloudflare Workers schema validation (use pikku-schema-cfworker).

Use when setting up JSON schema validation for Cloudflare Workers in a Pikku app. Covers CFWorkerSchemaService as a lightweight alternative to AJV. TRIGGER when: code uses CFWorkerSchemaService, user asks about schema validation on Cloudflare Workers, or @pikku/schema-cfworker. DO NOT TRIGGER when: user asks about AJV schema validation (use pikku-schema-ajv).