fix: validate and correct AI agent skill examples

docs/skills.md

@@ -4,7 +4,29 @@ This document describes the skill system for the a7 CLI. Skills are structured k
 
 ## Overview
 
-Skills are `SKILL.md` files stored in the `skills/` directory. Each skill provides domain-specific instructions, command patterns, and decision guidance for AI agents. The format is compatible with 39+ AI coding agents including Claude Code, OpenCode, Cursor, GitHub Copilot, and Windsurf.
+Skills are `SKILL.md` files stored in the `skills/` directory. Each skill provides domain-specific instructions, command patterns, and decision guidance for AI agents. The supported installation examples cover Claude Code, Codex, Cursor, and GitHub Copilot.
+
+Install the narrowest skill needed for the current task. Do not install the full
+collection by default: overlapping persona, recipe, and plugin guidance adds
+routing ambiguity and makes review and updates harder.
+
+## Install a Skill
+
+Preview the available skills, then copy one skill into the current project:
+
+```bash
+npx skills add api7/a7 --list
+npx skills add api7/a7 --skill a7-plugin-key-auth --agent codex --copy
+```
+
+Replace `codex` with `claude-code`, `cursor`, or `github-copilot`. Review the
+selected `SKILL.md` before use. Installation copies instructions only; it does
+not install `a7`, connect to API7 Gateway, or run gateway commands.
+
+Use a non-production gateway group and a narrowly scoped token for a first run.
+Ask the agent to inspect current resources, propose an exact change, wait for
+approval, apply only the approved change, verify the result, and retain a
+rollback path. Never put an access token in a prompt or committed file.
 
 ## Directory Structure
 
@@ -116,22 +138,23 @@ Every PR validates `skills/` with `scripts/validate-skills.sh`. The script check
 6. skill names are unique
 
 The E2E suite also contains static skill checks under `test/e2e/skills`.
