chore: move agent skills to api7/agent-skills

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+## Summary
+
+<!-- What changed and why. -->
+
+## Agent skills checklist
+
+The agent skills for this CLI live in [api7/agent-skills](https://github.com/api7/agent-skills). CI runs `test/skills` against that repository's `main`, so keep the two in step:
+
+- [ ] This PR **adds** a command, flag, or plugin → merge this PR first, then open the reference update in api7/agent-skills.
+- [ ] This PR **removes or renames** a command or flag → merge the api7/agent-skills PR that stops using it first, then this PR.
+- [ ] No CLI surface change → nothing to do in api7/agent-skills.

.github/workflows/skills.yml

@@ -5,7 +5,8 @@ on:
   push:
     branches: [main, master]
   workflow_dispatch:
-
+  schedule:
+    - cron: "17 4 * * *" # daily: catch drift between this CLI and api7/agent-skills
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
@@ -17,12 +18,17 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Check out api7/agent-skills
+        uses: actions/checkout@v4
+        with:
+          repository: api7/agent-skills
+          path: agent-skills
+
       - uses: actions/setup-go@v5
         with:
           go-version: "1.23.0"
 
-      - name: Validate skills
-        run: make validate-skills
-
       - name: Test skills
         run: make test-skills
+        env:
+          SKILLS_DIR: ${{ github.workspace }}/agent-skills/skills/a7

AGENTS.md

@@ -25,7 +25,7 @@ a7 is a Go CLI wrapping the API7 Enterprise Edition Admin API (control-plane + A
 | `docs/coding-standards.md` | Go style, naming conventions | Before writing code |
 | `docs/testing-strategy.md` | Test patterns and practices | Before writing tests |
 | `docs/documentation-maintenance.md` | Rules for keeping docs in sync | When updating docs |
-| `docs/skills.md` | AI agent skill taxonomy and SKILL.md format | When adding or editing `skills/` entries |
+| `docs/skills.md` | Where the a7 agent skill lives (api7/agent-skills), install, CI validation | When touching skill validation or install docs |
 | `docs/user-guide/` | Per-resource user-facing guides | When changing user-visible behavior |
 
 ### Project Structure
@@ -34,7 +34,8 @@ a7 is a Go CLI wrapping the API7 Enterprise Edition Admin API (control-plane + A
 a7/
 ├── .github/workflows/             # CI/CD
 │   ├── ci.yml                     # Unit test + lint
-│   └── e2e.yml                    # E2E tests with real API7 EE
+│   ├── e2e.yml                    # E2E tests with real API7 EE
+│   └── skills.yml                 # Validates api7/agent-skills examples against the CLI
 ├── cmd/a7/main.go                 # Entry point
 ├── pkg/cmd/                       # Command implementations
 │   ├── factory.go                # Factory DI container
@@ -87,12 +88,13 @@ a7/
 ├── docs/                          # Documentation
 ├── test/fixtures/                 # JSON fixtures for tests
 ├── test/e2e/                      # E2E tests
-├── skills/                        # AI agent skill files
-├── scripts/                       # CI/utility scripts
+├── test/skills/                   # Validates api7/agent-skills examples against the CLI
 ├── Makefile                       # Build, test, lint commands
 └── .goreleaser.yml                # Cross-platform release config
 ```
 
+The AI agent skill (`a7`) lives in the [api7/agent-skills](https://github.com/api7/agent-skills) repository; `make test-skills` validates its shell examples against this CLI (see `docs/skills.md`).
+
 ### Key Architecture Patterns
 1. **Factory Pattern**: Every command receives a Factory with IOStreams, HttpClient, Config. No global state.
 2. **Command Pattern**: Options struct + `NewCmd()` + `Run()` per command.
@@ -133,7 +135,8 @@ make test-verbose     # Tests with verbose output
 make test-e2e         # E2E tests (requires API7 EE)
 make lint             # golangci-lint
 make fmt              # Format code
-make check            # fmt + vet + lint + test
+make check            # fmt + vet + lint + test + test-skills
+make test-skills      # Validate api7/agent-skills examples against the CLI (SKILLS_DIR=...)
 make clean            # Remove build artifacts
 ```
 

Makefile

@@ -8,7 +8,7 @@ LDFLAGS := -s -w \
 	-X $(MODULE)/internal/version.Commit=$(COMMIT) \
 	-X $(MODULE)/internal/version.Date=$(DATE)
 
-.PHONY: build test test-verbose lint fmt vet check install clean docker-up docker-down validate-skills test-skills test-e2e test-e2e-full
+.PHONY: build test test-verbose lint fmt vet check install clean docker-up docker-down test-skills test-e2e test-e2e-full
 
 build:
 	go build -ldflags "$(LDFLAGS)" -o bin/$(BINARY) ./cmd/a7
@@ -29,13 +29,13 @@ fmt:
 vet:
 	go vet ./...
 
-check: fmt vet lint test validate-skills
+check: fmt vet lint test test-skills
 
-validate-skills:
-	bash ./scripts/validate-skills.sh
+# a7 skill directory in a checkout of api7/agent-skills (see docs/skills.md)
+SKILLS_DIR ?= $(CURDIR)/../agent-skills/skills/a7
 
 test-skills:
-	go test ./test/skills -count=1
+	SKILLS_DIR="$(SKILLS_DIR)" go test ./test/skills -count=1
 
 install: build
 	cp bin/$(BINARY) $(GOPATH)/bin/$(BINARY)

PRD.md

@@ -328,7 +328,7 @@ The following table tracks feature parity between a7 and [a6](https://github.com
 | `--verbose` HTTP logging | ✅ | 🔲 | Phase 3 |
 | Declarative config (dump/diff/sync/validate) | ✅ | ✅ | Phase 4 |
 | docs/ (29 files) | ✅ | ✅ | Phase 5 |
-| skills/ (40 SKILL.md) | ✅ | ✅ | Phase 6 |
+| AI agent skill (now maintained in api7/agent-skills as `a7`) | ✅ | ✅ | Phase 6 |
 | Debug (logs + trace) | ✅ | ✅ | Phase 7 |
 | Self-update | ✅ | ✅ | Phase 7 |
 | E2E tests | ✅ | ✅ | Phase 8 |

README.md

@@ -11,6 +11,7 @@
 - **Gateway group scoping** — All runtime operations are scoped to a gateway group via `--gateway-group` flag or context config
 - **Rich output** — Human-friendly tables in TTY, machine-readable JSON/YAML in pipes (`--output json|yaml|table`)
 - **Shell completions** — Bash, Zsh, Fish, PowerShell (`a7 completion`)
+- **AI agent skill** — an [`a7` skill](https://skills.sh/api7/agent-skills/a7) that teaches AI coding agents to configure API7 EE through this CLI (`npx skills add api7/agent-skills --skill a7`)
 
 ## Installation
 
@@ -215,15 +216,49 @@ make test-verbose   # Tests with verbose output
 make lint           # Run linter
 make fmt            # Format code
 make vet            # Run go vet
-make check          # fmt + vet + lint + test
+make check          # fmt + vet + lint + test + test-skills
+make test-skills    # Validate api7/agent-skills examples against the CLI (SKILLS_DIR=...)
 ```
 
 See [AGENTS.md](AGENTS.md) for the full development guide, coding conventions, and how to add new commands.
 
+## AI Agent Skills
+
+The `a7` agent skill teaches AI coding agents (Claude Code, Cursor, Codex, GitHub Copilot, Windsurf, OpenCode and 70+ others) how to configure API7 Enterprise Edition through the a7 CLI. The skill content lives in the [api7/agent-skills](https://github.com/api7/agent-skills) repository and is published at [skills.sh/api7/agent-skills/a7](https://skills.sh/api7/agent-skills/a7).
+
+```bash
+# install into the current project (add -g for a global install, -a <agent> to pick an agent)
+npx skills add api7/agent-skills --skill a7
+```
+
+Without Node.js, `install.sh` in this repository copies the skill into `~/.claude/skills/a7` (or `--dir <path>`):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/api7/a7/master/install.sh | sh
+```
+
+One skill covers everything; the agent reads the detailed reference for a topic only when a task needs it:
+
+| Category | Count | Examples |
+|----------|-------|---------|
+| **Shared** | 1 | Core a7 conventions and patterns |
+| **Authentication** | 5 | key-auth, jwt-auth, basic-auth, hmac-auth, openid-connect |
+| **Security & Rate Limiting** | 4 | ip-restriction, cors, limit-count, limit-req |
+| **Traffic & Transformation** | 5 | proxy-rewrite, response-rewrite, traffic-split, redirect, grpc-transcode |
+| **AI Gateway** | 4 | ai-proxy, ai-prompt-template, ai-prompt-decorator, ai-content-moderation |
+| **Observability** | 6 | prometheus, skywalking, zipkin, http-logger, kafka-logger, datadog |
+| **Advanced Plugins** | 5 | serverless, ext-plugin, fault-injection, consumer-restriction, wolf-rbac |
+| **Operational Recipes** | 5 | blue-green, canary, circuit-breaker, health-check, mTLS |
+| **Advanced Recipes** | 3 | multi-tenant, api-versioning, graphql-proxy |
+| **Personas** | 2 | operator, developer |
+
+Skill content changes go to [api7/agent-skills](https://github.com/api7/agent-skills); this repository's CI (`make test-skills`) validates the shell examples against the current CLI. See [docs/skills.md](docs/skills.md) for details.
+
 ## Documentation
 
 - [Product Requirements](PRD.md)
 - [AI Agent Guide](AGENTS.md)
+- [AI Agent Skills](docs/skills.md)
 - [Architecture Decision Record](docs/adr/001-tech-stack.md)
 - [API7 EE API Specification](docs/api7ee-api-spec.md)
 - [Golden Example](docs/golden-example.md)

docs/roadmap.md

@@ -15,7 +15,7 @@ This document tracks phase status for the a7 CLI (API7 Enterprise Edition) and r
 | 3 | CLI usability (`-f/--file`, `export`, `--force`, `--label`). `--dry-run` and `--verbose` are partial; see PRD Phase 3. | ✅ (partial flags noted in PRD) |
 | 4 | Declarative configuration (`a7 config dump|diff|sync|validate`) | ✅ |
 | 5 | Documentation (ADR, coding standards, golden example, testing strategy, skills, api spec, user guides) | ✅ |
-| 6 | AI agent skills (40 SKILL.md files, taxonomy in `docs/skills.md`) | ✅ |
+| 6 | AI agent skills (40 SKILL.md files, since moved to [api7/agent-skills](https://github.com/api7/agent-skills) as one `a7` skill; see `docs/skills.md`) | ✅ |
 | 7 | Debug & operations (`a7 debug logs`, `a7 debug trace`, `a7 update`) | ✅ |
 | 8 | E2E tests against a real API7 EE Docker stack (per-resource CRUD, config sync/diff/dump/validate, debug, completion, version) | ✅ |