Platformatic Watt Agent Skill

An Agent Skill for integrating and deploying Platformatic Watt in any Node.js project. Works with any skills-compatible agent: Claude Code, Cursor, GitHub Copilot, Gemini CLI, Junie, and more.

Also available as a Claude Code plugin with slash commands (/watt, /kafka).

Features

• Automatic Framework Detection: Detects Next.js, Nuxt, React Router, TanStack Start, Vite, Express, Fastify, Koa, Remix, Astro, NestJS, WordPress, Laravel, and PHP
• Release-Matched Guidance: Uses the locally installed wattpm skill for configuration, APIs, and supported workflows
• Deployment Automation: Generate Docker, Kubernetes, and cloud deployment configs
• Performance Optimization: Multi-worker SSR, distributed caching, Kubernetes tuning, CPU profiling with wattpm pprof, flamegraph generation with @platformatic/flame, and heap snapshots
• Kafka Integration: Event-driven microservices with kafka-hooks webhooks and migrations from KafkaJS or node-rdkafka (separate kafka skill)
• Scheduled Jobs: Cron-based task scheduling with retry support
• CMS Integration: Headless CMS webhooks and cache invalidation (Contentful, Sanity, Strapi)
• Observability: Logging (Pino), tracing (OpenTelemetry), metrics (Prometheus)

Installation

Any Skills-Compatible Agent

npx skills add platformatic/skills

Or clone the repository and point your agent at the skills/ directory:

git clone https://github.com/platformatic/skills.git

Claude Code

# As a plugin (enables slash commands)
claude --plugin-dir ./watt-skill

Skills

This repository contains three skills, each a standalone SKILL.md following the Agent Skills specification:

watt — Platformatic Watt Integration

Delegates to wattpm skill from the project's local installation. Watt workflows and references ship with that package, so guidance follows the installed release rather than this repository's default branch. The agent retrieves linked Markdown files with wattpm skill <file>, resolving links relative to the referring document within the bundle.

Requires Watt 3.74.0 or newer with the skill command. If the installed version is older than 3.74.0 or does not provide the command, the skill aborts the request without upgrading or substituting other documentation. For new projects, it establishes the target version before installation. It never implicitly downloads the latest major.

Capabilities: init, deploy (Docker/Kubernetes/cloud), migrate, enterprise multi-service setup, wattpm CLI guidance, scheduled jobs, CMS integration, observability.

kafka — Kafka Event-Driven Microservices

Sets up event-driven architectures with @platformatic/kafka and kafka-hooks.

Capabilities: producer/consumer setup, kafka-hooks webhooks, request/response patterns, consumer lag monitoring, OpenTelemetry tracing, KafkaJS migration, node-rdkafka migration.

workflow — Vercel Workflow SDK with @platformatic/world

Helps build applications that use the Vercel Workflow SDK against a self-hosted Platformatic Workflow Service via @platformatic/world.

Capabilities: install + env-var wiring, Next.js instrumentation.ts, generic Node world.start(), optional @platformatic/workflow-fastify plugin, authoring workflows and steps ('use workflow' / 'use step', retries, hooks, sleeps, streams), triggering runs, standalone build, troubleshooting.

Usage

Any skills-compatible agent will match these skills based on the description field in each SKILL.md and follow the workflow instructions. Just ask in natural language:

• "Add Watt to this Next.js project"
• "Generate a Dockerfile for my Watt app"
• "Deploy this to Kubernetes"
• "Set up Kafka hooks for this service"
• "Migrate from KafkaJS to @platformatic/kafka"
• "Migrate from node-rdkafka to @platformatic/kafka"
• "Create a multi-service enterprise setup"
• "Capture a CPU profile for my Watt app with pprof"
• "Generate a flamegraph with @platformatic/flame"
• "Take a heap snapshot for my Watt app"
• "Add the Vercel Workflow SDK to my Next.js app with @platformatic/world"
• "Wire @platformatic/workflow-fastify into my Fastify server"
• "How do I author a workflow with 'use workflow' and 'use step'?"

Claude Code Slash Commands

When loaded as a Claude Code plugin, the skills also expose slash commands with argument-based routing. These are Claude Code-specific and not part of the Agent Skills standard:

/watt                     # auto-detect and integrate
/watt init nextjs         # integrate with framework hint
/watt deploy docker       # generate Docker config
/watt deploy k8s          # generate Kubernetes manifests
/watt enterprise          # multi-service setup
/watt migrate             # migrate existing app
/watt cli                 # wattpm CLI reference
/watt status              # check Watt configuration health