-Those checks keep this document aligned with the actual `skills/` inventory and
-prevent references to known removed commands such as the old health and portal
-commands.
+Those checks keep this document aligned with the actual `skills/` inventory,
+reject known removed commands, and validate commands and long flags used in
+shell examples against the current a7 CLI help tree.
 
 Run locally:
 
 ```bash
 make validate-skills
+make test-skills
 ```
 
 ## Adding a New Skill
 
 1. Choose the skill type and name following the [taxonomy](#skill-taxonomy)
 2. Create the directory: `mkdir skills/<skill-name>`
 3. Create `skills/<skill-name>/SKILL.md` with frontmatter and body
-4. Run validation: `make validate-skills`
+4. Run validation: `make validate-skills test-skills`
 5. Update this document if adding a new skill type or category
 
 ## Current Inventory

docs/user-guide/gateway-group.md

@@ -47,15 +47,15 @@ Creates a new gateway group.
 
 | Flag | Short | Default | Description |
 |------|-------|---------|-------------|
-| `--name` | `-n` | | Name of the gateway group (required) |
-| `--desc` | `-d` | | Description |
+| `--name` | | | Name of the gateway group (required) |
+| `--description` | | | Description |
 | `--file` | `-f` | | Path to a configuration file |
 
 **Examples:**
 
 Create a gateway group via flags:
 ```bash
-a7 gateway-group create --name staging --desc "Staging environment"
+a7 gateway-group create --name staging --description "Staging environment"
 ```
 
 ### `a7 gateway-group update`
@@ -65,13 +65,13 @@ Updates an existing gateway group's configuration.
 | Flag | Short | Default | Description |
 |------|-------|---------|-------------|
 | `--name` | `-n` | | New name |
-| `--desc` | `-d` | | New description |
+| `--description` | | | New description |
 | `--file` | `-f` | | Path to a configuration file |
 
 **Examples:**
 
 ```bash
-a7 gateway-group update staging --desc "Updated staging description"
+a7 gateway-group update staging --description "Updated staging description"
 ```
 
 ### `a7 gateway-group delete`

skills/a7-persona-developer/SKILL.md

@@ -133,7 +133,7 @@ Run a local APISIX instance via Docker and test your routes using generic `a7` c
 Before pushing to the Dashboard, validate your config against the enterprise schema.
 
 ```bash
-a7 config validate -g dev-group -f my-api.yaml
+a7 config validate -f my-api.yaml
 ```
 
 ### 3. Sync to Dashboard
@@ -149,18 +149,17 @@ Use `debug trace` to see exactly which plugins are executed and how the URI is t
 
 ```bash
 # Trace a request with an API Key
-a7 debug trace -g dev-group \
-  --uri /v1/users/123 \
+a7 debug trace user-v1-get -g dev-group \
+  --path /v1/users/123 \
   --method GET \
-  --header "X-API-KEY: my-dev-key" \
-  --verbose
+  --header "X-API-KEY: my-dev-key"
 ```
 
 ### Live Log Streaming
 
 ```bash
-# Stream error logs for your specific group
-a7 debug logs -g dev-group --follow --level error
+# Stream logs from a specific API7 Gateway container
+a7 debug logs --container <gateway-container> --follow
 ```
 
 ## CI/CD Integration
@@ -185,7 +184,7 @@ Automate your API lifecycle using `a7` in your pipelines.
 | Exposing an API path | Create or update a service-backed route | `a7 route create -f route.yaml` |
 | Backend URI mismatch | Use `proxy-rewrite` | `a7 route update ...` |
 | Testing Canary version | Use `traffic-split` | `a7 route update ...` |
-| Auth failure (401) | Check Trace & Logs | `a7 debug trace` & `a7 debug logs` |
+| Auth failure (401) | Check Trace & Logs | `a7 debug trace <route-id>` & `a7 debug logs` |
 
 ## Best Practices
 
@@ -195,5 +194,5 @@ Automate your API lifecycle using `a7` in your pipelines.
 4. **Token Security**: Do not hardcode your `--token` in scripts; use environment variables or secrets.
 5. **Declarative Sync**: Prefer `a7 config sync` for complex multi-route deployments.
 6. **Documentation**: Always provide a description (`--desc`) for routes and services for colleagues.
-7. **Trace Verbosity**: Use `--verbose` in `debug trace` to inspect plugin input/output headers.
+7. **Trace Scope**: Send only the headers needed to reproduce the request, and redact credentials before sharing trace output.
 8. **Route Model**: Prefer `service create` plus `route create` with `service_id`; avoid standalone upstream workflows for API7 EE.

skills/a7-persona-operator/SKILL.md

@@ -83,7 +83,7 @@ a7 config dump -g finance-dept > finance-backup-$(date +%F).yaml
 a7 config diff -g finance-dept -f finance-infra.yaml
 
 # Validate enterprise plugin configuration before sync
-a7 config validate -g finance-dept -f updated-config.yaml
+a7 config validate -f updated-config.yaml
 ```
 
 ### 3. Enterprise Security & SSL
@@ -117,7 +117,7 @@ a7 config diff -g prod-group -f infra-v2.yaml
 a7 config sync -g prod-group -f infra-v2.yaml
 
 # 4. Verify traffic flow in Prod
-a7 debug trace -g prod-group --uri /v1/status
+a7 debug trace <route-id> -g prod-group --path /v1/status
 ```
 
 ### Emergency Rollback
@@ -136,10 +136,10 @@ a7 config sync -g prod-group -f last-good-backup.yaml
 
 ```bash
 # 1. Trace a request through a specific Gateway Group
-a7 debug trace -g customer-facing --uri /api/v1/checkout --method POST
+a7 debug trace <route-id> -g customer-facing --path /api/v1/checkout --method POST
 
-# 2. Follow real-time error logs for a Gateway Group
-a7 debug logs -g customer-facing --follow --level error
+# 2. Follow logs from a specific API7 Gateway container
+a7 debug logs --container <gateway-container> --follow
 
 # 3. Check for misconfigured Global Rules
 a7 global-rule list -g customer-facing --output json
@@ -149,7 +149,7 @@ a7 global-rule list -g customer-facing --output json
 
 ```bash
 # Check the execution time of plugins in the trace
-a7 debug trace -g api-internal --uri /heavy-endpoint --verbose
+a7 debug trace <route-id> -g api-internal --path /heavy-endpoint
 
 # List active routes and their hit counts (if metrics enabled)
 a7 route list -g api-internal --output wide

skills/a7-plugin-basic-auth/SKILL.md

@@ -65,33 +65,32 @@ EOF
 ### 2. Add basic-auth credential
 
 ```bash
-curl -k "https://$(a7 context current -o json | jq -r .server):7443/apisix/admin/consumers/alice/credentials" \
-  -X PUT \
-  -H "X-API-KEY: $(a7 context current -o json | jq -r .token)" \
-  -d '{
-    "id": "cred-alice-basic-auth",
-    "plugins": {
-      "basic-auth": {
-        "username": "alice",
-        "password": "alice-password-123"
-      }
-    }
-  }'
+a7 credential create cred-alice-basic-auth -g default \
+  --consumer alice \
+  --plugins-json '{"basic-auth":{"username":"alice","password":"alice-password-123"}}'
 ```
 
-### 3. Create a route with basic-auth enabled
+### 3. Create a service and route with basic-auth enabled
 
 ```bash
+a7 service create -g default -f - <<'EOF'
+{
+  "id": "basic-protected-service",
+  "name": "Basic protected service",
+  "upstream": {
+    "type": "roundrobin",
+    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
+  }
+}
+EOF
+
 a7 route create -g default -f - <<'EOF'
 {
   "id": "basic-protected",
-  "uri": "/api/*",
+  "paths": ["/api/*"],
+  "service_id": "basic-protected-service",
   "plugins": {
     "basic-auth": {}
-  },
-  "upstream": {
-    "type": "roundrobin",
-    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
   }
 }
 EOF

skills/a7-plugin-hmac-auth/SKILL.md

@@ -71,33 +71,32 @@ EOF
 ### 2. Add hmac-auth credential
 
 ```bash
-curl -k "https://$(a7 context current -o json | jq -r .server):7443/apisix/admin/consumers/alice/credentials" \
-  -X PUT \
-  -H "X-API-KEY: $(a7 context current -o json | jq -r .token)" \
-  -d '{
-    "id": "cred-alice-hmac",
-    "plugins": {
-      "hmac-auth": {
-        "key_id": "alice-key",
-        "secret_key": "alice-secret-key-value"
-      }
-    }
-  }'
+a7 credential create cred-alice-hmac -g default \
+  --consumer alice \
+  --plugins-json '{"hmac-auth":{"key_id":"alice-key","secret_key":"alice-secret-key-value"}}'
 ```
 
-### 3. Create a route with hmac-auth enabled
+### 3. Create a service and route with hmac-auth enabled
 
 ```bash
+a7 service create -g default -f - <<'EOF'
+{
+  "id": "hmac-protected-service",
+  "name": "HMAC protected service",
+  "upstream": {
+    "type": "roundrobin",
+    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
+  }
+}
+EOF
+
 a7 route create -g default -f - <<'EOF'
 {
   "id": "hmac-protected",
-  "uri": "/api/*",
+  "paths": ["/api/*"],
+  "service_id": "hmac-protected-service",
   "plugins": {
     "hmac-auth": {}
-  },
-  "upstream": {
-    "type": "roundrobin",
-    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
   }
 }
 EOF

skills/a7-plugin-http-logger/SKILL.md

@@ -116,10 +116,12 @@ EOF
 
 Apply a Global Rule to log all traffic in the `prod` group:
 
+Do not set an `id` in the create payload. The CLI derives the Global Rule ID
+from the plugin name.
+
 ```bash
-a7 global_rule create --gateway-group prod -f - <<'EOF'
+a7 global-rule create --gateway-group prod -f - <<'EOF'
 {
-  "id": "http-logger-global",
   "plugins": {
     "http-logger": {
       "uri": "http://log-collector:8080/global-logs",