added skills for common app activities

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 -->

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`)

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`

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`

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`