fix: correct AI agent skills and add CLI example validation

.github/workflows/ci.yml

@@ -57,3 +57,10 @@ jobs:
 
       - name: Validate SKILL.md files
         run: ./scripts/validate-skills.sh
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Test skill examples
+        run: make test-skills

Makefile

@@ -1,4 +1,4 @@
-.PHONY: build test lint clean install help test-e2e docker-up docker-down validate-skills
+.PHONY: build test lint clean install help test-e2e docker-up docker-down validate-skills test-skills check
 
 # Build variables
 BINARY_NAME := a6
@@ -81,5 +81,9 @@ docker-down:
 validate-skills:
 	./scripts/validate-skills.sh
 
+## test-skills: Validate commands and flags used in skill shell examples
+test-skills:
+	go test ./test/skills -count=1
+
 ## check: Run all checks (fmt, vet, lint, test)
-check: fmt vet lint test
+check: fmt vet lint test validate-skills test-skills

docs/skills.md

@@ -4,7 +4,30 @@ This document describes the skill system for the a6 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.
+
+Start with one task-specific skill. Add another only when the task clearly spans
+multiple workflows. Do not install the full collection by default: overlapping
+persona, recipe, and plugin guidance can make skill routing and updates harder
+to review.
+
+## Install a Skill
+
+Preview the available skills, then copy one skill into the current project:
+
+```bash
+npx skills add api7/a6 --list
+npx skills add api7/a6 --skill a6-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 `a6`, connect to APISIX, or run gateway commands.
+
+Use a non-production context 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 Admin API
+key in a prompt or committed file.
 
 ## Directory Structure
 
@@ -108,26 +131,31 @@ The body follows the skill type:
 
 ## CI Validation
 
-Every PR that modifies `skills/` is validated by `scripts/validate-skills.sh`. The script checks:
+Every PR that modifies `skills/` runs metadata validation and CLI-example
+tests. The checks cover:
 
 1. Every `skills/*/SKILL.md` has valid YAML frontmatter
 2. Required fields `name` and `description` are present
 3. `name` matches the directory name
 4. `name` follows kebab-case pattern
 5. `description` is non-empty
+6. Commands used in shell examples exist in the current a6 CLI
+7. Flags used in shell examples are supported by that command or globally
+8. Literal output formats and positional argument counts match the command
 
 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
 
 ## Skill Roadmap

skills/a6-persona-developer/SKILL.md

@@ -10,14 +10,15 @@ author: Apache APISIX Contributors
 license: Apache-2.0
 metadata:
   category: persona
-  apisix_version: ">=3.0.0"
+  apisix_version: ">=3.11.0"
   a6_commands:
     - a6 route create
     - a6 route update
     - a6 route get
     - a6 upstream create
     - a6 service create
     - a6 consumer create
+    - a6 credential create
     - a6 plugin list
     - a6 plugin get
     - a6 config sync
@@ -49,7 +50,7 @@ go install github.com/api7/a6/cmd/a6@latest
 a6 context create dev --server http://localhost:9180 --api-key edd1c9f034335f136f87ad84b625c8f1
 
 # Verify connection
-a6 health
+a6 route list --output table
 ```
 
 ### 2. Explore available plugins
@@ -287,9 +288,6 @@ upstreams:
 
 consumers:
   - username: dev
-    plugins:
-      key-auth:
-        key: dev-key
 
 routes:
   - id: api
@@ -303,23 +301,34 @@ EOF
 a6 config sync -f dev-config.yaml
 ```
 
+Create authentication data as a separate credential resource. Save the
+following as `dev-credential.yaml`:
+
+```yaml
+id: dev-key-auth
+plugins:
+  key-auth:
+    key: dev-key
+```
+
+```bash
+a6 credential create --consumer dev -f dev-credential.yaml
+```
+
 ## Debugging
 
 ### Trace a request
 
 ```bash
 # See how APISIX routes a specific request
-a6 debug trace --uri /api/users --method GET --header "apikey: dev-key"
+a6 debug trace api --path /api/users --method GET --header "apikey: dev-key"
 ```
 
 ### Stream logs
 
 ```bash
-# Watch APISIX error logs in real-time
+# Watch APISIX container logs in real-time
 a6 debug logs --follow
-
-# Filter by log level
-a6 debug logs --follow --level error
 ```
 
 ### Inspect a route's full config
@@ -350,14 +359,13 @@ a6 route get my-api --output json | jq .
     a6 config sync -f apisix-config.yaml
 ```
 
-### Export for other tools
+### Export the current configuration
 
-```bash
-# Export to Kubernetes-friendly format
-a6 export --format kubernetes > k8s-apisix.yaml
+`a6 config dump` does not export Consumer Credential subresources. Keep the
+credential files in your secure deployment workflow and restore them separately.
 
-# Export to standalone YAML
-a6 export --format standalone > apisix-standalone.yaml
+```bash
+a6 config dump --output yaml > apisix-backup.yaml
 ```
 
 ## Decision Framework
@@ -369,7 +377,7 @@ a6 export --format standalone > apisix-standalone.yaml
 | Multiple routes, same config | Create a Service → reference via `service_id` |
 | Need rate limiting | Choose `limit-count` (fixed) or `limit-req` (smooth) → add to route |
 | Backend URL changed | `a6 upstream update <id>` with new nodes |
-| Debug 502 errors | `a6 debug trace` → `a6 upstream health` → check backend |
+| Debug 502 errors | `a6 debug trace <route-id>` → `a6 upstream health` → check backend |
 | Prepare for production | `a6 config dump` → commit to git → `a6 config validate` in CI |
 | Test a new plugin | `a6 plugin get <name>` for schema → add to a test route → verify |
 

skills/a6-persona-operator/SKILL.md

@@ -21,7 +21,7 @@ metadata:
     - a6 config validate
     - a6 debug logs
     - a6 debug trace
-    - a6 health
+    - a6 route list
     - a6 ssl create
     - a6 global-rule create
 ---
@@ -65,8 +65,8 @@ Always verify the active context before running destructive operations.
 ### 1. Health check
 
 ```bash
-# Verify APISIX is reachable and get version
-a6 health
+# Verify that the APISIX Admin API is reachable
+a6 route list --output table
 
 # Check all upstream health status
 a6 upstream list --output json | jq '.[] | {id: .id, name: .name}'
@@ -117,14 +117,13 @@ a6 config diff -f new-config.yaml
 a6 --context staging config sync -f new-config.yaml
 
 # 4. Verify staging
-a6 --context staging health
-a6 --context staging route list
+a6 --context staging route list --output table
 
 # 5. Apply to production
 a6 --context prod config sync -f new-config.yaml
 
 # 6. Verify production
-a6 --context prod health
+a6 --context prod route list --output table
 ```
 
 ### Rollback
@@ -147,9 +146,9 @@ a6 route list
 a6 route get <route-id> --output json
 
 # 2. Trace the request path
-a6 debug trace --uri /api/v1/users --method GET
+a6 debug trace <route-id> --path /api/v1/users --method GET
 
-# 3. Stream error logs in real-time
+# 3. Stream APISIX container logs in real-time
 a6 debug logs --follow
 
 # 4. Check upstream health
@@ -163,10 +162,10 @@ a6 upstream health <upstream-id>
 a6 upstream get <upstream-id> --output json
 
 # Verify backend is reachable from APISIX
-a6 debug trace --uri /failing-endpoint
+a6 debug trace <route-id> --path /failing-endpoint
 
-# Check error logs for connection refused / timeout
-a6 debug logs --follow --level error
+# Check container logs for connection refused / timeout
+a6 debug logs --follow
 ```
 
 ### Authentication failures (401/403)

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

@@ -10,13 +10,14 @@ author: Apache APISIX Contributors
 license: Apache-2.0
 metadata:
   category: plugin
-  apisix_version: ">=3.0.0"
+  apisix_version: ">=3.11.0"
   plugin_name: basic-auth
   a6_commands:
     - a6 route create
     - a6 route update
     - a6 consumer create
     - a6 consumer update
+    - a6 credential create
 ---
 
 # a6-plugin-basic-auth
@@ -64,19 +65,18 @@ EOF
 
 ### 2. Add basic-auth credential
 
+Save the credential as `credential.yaml`, then create it:
+
+```yaml
+id: cred-alice-basic-auth
+plugins:
+  basic-auth:
+    username: alice
+    password: alice-password-123
+```
+
 ```bash
-curl "$(a6 context current -o json | jq -r .server)/apisix/admin/consumers/alice/credentials" \
-  -X PUT \
-  -H "X-API-KEY: $(a6 context current -o json | jq -r .api_key)" \
-  -d '{
-    "id": "cred-alice-basic-auth",
-    "plugins": {
-      "basic-auth": {
-        "username": "alice",
-        "password": "alice-password-123"
-      }
-    }
-  }'
+a6 credential create --consumer alice -f credential.yaml
 ```
 
 ### 3. Create a route with basic-auth enabled

skills/a6-plugin-consumer-restriction/SKILL.md

@@ -154,7 +154,7 @@ Only allow consumers in `enterprise` group:
 
 ```bash
 # Create consumer group
-a6 consumergroup create -f - <<'EOF'
+a6 consumer-group create -f - <<'EOF'
 {
   "id": "enterprise",
   "plugins": {

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

@@ -10,13 +10,14 @@ author: Apache APISIX Contributors
 license: Apache-2.0
 metadata:
   category: plugin
-  apisix_version: ">=3.0.0"
+  apisix_version: ">=3.11.0"
   plugin_name: hmac-auth
   a6_commands:
     - a6 route create
     - a6 route update
     - a6 consumer create
     - a6 consumer update
+    - a6 credential create
 ---
 
 # a6-plugin-hmac-auth
@@ -70,19 +71,18 @@ EOF
 
 ### 2. Add hmac-auth credential
 
+Save the credential as `credential.yaml`, then create it:
+
+```yaml
+id: cred-alice-hmac
+plugins:
+  hmac-auth:
+    key_id: alice-key
+    secret_key: alice-secret-key-value
+```
+
 ```bash
-curl "$(a6 context current -o json | jq -r .server)/apisix/admin/consumers/alice/credentials" \
-  -X PUT \
-  -H "X-API-KEY: $(a6 context current -o json | jq -r .api_key)" \
-  -d '{
-    "id": "cred-alice-hmac",
-    "plugins": {
-      "hmac-auth": {
-        "key_id": "alice-key",
-        "secret_key": "alice-secret-key-value"
-      }
-    }
-  }'
+a6 credential create --consumer alice -f credential.yaml
 ```
 
 ### 3. Create a route with hmac-auth enabled