diff --git a/README.md b/README.md
index 377ef10e..d775f4bd 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,16 @@ $ aio discover -i
 $ aio app --help
 ```
 
+## Agent skills
+
+Install [Agent Skills](https://agentskills.io/) for Cursor, Claude Code, Codex, and other agents:
+
+```bash
+npx skills add adobe/aio-cli-plugin-app
+```
+
+See [skills/README.md](skills/README.md) for the skill list and install options.
+
 # Commands
 
 <!-- commands -->
diff --git a/skills/README.md b/skills/README.md
new file mode 100644
index 00000000..18ca2a17
--- /dev/null
+++ b/skills/README.md
@@ -0,0 +1,39 @@
+# Agent skills for Adobe I/O CLI (`aio app`)
+
+These skills teach coding agents how to work with **App Builder** projects using the [`@adobe/aio-cli-plugin-app`](https://github.com/adobe/aio-cli-plugin-app) oclif plugin (`aio app` commands).
+
+## Install
+
+From any project (or globally):
+
+```bash
+# All skills, all supported agents (Cursor, Claude Code, Codex, etc.)
+npx skills add adobe/aio-cli-plugin-app
+
+# Cursor only, global user directory
+npx skills add adobe/aio-cli-plugin-app -a cursor -g
+
+# One skill
+npx skills add adobe/aio-cli-plugin-app -s aio-app-deploy
+
+# List skills without installing
+npx skills add adobe/aio-cli-plugin-app --list
+```
+
+Install locations depend on the agent (for example Cursor: `.cursor/skills/` or `~/.cursor/skills/` with `-g`). See [skills.sh](https://skills.sh) and [Agent Skills](https://agentskills.io/) for details.
+
+## Skills in this repo
+
+| Skill | Use when |
+|-------|----------|
+| [aio-cli-setup](aio-cli-setup/SKILL.md) | Installing CLI/plugin, login, linking Developer Console workspace |
+| [aio-app-scaffold](aio-app-scaffold/SKILL.md) | `aio app init`, `create`, `add`, project layout |
+| [aio-app-deploy](aio-app-deploy/SKILL.md) | `build`, `deploy`, `run`, `undeploy`, deploy flags |
+| [aio-app-config](aio-app-config/SKILL.md) | `app.config.yaml`, extensions, actions, web assets, hooks |
+| [aio-app-debug](aio-app-debug/SKILL.md) | `logs`, `info`, `get-url`, `test`, common failures |
+
+## Prerequisites
+
+- Node.js **>= 20.5** (matches plugin `engines`)
+- Adobe I/O CLI: `npm install -g @adobe/aio-cli`
+- Plugin: `aio plugins:install @adobe/aio-cli-plugin-app` (or `aio discover -i`)
diff --git a/skills/aio-app-config/SKILL.md b/skills/aio-app-config/SKILL.md
new file mode 100644
index 00000000..b07f2208
--- /dev/null
+++ b/skills/aio-app-config/SKILL.md
@@ -0,0 +1,101 @@
+---
+name: aio-app-config
+description: >-
+  Explains App Builder app.config.yaml, ext.config.yaml, Runtime manifests, actions,
+  web assets, hooks, and extension points for aio-cli-plugin-app. Use when editing
+  deploy manifests, adding actions, or configuring frontends and events.
+---
+
+# App configuration (`app.config.yaml`)
+
+Validation schemas live in the plugin repo: `schema/config.schema.json`, `schema/deploy.yaml.schema.json`.
+
+## Standalone application
+
+```yaml
+application:
+  actions: actions          # folder for action sources
+  web: web-src              # optional frontend root
+  runtimeManifest:
+    packages:
+      my-package:
+        license: Apache-2.0
+        actions:
+          my-action:
+            function: actions/my-action/index.js
+            web: 'yes'                    # HTTP-accessible
+            runtime: nodejs:22
+            inputs:
+              LOG_LEVEL: debug
+            annotations:
+              require-adobe-auth: false
+              final: true
+  hooks:
+    pre-app-build: node scripts/prebuild.js
+    post-app-deploy: node scripts/postdeploy.js
+```
+
+## Multi-extension app
+
+```yaml
+extensions:
+  dx/excshell/1:
+    $include: src/dx-excshell-1/ext.config.yaml
+```
+
+Extension `ext.config.yaml` typically defines:
+
+```yaml
+operations:
+  view:
+    - type: web
+      impl: index.html
+actions: ./actions
+web: ./web-src
+runtimeManifest:
+  packages:
+    ...
+```
+
+Use `aio app add extension` to add extension points; use `-e` on build/deploy/run to target one.
+
+## Web assets and CDN
+
+- Frontend lives under `web` / `web-src` path from config.
+- `aio app build` bundles to `dist`; `aio app deploy` uploads via `@adobe/aio-lib-web` (deploy-service CDN API).
+- `web` section can include `response-headers` rules (paths → `adp-*` metadata on upload).
+
+Requires valid `.env` / auth from `aio app use` (`ow.auth_handler` for bearer token).
+
+## Events
+
+Register event actions with `aio app add event`. Deploy with `--force-events` to sync registrations to config (can delete stray registrations).
+
+## Log forwarding
+
+```bash
+aio app config get log-forwarding
+aio app config set log-forwarding
+```
+
+Deploy runs log-forwarding update by default (`--no-log-forwarding-update` to skip).
+
+## Hooks (common)
+
+| Hook | When |
+|------|------|
+| `pre-app-build` / `post-app-build` | Around `aio app build` |
+| `pre-app-deploy` / `post-app-deploy` | Around deploy |
+| `deploy-static` | Replace default web deploy if script returns truthy |
+| `post-app-run` | After `aio app run` |
+
+Hook commands run in-process via `runInProcess` (see `src/lib/app-helper.js`).
+
+## Config validation
+
+Most commands default to `--config-validation`. Disable with `--no-config-validation` only when debugging broken YAML.
+
+## Related skills
+
+- Deploy commands: `aio-app-deploy`
+- Setup / `aio app use`: `aio-cli-setup`
diff --git a/skills/aio-app-debug/SKILL.md b/skills/aio-app-debug/SKILL.md
new file mode 100644
index 00000000..0df19e9a
--- /dev/null
+++ b/skills/aio-app-debug/SKILL.md
@@ -0,0 +1,78 @@
+---
+name: aio-app-debug
+description: >-
+  Debugs Adobe App Builder apps using aio app logs, info, get-url, and test.
+  Use when deployments fail, actions return errors, web assets missing, or
+  verifying Runtime/CDN URLs.
+---
+
+# Debug App Builder apps (`aio app`)
+
+## Quick checks
+
+```bash
+aio console where          # correct org / project / workspace?
+aio app info               # namespace, creds, manifest summary
+aio app info --json
+aio app get-url            # action web URLs after deploy
+aio app get-url --cdn
+```
+
+## Logs
+
+```bash
+aio app logs
+aio app logs --tail        # follow (alias: --watch, --poll)
+aio app logs -a my-pkg/my-action
+aio app logs -l 10         # last N activations (1–50)
+aio app logs --strip       # one line per activation
+```
+
+Use `-v` on any command for verbose plugin output.
+
+## Tests
+
+```bash
+aio app test               # unit tests (default)
+aio app test --e2e
+aio app test --all
+aio app test -a my-action
+aio app test -e <extension>
+```
+
+Extension `ext.config.yaml` may define a `test` hook script instead of default test runner.
+
+## Common failures
+
+| Symptom | Things to try |
+|---------|----------------|
+| First deploy 404/503 | `aio app clean && aio app deploy --force-deploy` |
+| `aio app` unknown | Install plugin: `aio plugins:install @adobe/aio-cli-plugin-app` |
+| Wrong namespace / creds | `aio console where` then `aio app use -g --overwrite` |
+| Production deploy blocked | App published on Exchange; use `--force-deploy` or retract in Exchange |
+| Web deploy auth error | Re-login; ensure `aio app use` refreshed `.env` |
+| Empty UI after first deploy | `web-src/src/config.json` empty until deploy; use runtime URL fallback (see scaffold docs) |
+| Multiple extensions on `run` | Pass `-e <extension-id>` |
+| Nothing to deploy | Pass `--actions` and/or `--web-assets` (both default true) |
+
+## Build vs deploy artifacts
+
+```bash
+aio app clean              # wipe dist/
+aio app build --force-build
+```
+
+If actions look stale, deploy always overwrites changed actions; use `--force-build` to rebuild everything.
+
+## Validate config only
+
+```bash
+aio app deploy --no-actions --no-web-assets   # not useful alone
+# Prefer fixing YAML against schema; use normal command with validation on
+```
+
+## Related skills
+
+- Deploy flags: `aio-app-deploy`
+- Config structure: `aio-app-config`
+- Setup: `aio-cli-setup`
diff --git a/skills/aio-app-deploy/SKILL.md b/skills/aio-app-deploy/SKILL.md
new file mode 100644
index 00000000..89f017db
--- /dev/null
+++ b/skills/aio-app-deploy/SKILL.md
@@ -0,0 +1,102 @@
+---
+name: aio-app-deploy
+description: >-
+  Builds, deploys, runs, and undeploys Adobe App Builder apps using aio app build,
+  deploy, run, and undeploy. Use when shipping actions or static web assets to
+  Adobe I/O Runtime and CDN, or running local dev.
+---
+
+# App lifecycle: build, deploy, run (`aio app`)
+
+## Standard workflow
+
+```bash
+# From app root (app.config.yaml present)
+aio app build
+aio app deploy
+```
+
+`deploy` runs **build** by default for changed actions/web assets. Force full rebuild:
+
+```bash
+aio app deploy --force-build
+```
+
+First deploy to a **new** project/workspace often fails (404/503). Retry:
+
+```bash
+aio app clean && aio app deploy --force-deploy
+```
+
+## Build
+
+```bash
+aio app build
+aio app build --no-web-assets      # actions only
+aio app build --no-actions         # web only
+aio app build -a my-pkg/my-action  # single action
+aio app build -e <extension>       # single extension point
+aio app build --web-optimize       # minify web assets
+```
+
+`aio app clean` removes `dist/` artifacts; next build is full.
+
+## Deploy
+
+```bash
+aio app deploy
+aio app deploy --no-publish        # skip Exchange publish (extension apps)
+aio app deploy --no-web-assets     # Runtime actions only
+aio app deploy --no-actions        # CDN static files only
+aio app deploy -a my-pkg/my-action # one action
+aio app deploy -e <extension>      # one extension
+aio app deploy --open              # open frontend URL after deploy
+aio app deploy --force-deploy      # Production workspace published on Exchange
+aio app deploy --force-publish     # replace published extension points
+```
+
+Deploy overwrites existing Runtime deployments for changed actions. Static web deploy clears namespace assets before upload (via `@adobe/aio-lib-web`).
+
+## Local development
+
+```bash
+aio app run
+aio app run --open
+aio app run --no-actions           # frontend only
+aio app run -e <extension>         # required if multiple extensions
+```
+
+There is **no** `aio app dev` command; use **`aio app run`**. Multi-extension apps error unless `-e` selects one extension.
+
+Hooks in config (e.g. `post-app-run`) can run scripts during `run`.
+
+## Undeploy
+
+```bash
+aio app undeploy
+aio app undeploy --no-web-assets
+aio app undeploy --no-actions
+aio app undeploy --force-unpublish
+```
+
+## Pack / install (distribution)
+
+```bash
+aio app pack [path] -o dist/app.zip
+aio app install <path-to-package>
+```
+
+## After deploy
+
+```bash
+aio app get-url              # action invoke URLs
+aio app get-url --cdn
+aio app logs
+aio app logs -a my-pkg/my-action --tail
+```
+
+## Related skills
+
+- Config / hooks: `aio-app-config`
+- Failures: `aio-app-debug`
+- CLI install: `aio-cli-setup`
diff --git a/skills/aio-app-scaffold/SKILL.md b/skills/aio-app-scaffold/SKILL.md
new file mode 100644
index 00000000..45f05cb8
--- /dev/null
+++ b/skills/aio-app-scaffold/SKILL.md
@@ -0,0 +1,82 @@
+---
+name: aio-app-scaffold
+description: >-
+  Scaffolds Adobe App Builder apps with aio app init, create, and add (actions,
+  web-assets, extensions, events). Use when creating a new I/O app, adding Runtime
+  actions, or generating project structure from templates.
+---
+
+# Scaffold App Builder apps (`aio app`)
+
+## Create a new app
+
+```bash
+# Interactive (templates, extensions, console login)
+aio app init [path]
+
+# Non-interactive standalone app (minimal prompts)
+aio app init --standalone-app --yes --no-login --linter none
+
+# From Developer Console export
+aio app init --import ./workspace.json
+
+# From GitHub quick-start (owner/repo/path)
+aio app init --repo adobe/generator-aio-app
+```
+
+`aio app create [path]` is similar but uses default parameters (less prompting than `init`).
+
+After scaffold, link credentials:
+
+```bash
+aio console where
+aio app use -g --no-input --overwrite
+```
+
+## Add components to an existing app
+
+```bash
+aio app add action          # Runtime action under configured actions folder
+aio app add web-assets      # web-src + frontend tooling
+aio app add extension       # extension point (e.g. Experience Cloud shell)
+aio app add event           # Adobe I/O Events action
+aio app add ci              # CI workflow files
+aio app add service         # subscribe workspace to services
+```
+
+Common flags: `-y` (defaults), `-e <extension>` (target extension), `--no-install` (skip npm).
+
+## Delete components
+
+```bash
+aio app delete action [pkg/name]
+aio app delete web-assets
+aio app delete extension -e <extension-id>
+```
+
+## Project layout (typical)
+
+| Path | Role |
+|------|------|
+| `app.config.yaml` | Root manifest: `application` and/or `extensions` |
+| `actions/` or per-ext `actions/` | Runtime action source |
+| `web-src/` | Frontend (if `web` / `web-assets` enabled) |
+| `src/<extension>/ext.config.yaml` | Extension-specific manifest (`$include` from root) |
+| `.env` | Runtime namespace, credentials (from `aio app use`) |
+| `.aio` | Console metadata |
+| `dist/` | Build output (actions zip, web bundles) |
+
+Standalone apps use top-level `application:` in `app.config.yaml`. Multi-extension apps add `extensions:` with `$include` to per-extension configs.
+
+## List what exists
+
+```bash
+aio app list
+aio app list extension
+```
+
+## Related skills
+
+- Setup: `aio-cli-setup`
+- Config schema: `aio-app-config`
+- Deploy after scaffold: `aio-app-deploy`
diff --git a/skills/aio-cli-setup/SKILL.md b/skills/aio-cli-setup/SKILL.md
new file mode 100644
index 00000000..cccc254e
--- /dev/null
+++ b/skills/aio-cli-setup/SKILL.md
@@ -0,0 +1,73 @@
+---
+name: aio-cli-setup
+description: >-
+  Installs and configures Adobe I/O CLI and the aio-cli-plugin-app plugin for App
+  Builder. Use when setting up aio, logging in, linking Developer Console org/project/workspace,
+  or running aio app use / aio console commands.
+---
+
+# Adobe I/O CLI setup (`aio app`)
+
+## Install CLI and plugin
+
+```bash
+npm install -g @adobe/aio-cli
+aio plugins:install @adobe/aio-cli-plugin-app
+# or discover all Adobe plugins:
+aio discover -i
+aio app --help
+```
+
+The `aio app` topic comes from **@adobe/aio-cli-plugin-app** (oclif). Without the plugin, `aio app` is unavailable.
+
+## Login and console context
+
+```bash
+aio login
+aio console org list
+aio console project list
+aio console project select <projectNameOrId>
+aio console workspace select Stage    # or Production
+aio console where                     # verify org / project / workspace
+```
+
+Always run `aio console where` before linking an app. Wrong global selection causes `aio app use` to wire the wrong workspace silently.
+
+## Link app to Developer Console
+
+From the app root (contains `app.config.yaml`):
+
+```bash
+# Use globally selected org/project/workspace → writes .env and .aio
+aio app use -g --no-input --overwrite
+
+# Or import a downloaded workspace JSON from developer.adobe.com/console
+aio app use ./path/to/workspace.json --overwrite
+
+# Merge instead of overwrite
+aio app use -g --merge
+```
+
+Flags worth knowing:
+
+| Flag | Purpose |
+|------|---------|
+| `-g, --global` | Use global console selection (no local file path) |
+| `-w, --workspace` | Pick workspace by name or id |
+| `--overwrite` / `--merge` | How to combine with existing `.env` / `.aio` |
+| `--no-service-sync` | Do not copy service subscriptions to new workspace |
+| `--use-jwt` | Prefer JWT creds when both JWT and OAuth S2S exist |
+
+## Inspect configuration
+
+```bash
+aio app info
+aio app info --json
+aio app info --mask          # hide secrets in output
+```
+
+## Related skills
+
+- Scaffold: `aio-app-scaffold`
+- Deploy: `aio-app-deploy`
+- Config files: `aio-app-config`