From ad5162e88b98f97af1ee0e8b9d84834339181182 Mon Sep 17 00:00:00 2001
From: Jesse MacFadyen <purplecabbage@gmail.com>
Date: Thu, 28 May 2026 11:38:26 -0700
Subject: [PATCH] added skills for common runtime activities

---
 README.md                                  |  42 ++++++
 skills/aio-runtime-actions/SKILL.md        | 129 +++++++++++++++++
 skills/aio-runtime-api/SKILL.md            | 134 ++++++++++++++++++
 skills/aio-runtime-debug/SKILL.md          | 132 +++++++++++++++++
 skills/aio-runtime-deploy/SKILL.md         | 157 +++++++++++++++++++++
 skills/aio-runtime-events/SKILL.md         | 155 ++++++++++++++++++++
 skills/aio-runtime-log-forwarding/SKILL.md | 102 +++++++++++++
 skills/aio-runtime-setup/SKILL.md          |  92 ++++++++++++
 8 files changed, 943 insertions(+)
 create mode 100644 skills/aio-runtime-actions/SKILL.md
 create mode 100644 skills/aio-runtime-api/SKILL.md
 create mode 100644 skills/aio-runtime-debug/SKILL.md
 create mode 100644 skills/aio-runtime-deploy/SKILL.md
 create mode 100644 skills/aio-runtime-events/SKILL.md
 create mode 100644 skills/aio-runtime-log-forwarding/SKILL.md
 create mode 100644 skills/aio-runtime-setup/SKILL.md