/kafka                    # Kafka overview
/kafka hooks              # kafka-hooks webhooks
/kafka producer           # producer setup
/kafka consumer           # consumer setup
/kafka monitoring         # consumer lag monitoring
/kafka migrate kafkajs    # KafkaJS migration guide
/kafka migrate node-rdkafka  # node-rdkafka migration guide

/workflow                 # auto-detect and wire @platformatic/world
/workflow next            # Next.js instrumentation.ts setup
/workflow node            # generic Node setup with explicit world.start()
/workflow fastify         # set up @platformatic/workflow-fastify
/workflow author          # how to write 'use workflow' / 'use step' files
/workflow trigger         # how to call start() / resumeHook()
/workflow build           # workflow build --target standalone walkthrough
/workflow status          # check Workflow SDK configuration health

Supported Frameworks

The installed release's bundled instructions determine framework support and configuration. The following table lists framework detection signals; verify package compatibility against that release.

Framework	Package	Detection
Next.js	@platformatic/next	next.config.{js,ts,mjs}
Nuxt	@platformatic/nuxt	nuxt.config.{ts,js,mjs}
React Router	@platformatic/react-router	react-router.config.{ts,js}
TanStack Start	@platformatic/tanstack	@tanstack/react-start in dependencies
Vite	@platformatic/vite	vite.config.{js,ts,mjs} (fallback for Vite apps)
Remix	@platformatic/remix	remix.config.js
Astro	@platformatic/astro	astro.config.{mjs,ts}
Express	@platformatic/node	express in dependencies
Fastify	@platformatic/node	fastify in dependencies
Koa	@platformatic/node	koa in dependencies
NestJS	@platformatic/node	nest-cli.json or @nestjs/core
WordPress	@platformatic/php	wp-config.php
Laravel	@platformatic/php	artisan + composer.json
PHP	@platformatic/php	composer.json + public/index.php

Several frameworks build on Vite (React Router, TanStack Start, Remix, Astro) and ship a vite.config.*. Detection matches the specific framework first and falls back to @platformatic/vite only when no more specific signal is present.

Requirements

• Node.js: A version supported by the installed wattpm release
• Watt skill: A project-local wattpm installation with the skill command and an agent capable of executing local commands

Configuration Reference

Load the local wattpm skill output and follow its configuration references. Configuration formats, environment handling, Node.js requirements, and available commands depend on the installed release. See the Watt discovery skill for local CLI resolution and reference navigation.

Project Structure

watt-skill/
├── skills/
│   ├── watt/
│   │   └── SKILL.md             # Delegates to the project-local wattpm skill
│   ├── kafka/
│   │   ├── SKILL.md             # Kafka integration skill
│   │   └── references/
│   │       ├── kafka.md         # Kafka reference docs
│   │       ├── kafkajs-migration.md        # KafkaJS migration guide
│   │       └── node-rdkafka-migration.md   # node-rdkafka migration guide
│   └── workflow/
│       ├── SKILL.md             # Vercel Workflow SDK + @platformatic/world skill
│       └── references/
│           ├── world.md         # @platformatic/world adapter reference
│           ├── authoring.md     # 'use workflow' / 'use step' authoring guide
│           ├── fastify.md       # @platformatic/workflow-fastify plugin
│           └── troubleshooting.md          # common workflow pitfalls
├── agents/
│   └── watt-analyzer.md         # Project analysis sub-agent
├── commands/
│   └── watt-status.md           # Status check (Claude Code)
├── .claude-plugin/
│   └── plugin.json              # Claude Code plugin manifest
├── README.md
└── LICENSE

The skills/ directory follows the Agent Skills specification. The agents/, commands/, and .claude-plugin/ directories are Claude Code-specific extensions.

Development

Testing Locally

# With Claude Code
claude --plugin-dir /path/to/watt-skill

# Test skill invocation
/watt
/watt-status

For other agents, point your agent's skill configuration at the skills/ directory.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with your agent of choice
5. Submit a pull request

Troubleshooting

Use the troubleshooting references returned by the local wattpm skill. If the installation is missing or the command is unsupported, follow the discovery skill's fallback guidance.

Resources

• Platformatic Watt Documentation
• Watt 3 Announcement
• Agent Skills Standard — open format specification
• Skills.sh Directory — discover and install agent skills
• Claude Code Skills Guide — Claude Code-specific docs

License

Apache-2.0 - See LICENSE for details.

Support

• Issues: GitHub Issues
• Discord: Platformatic Community