diff --git a/README.md b/README.md
index 6d781018..105aff9a 100644
--- a/README.md
+++ b/README.md
@@ -27,6 +27,7 @@ Adobe I/O Runtime plugin for the Adobe I/O CLI
 <!-- toc -->
 * [aio-cli-plugin-runtime](#aio-cli-plugin-runtime)
 * [Usage](#usage)
+* [Skills](#skills)
 * [Commands](#commands)
 <!-- tocstop -->
 
@@ -38,6 +39,47 @@ $ aio discover -i
 $ aio runtime --help
 ```
 
+# Skills
+
+This repository includes [agent skills](https://github.com/vercel-labs/skills) that teach coding agents (Cursor, Claude Code, Codex, and others) how to use `aio runtime` commands.
+
+Install all skills:
+
+```sh
+npx skills add adobe/aio-cli-plugin-runtime
+```
+
+Install a specific skill:
+
+```sh
+npx skills add adobe/aio-cli-plugin-runtime --skill aio-runtime-deploy
+```
+
+Target a specific agent:
+
+```sh
+npx skills add adobe/aio-cli-plugin-runtime -a cursor
+npx skills add adobe/aio-cli-plugin-runtime -a claude-code -a codex
+```
+
+Install globally (available in all projects):
+
+```sh
+npx skills add adobe/aio-cli-plugin-runtime --global
+```
+
+### Available skills
+
+| Skill | Description |
+|-------|-------------|
+| `aio-runtime-setup` | Plugin install, auth, namespace, and property configuration |
+| `aio-runtime-actions` | Create, update, invoke, and manage actions |
+| `aio-runtime-deploy` | Deploy from YAML manifests (sync, undeploy, report) |
+| `aio-runtime-debug` | Activations, logs, results, and troubleshooting |
+| `aio-runtime-events` | Triggers, rules, and action sequences |
+| `aio-runtime-api` | HTTP API routes and REST endpoints |
+| `aio-runtime-log-forwarding` | Log forwarding to Splunk, New Relic, Azure, and more |
+
 # Commands
 <!-- commands -->
 * [`aio runtime`](#aio-runtime)
diff --git a/skills/aio-runtime-actions/SKILL.md b/skills/aio-runtime-actions/SKILL.md
new file mode 100644
index 00000000..ea2a787d
--- /dev/null
+++ b/skills/aio-runtime-actions/SKILL.md
@@ -0,0 +1,129 @@
+---
+name: aio-runtime-actions
+description: >-
+  Create, update, invoke, and manage Adobe I/O Runtime actions via aio-cli.
+  Use when working with serverless actions, web actions, action parameters,
+  runtimes (nodejs:22), annotations, or aio runtime action commands.
+---
+
+# Runtime Actions
+
+Manage individual actions with `aio runtime action` (`aio rt action`).
+
+## Create or update
+
+```bash
+# Create from source file (kind inferred from extension)
+aio runtime action create mypkg/my-action actions/my-action/index.js \
+  --web true \
+  --kind nodejs:22 \
+  -p greeting "hello" \
+  -a final true \
+  -a require-adobe-auth false
+
+# Update existing action
+aio runtime action update mypkg/my-action actions/my-action/index.js --web true
+```
+
+### Supported runtimes (by file extension)
+
+| Extension | Kind |
+|-----------|------|
+| `.js` | `nodejs:default` |
+| `.ts` | `typescript:default` |
+| `.py` | `python:default` |
+| `.java` | `java:default` |
+| `.go` | `go:default` |
+
+Prefer explicit `--kind nodejs:22` (or current supported version) over default.
+
+### Web actions
+
+- `--web true` — JSON HTTP response (standard web action)
+- `--web raw` — raw HTTP (full control of status, headers, body)
+- `--web-secure true` — require whisk auth on the URL
+
+For App Builder UIs calling actions via `actionWebInvoke`, return JSON bodies — not binary Content-Type responses.
+
+### Annotations
+
+```bash
+-a final true                    # prevent further updates via CLI
+-a require-adobe-auth false      # public web action (App Builder)
+-a require-whisk-auth false       # no auth header required
+-a raw-http true                  # raw HTTP mode
+```
+
+Or load from file: `-A annotations.json`
+
+### Limits
+
+```bash
+-m 512          # memory MB (128–4096)
+-t 60000        # timeout ms (100–3600000)
+-l 10           # log size MB (0–10)
+-c 200          # concurrency (1–500)
+```
+
+## Invoke and inspect
+
+```bash
+# Blocking invoke, show result only
+aio runtime action invoke mypkg/my-action -r -p name "World"
+
+# From JSON param file
+aio runtime action invoke mypkg/my-action -P params.json -b
+
+# Get action URL (web actions)
+aio runtime action get mypkg/my-action -r
+
+# List actions in package
+aio runtime action list mypkg
+
+# Get action metadata (+ code if not zipped)
+aio runtime action get mypkg/my-action -c
+
+# Save deployed code locally
+aio runtime action get mypkg/my-action --save
+```
+
+## Action handler pattern (Node.js)
+
+```javascript
+async function main (params) {
+  return {
+    statusCode: 200,
+    body: { message: `Hello ${params.name}` }
+  }
+}
+exports.main = main
+```
+
+For raw HTTP web actions, return `{ statusCode, headers, body }` with appropriate Content-Type.
+
+## Sequences and copies
+
+```bash
+# Sequence action (comma-separated fully-qualified names)
+aio runtime action create mypkg/my-seq --sequence "mypkg/step1,mypkg/step2"
+
+# Copy from existing action
+aio runtime action create mypkg/new-action --copy mypkg/existing-action
+```
+
+## Delete
+
+```bash
+aio runtime action delete mypkg/my-action
+```
+
+## Quick reference
+
+| Task | Command |
+|------|---------|
+| List all actions | `aio runtime action list` |
+| Count actions | `aio runtime action list --count` |
+| JSON output | add `--json` to list/create/update |
+| Package-scoped list | `aio runtime action list <packagename>` |
+
+For manifest-based bulk deploy, use the **aio-runtime-deploy** skill.
diff --git a/skills/aio-runtime-api/SKILL.md b/skills/aio-runtime-api/SKILL.md
new file mode 100644
index 00000000..ef2320dd
--- /dev/null
+++ b/skills/aio-runtime-api/SKILL.md
@@ -0,0 +1,134 @@
+---
+name: aio-runtime-api
+description: >-
+  Create and manage Adobe I/O Runtime HTTP API routes via aio-cli. Use when
+  exposing actions as REST endpoints, configuring API base paths, swagger
+  config, or aio runtime api commands.
+---
+
+# Runtime API Routes
+
+Map HTTP paths and verbs to web actions. Commands: `aio runtime api` (aliases: `aio rt api`, `aio runtime route`).
+
+**Prerequisite**: Target actions must be **web actions** (`--web true` or `web: 'yes'` in manifest).
+
+## Create a route
+
+```bash
+# basepath / relpath / verb / action
+aio runtime api create /v1 /hello GET mypkg/hello-action
+
+# With response type
+aio runtime api create /v1 /data GET mypkg/data-action -r json
+# response types: html, http, json, text, svg
+```
+
+## Create from Swagger config
+
+```bash
+aio runtime api create -c api-config.json
+```
+
+Swagger JSON defines multiple routes at once. Use for complex APIs.
+
+## List and inspect
+
+```bash
+# All APIs
+aio runtime api list
+
+# Filter by base path
+aio runtime api list /v1
+
+# Get API details
+aio runtime api get my-api-name
+aio runtime api get /v1
+```
+
+## Delete routes
+
+```bash
+# Delete entire API (by name or base path)
+aio runtime api delete my-api-name
+
+# Delete specific route
+aio runtime api delete /v1 /hello GET
+```
+
+## Manifest-based API definition
+
+Deploy APIs with manifest:
+
+```yaml
+packages:
+  my-package:
+    version: 1.0
+    license: Apache-2.0
+    actions:
+      hello:
+        function: actions/hello.js
+        web: true
+      goodbye:
+        function: actions/goodbye.js
+        web: true
+    apis:
+      hello-world:        # API name
+        v1:                 # base path segment
+          hello:            # relpath segments
+            world:
+              hello:
+                method: GET
+      goodbye-world:
+        v1:
+          bye:
+            world:
+              goodbye:
+                method: DELETE
+```
+
+Deploy:
+
+```bash
+aio runtime deploy -m manifest.yaml
+```
+
+Resulting URLs follow pattern: `https://<namespace>.adobeioruntime.net/api/v1/web/<package>/<action>`
+
+For App Builder apps, action URLs are also available via:
+
+```bash
+aio app get-url
+```
+
+## Auth on API endpoints
+
+Control access via action annotations:
+
+```yaml
+annotations:
+  require-adobe-auth: true    # Adobe IMS token required
+  require-whisk-auth: true    # Namespace auth header required
+```
+
+Public endpoints:
+
+```yaml
+annotations:
+  require-adobe-auth: false
+  require-whisk-auth: false
+```
+
+## Quick reference
+
+| Task | Command |
+|------|---------|
+| List APIs | `aio runtime api list` |
+| JSON output | `aio runtime api list --json` |
+| Get action URL | `aio runtime action get pkg/action -r` |
+| Aliases | `aio rt api`, `aio runtime route` |
+
+## Troubleshooting
+
+- **404 on API route** — Confirm action is deployed as web action and route was created (`aio runtime api list`).
+- **401 Unauthorized** — Check `require-adobe-auth` / `require-whisk-auth` annotations.
+- **Wrong response format** — Set `-r json|html|text` on create, or return proper structure from raw web action.
diff --git a/skills/aio-runtime-debug/SKILL.md b/skills/aio-runtime-debug/SKILL.md
new file mode 100644
index 00000000..ca7688d8
--- /dev/null
+++ b/skills/aio-runtime-debug/SKILL.md
@@ -0,0 +1,132 @@
+---
+name: aio-runtime-debug
+description: >-
+  Debug Adobe I/O Runtime actions with activations, logs, and results via
+  aio-cli. Use when troubleshooting failed invocations, viewing activation
+  history, tailing logs, or aio runtime activation commands.
+---
+
+# Runtime Debug and Activations
+
+Every action invocation creates an **activation**. Use activation commands to inspect results and logs.
+
+## List recent activations
+
+```bash
+# All recent activations
+aio runtime activation list
+
+# Filter by action
+aio runtime activation list mypkg/my-action
+
+# Full details
+aio runtime activation list --full
+
+# Count only
+aio runtime activation list --count
+
+# Time range (milliseconds since epoch)
+aio runtime activation list --since 1700000000000
+```
+
+## Get activation details
+
+```bash
+# By activation ID
+aio runtime activation get <activationId>
+
+# Most recent activation
+aio runtime activation get --last
+
+# Logs only (stripped timestamps)
+aio runtime activation get <activationId> --logs
+```
+
+## Result and logs
+
+```bash
+# Result body from most recent activation
+aio runtime activation result --last
+
+# Logs from specific activation
+aio runtime activation logs <activationId>
+
+# Most recent logs
+aio runtime activation logs --last
+```
+
+## Tail logs (live)
+
+```bash
+# Tail logs for an action (continuous)
+aio runtime activation logs --action mypkg/my-action --tail
+
+# Watch mode (alias)
+aio runtime activation logs --action mypkg/my-action --watch
+
+# Poll continuously
+aio runtime activation logs --action mypkg/my-action --poll
+
+# Last N activations
+aio runtime activation logs --action mypkg/my-action --limit 10
+```
+
+## Manifest-scoped log fetching
+
+When working with deployed manifests:
+
+```bash
+# All actions in manifest
+aio runtime activation logs --manifest
+
+# Specific package in manifest
+aio runtime activation logs --package my-package
+
+# All deployed actions under a package
+aio runtime activation logs --deployed --package my-package
+```
+
+## Debug workflow
+
+1. **Reproduce** — invoke the action:
+   ```bash
+   aio runtime action invoke mypkg/my-action -r -p key value
+   ```
+
+2. **Check result** — if invoke fails or returns unexpected output:
+   ```bash
+   aio runtime activation result --last
+   ```
+
+3. **Read logs** — for stack traces and `console.log` output:
+   ```bash
+   aio runtime activation logs --last
+   ```
+
+4. **Inspect full activation** — for timing, status, error payload:
+   ```bash
+   aio runtime activation get --last
+   ```
+
+5. **Enable verbose CLI output** for API-level errors:
+   ```bash
+   aio runtime action invoke mypkg/my-action -r --verbose
+   ```
+
+## Aliases
+
+| Command | Aliases |
+|---------|---------|
+| `aio runtime activation logs` | `aio runtime log`, `aio rt logs` |
+| `aio runtime activation list` | `aio rt activations list` |
+
+## Common issues
+
+| Symptom | Check |
+|---------|-------|
+| Action timeout | `activation get --last` → look at `duration`; increase `-t` / `limits.timeout` |
+| 401/403 on web action | Annotations `require-adobe-auth`, `require-whisk-auth` |
+| Empty logs | Log size limit (`-l` / `limits.logSize`); activation may have failed before logging |
+| "Cannot find activation" | Activation expired; invoke again and use `--last` immediately |
+
+For log forwarding to external systems, see the **aio-runtime-log-forwarding** skill.
diff --git a/skills/aio-runtime-deploy/SKILL.md b/skills/aio-runtime-deploy/SKILL.md
new file mode 100644
index 00000000..352bd48d
--- /dev/null
+++ b/skills/aio-runtime-deploy/SKILL.md
@@ -0,0 +1,157 @@
+---
+name: aio-runtime-deploy
+description: >-
+  Deploy Adobe I/O Runtime packages from YAML manifests with aio-cli. Use when
+  writing manifest.yaml, deploying actions/packages/triggers/rules/sequences,
+  sync/undeploy/report, or aio runtime deploy commands.
+---
+
+# Runtime Deploy (Manifest YAML)
+
+Deploy multiple packages, actions, triggers, rules, sequences, and APIs from YAML manifests.
+
+## Basic deploy
+
+```bash
+aio runtime deploy -m manifest.yaml
+# or from directory containing manifest:
+aio runtime deploy
+```
+
+With deployment overrides (environment-specific trigger inputs):
+
+```bash
+aio runtime deploy -m manifest.yaml -d deployment.yaml
+```
+
+Pass runtime parameters at deploy time:
+
+```bash
+aio runtime deploy -m manifest.yaml --param API_KEY "$API_KEY"
+aio runtime deploy -m manifest.yaml -P params.json
+```
+
+## Manifest structure
+
+```yaml
+packages:
+  my-package:
+    version: 1.0
+    license: Apache-2.0
+    actions:
+      hello:
+        function: actions/hello/index.js
+        runtime: nodejs:22
+        web: 'yes'
+        inputs:
+          name: World
+        annotations:
+          final: true
+          require-adobe-auth: false
+    sequences:
+      my-sequence:
+        actions: hello,another-action
+    triggers:
+      my-trigger:
+        inputs:
+          event: created
+    rules:
+      my-rule:
+        trigger: my-trigger
+        action: hello
+    apis:
+      my-api:
+        v1:
+          hello:
+            hello:
+              method: GET
+```
+
+### Key fields
+
+| Field | Purpose |
+|-------|---------|
+| `function` | Path to `.js`, `.zip`, or other source |
+| `runtime` | e.g. `nodejs:22`, `python:default` |
+| `web` / `web-export` | `yes`, `no`, `raw` — expose as HTTP endpoint |
+| `inputs` | Default parameters (typed or simple key:value) |
+| `limits` | `memorySize`, `timeout`, `logSize` |
+| `annotations` | `final`, `require-adobe-auth`, `require-whisk-auth`, `raw-http` |
+| `sequences` | Comma-separated action names within package |
+| `rules` | Map trigger → action |
+
+Action names in rules/triggers are **package-local** unless fully qualified (`pkg/action`).
+
+## Deployment file (overrides)
+
+Separate environment config from manifest:
+
+```yaml
+# deployment.yaml
+project:
+  name: my-project
+  packages:
+    my-package:
+      triggers:
+        my-trigger:
+          inputs:
+            event: prod-created
+```
+
+## Sync vs deploy
+
+| Command | Behavior |
+|---------|----------|
+| `aio runtime deploy` | Deploy entities from manifest |
+| `aio runtime deploy sync` | Sync project — add/update/remove to match manifest |
+| `aio runtime deploy undeploy` | Remove deployed assets |
+| `aio runtime deploy report` | Preview changes before deploy |
+| `aio runtime deploy export` | Export runtime project back to manifest |
+
+```bash
+# Preview what will change
+aio runtime deploy report -m manifest.yaml -d deployment.yaml
+
+# Sync (requires project name in deployment file)
+aio runtime deploy sync -m manifest.yaml -d deployment.yaml
+
+# Undeploy
+aio runtime deploy undeploy -m manifest.yaml --projectname my-project
+```
+
+## App Builder vs standalone
+
+- **App Builder**: `aio app deploy` reads `app.config.yaml` and deploys the `runtimeManifest` section. Use `aio app` commands for full-stack apps.
+- **Standalone Runtime**: Use `aio runtime deploy -m manifest.yaml` directly with a hand-written manifest.
+
+## Common patterns
+
+**Zip deployment** — point `function` at a zip archive:
+
+```yaml
+actions:
+  bundled:
+    function: ./dist/action.zip
+```
+
+**Adobe IMS auth on web actions**:
+
+```yaml
+annotations:
+  require-adobe-auth: true
+web: 'yes'
+```
+
+**Parameter placeholders** — resolved from `--param` or `-P` at deploy:
+
+```yaml
+inputs:
+  apiKey: $API_KEY
+```
+
+## Troubleshooting
+
+- Run `aio runtime deploy report` first to catch missing actions in rules/sequences.
+- Rule action names must match deployed action names exactly.
+- Use `--verbose` for full OpenWhisk error details.
+- After auth issues, verify with `aio runtime property get --all`.
diff --git a/skills/aio-runtime-events/SKILL.md b/skills/aio-runtime-events/SKILL.md
new file mode 100644
index 00000000..ccab7b29
--- /dev/null
+++ b/skills/aio-runtime-events/SKILL.md
@@ -0,0 +1,155 @@
+---
+name: aio-runtime-events
+description: >-
+  Manage Adobe I/O Runtime triggers, rules, and action sequences via aio-cli.
+  Use when wiring event-driven actions, firing triggers, creating rules,
+  or composing multi-step sequences with aio runtime trigger/rule commands.
+---
+
+# Runtime Events (Triggers, Rules, Sequences)
+
+Event-driven workflows connect **triggers** → **rules** → **actions**. **Sequences** chain multiple actions.
+
+## Triggers
+
+```bash
+# Create trigger
+aio runtime trigger create my-trigger \
+  -p source "api" \
+  -p eventType "created"
+
+# Create with feed (scheduled or external feed action)
+aio runtime trigger create my-scheduled-trigger --feed mypkg/alarm-feed
+
+# Fire trigger (test event flow)
+aio runtime trigger fire my-trigger -p payload '{"id": 1}'
+
+# List / get / update / delete
+aio runtime trigger list
+aio runtime trigger get /namespace/my-trigger
+aio runtime trigger update my-trigger -p key value
+aio runtime trigger delete /namespace/my-trigger
+```
+
+Trigger paths use format `/NAMESPACE/NAME` for get/delete.
+
+## Rules
+
+Rules bind a trigger to an action:
+
+```bash
+# Create rule: when trigger fires, invoke action
+aio runtime rule create my-rule my-trigger mypkg/my-action
+
+# Enable / disable
+aio runtime rule enable my-rule
+aio runtime rule disable my-rule
+
+# Check status
+aio runtime rule status my-rule
+
+# List / get / update / delete
+aio runtime rule list
+aio runtime rule get my-rule
+aio runtime rule update my-rule my-trigger mypkg/other-action
+aio runtime rule delete my-rule
+```
+
+## Sequences
+
+Sequences invoke actions in order, passing output forward.
+
+### Via CLI
+
+```bash
+aio runtime action create mypkg/my-sequence \
+  --sequence "mypkg/step1,mypkg/step2,mypkg/step3"
+```
+
+### Via manifest
+
+```yaml
+packages:
+  my-package:
+    actions:
+      step1:
+        function: actions/step1.js
+      step2:
+        function: actions/step2.js
+        inputs:
+          data: {}    # receives output from previous step
+    sequences:
+      pipeline:
+        actions: step1, step2
+```
+
+Sequence action names are comma-separated, package-local unless fully qualified (`other-pkg/action`).
+
+## Manifest triggers and rules
+
+Deploy triggers/rules with manifest deploy:
+
+```yaml
+packages:
+  my-package:
+    actions:
+      handler:
+        function: actions/handler.js
+    triggers:
+      order-created:
+        inputs:
+          orderId: ""
+    rules:
+      on-order-created:
+        trigger: order-created
+        action: handler
+```
+
+Override trigger inputs per environment in `deployment.yaml`:
+
+```yaml
+project:
+  name: my-project
+  packages:
+    my-package:
+      triggers:
+        order-created:
+          inputs:
+            orderId: "prod-default"
+```
+
+Deploy:
+
+```bash
+aio runtime deploy -m manifest.yaml -d deployment.yaml
+```
+
+## Test event flow
+
+```bash
+# 1. Fire trigger
+aio runtime trigger fire order-created -p orderId "12345"
+
+# 2. Check activation from rule-invoked action
+aio runtime activation list my-package/handler
+aio runtime activation result --last
+```
+
+## Package management
+
+Triggers and rules belong to packages. Delete package recursively removes associated rules/triggers:
+
+```bash
+aio runtime package delete my-package --recursive
+```
+
+## Quick reference
+
+| Task | Command |
+|------|---------|
+| Inventory namespace | `aio runtime namespace get` |
+| List rules | `aio runtime rule list` |
+| List triggers | `aio runtime trigger list` |
+| JSON output | add `--json` |
+
+For bulk deploy of triggers/rules, prefer manifest deploy (**aio-runtime-deploy** skill).
diff --git a/skills/aio-runtime-log-forwarding/SKILL.md b/skills/aio-runtime-log-forwarding/SKILL.md
new file mode 100644
index 00000000..c1f0b343
--- /dev/null
+++ b/skills/aio-runtime-log-forwarding/SKILL.md
@@ -0,0 +1,102 @@
+---
+name: aio-runtime-log-forwarding
+description: >-
+  Configure Adobe I/O Runtime log forwarding to Splunk, New Relic, Azure Log
+  Analytics, or Adobe I/O Runtime via aio-cli. Use when setting up external
+  log destinations or troubleshooting log forwarding errors.
+---
+
+# Runtime Log Forwarding
+
+Forward activation logs from your namespace to external monitoring systems.
+
+Commands: `aio runtime namespace log-forwarding` (aliases: `aio rt ns lf`, `aio rt ns log-forwarding`).
+
+## Check current configuration
+
+```bash
+aio runtime namespace log-forwarding get
+
+# Check forwarding errors
+aio runtime namespace log-forwarding errors
+```
+
+## Adobe I/O Runtime (CLI-accessible logs)
+
+Store logs in Runtime so `aio runtime activation logs` works (default for many namespaces):
+
+```bash
+aio runtime namespace log-forwarding set adobe-io-runtime
+```
+
+## Splunk HEC
+
+```bash
+aio runtime namespace log-forwarding set splunk-hec \
+  --host splunk.example.com \
+  --port 8088 \
+  --index main \
+  --hec-token "$SPLUNK_HEC_TOKEN"
+```
+
+Never commit HEC tokens or shared keys to source control. Pass via env vars or secure prompts.
+
+## New Relic
+
+```bash
+aio runtime namespace log-forwarding set new-relic \
+  --base-uri https://log-api.newrelic.com/log/v1 \
+  --license-key "$NEW_RELIC_LICENSE_KEY"
+```
+
+## Azure Log Analytics
+
+```bash
+aio runtime namespace log-forwarding set azure-log-analytics \
+  --customer-id "$AZURE_CUSTOMER_ID" \
+  --shared-key "$AZURE_SHARED_KEY" \
+  --log-type AdobeRuntime
+```
+
+## Interactive setup
+
+```bash
+aio runtime namespace log-forwarding set
+```
+
+Prompts for destination type and credentials.
+
+## Verify forwarding works
+
+1. Configure destination (above).
+2. Invoke an action that logs output:
+   ```bash
+   aio runtime action invoke mypkg/my-action -r
+   ```
+3. Check for forwarding errors:
+   ```bash
+   aio runtime namespace log-forwarding errors
+   ```
+4. Confirm logs appear in the destination (Splunk, New Relic, etc.) or via CLI:
+   ```bash
+   aio runtime activation logs --last
+   ```
+
+## Aliases
+
+| Long | Short |
+|------|-------|
+| `aio runtime namespace log-forwarding` | `aio rt ns lf` |
+| `aio runtime namespace log-forwarding get` | `aio rt ns lf get` |
+| `aio runtime namespace log-forwarding set splunk-hec` | `aio rt ns lf set splunk-hec` |
+
+## Troubleshooting
+
+| Issue | Action |
+|-------|--------|
+| Logs missing in external system | Run `aio rt ns log-forwarding errors` |
+| Auth failures | Verify tokens/keys; rotate if expired |
+| CLI logs empty but forwarding set | Ensure destination is `adobe-io-runtime` for CLI access |
+| Wrong namespace | Run `aio runtime property get --namespace` first |
+
+For per-activation debugging without external forwarding, use the **aio-runtime-debug** skill.
diff --git a/skills/aio-runtime-setup/SKILL.md b/skills/aio-runtime-setup/SKILL.md
new file mode 100644
index 00000000..69e04e59
--- /dev/null
+++ b/skills/aio-runtime-setup/SKILL.md
@@ -0,0 +1,92 @@
+---
+name: aio-runtime-setup
+description: >-
+  Install and configure Adobe I/O Runtime via aio-cli. Use when setting up
+  @adobe/aio-cli-plugin-runtime, configuring WHISK_AUTH/APIHOST/NAMESPACE,
+  selecting namespaces, or troubleshooting "An AUTH key must be specified".
+---
+
+# Adobe I/O Runtime CLI Setup
+
+This skill covers the **runtime plugin** (`aio runtime` / `aio rt`). App Builder full-stack apps use `aio app` (separate plugin); see the app-builder skill for that workflow.
+
+## Install the plugin
+
+```bash
+aio plugins:install @adobe/aio-cli-plugin-runtime
+# or discover all Adobe plugins:
+aio discover -i
+```
+
+Verify:
+
+```bash
+aio runtime --help
+aio rt --help   # alias
+```
+
+## Authentication and namespace
+
+Runtime commands require **AUTH** (namespace auth key) and **APIHOST**. Resolution order (highest first):
+
+1. CLI flags: `-u` / `--auth`, `--apihost`
+2. Environment: `WHISK_AUTH`, `WHISK_APIHOST`, `WHISK_NAMESPACE`, `WHISK_APIVERSION`
+3. aio config: `runtime.auth`, `runtime.apihost`, `runtime.namespace`
+4. `~/.wskprops` (or path in `WSK_CONFIG_FILE`)
+
+Default apihost: `https://adobeioruntime.net`
+
+### App Builder projects (linked workspace)
+
+When a project is linked via `aio app use`, credentials are read from aio config automatically. Verify context:
+
+```bash
+aio console where
+aio runtime property get --all
+```
+
+### Standalone / direct Runtime access
+
+Set properties explicitly:
+
+```bash
+aio runtime property set --namespace <namespace>
+# AUTH and APIHOST typically come from Developer Console Runtime namespace credentials
+```
+
+Or export env vars before commands:
+
+```bash
+export WHISK_AUTH="<namespace-auth-key>"
+export WHISK_APIHOST="https://adobeioruntime.net"
+export WHISK_NAMESPACE="<namespace>"
+```
+
+## Common commands
+
+| Task | Command |
+|------|---------|
+| Show all properties | `aio runtime property get --all` |
+| Set namespace | `aio runtime property set --namespace <ns>` |
+| List namespaces | `aio runtime namespace list` |
+| Inventory namespace | `aio runtime namespace get` |
+| Verbose errors | add `--verbose` or `--debug '*'` |
+
+## Aliases
+
+| Long form | Short |
+|-----------|-------|
+| `aio runtime` | `aio rt` |
+| `aio runtime namespace` | `aio rt ns` |
+| `aio runtime package` | `aio rt pkg` |
+| `aio runtime property` | `aio rt prop` |
+
+## Troubleshooting
+
+**"An AUTH key must be specified"** — No valid auth found. Set `WHISK_AUTH`, run `aio runtime property set`, or link an App Builder project with `aio app use`.
+
+**"An API host must be specified"** — Set `WHISK_APIHOST` or `--apihost`.
+
+**Wrong namespace** — Check `aio runtime property get --namespace` and `aio console where` before deploy/invoke.
+
+**Certificate errors** — Use `-i` / `--insecure` only for local dev with self-signed certs.