add functionality to read api schema. add skill for schema command

Author: cjkenned

.github/workflows/test.yml

@@ -21,6 +21,14 @@ jobs:
       - name: Download dependencies
         run: go mod download
 
+      - name: Verify generated schema is up to date
+        run: |
+          go generate ./...
+          if ! git diff --exit-code internal/spec/extracted_gen.go; then
+            echo "::error::internal/spec/extracted_gen.go is stale. Run 'go generate ./...' and commit the result."
+            exit 1
+          fi
+
       - name: Run tests
         run: go test ./... -v -race -coverprofile=coverage.out
 

AGENTS.md

@@ -41,6 +41,9 @@ The CLI uses a **resource-registry** pattern:
 | `cmd/` | Root Cobra command, persistent flags, version command |
 | `internal/registry/` | Resource/Operation types, dynamic Cobra command builder |
 | `internal/resources/` | All resource implementations |
+| `internal/spec/` | OpenAPI request/response schemas (extracted at build time) |
+| `cmd/extract-schemas/` | Generator: reads `api/*.json` and emits `internal/spec/extracted_gen.go` |
+| `api/` | Checked-in OpenAPI specs (source of truth for the schema feature) |
 | `skills/` | Per-command agent skill documents (`<command>/SKILL.md` with YAML frontmatter) |
 | `internal/client/` | HTTP client with retry logic, structured error types |
 | `internal/auth/` | Credential resolution (env -> file), OAuth token caching |
@@ -196,6 +199,7 @@ When adding a new resource or operation:
 4. If the resource uses name-based lookup, add a `PreRun` hook for server-side ID resolution
 5. Update the **Command Surface** table in this file
 6. If the resource adds a new leaf command, add a corresponding `skills/<command>/SKILL.md` with frontmatter (`name`, `description`, `command`) and task-oriented agent guidance
+7. Set `SpecRef: registry.SpecRef{Path: "...", Method: "..."}` on each operation that maps to an OpenAPI route, then run `go generate ./...` (or `make generate`) so `internal/spec/extracted_gen.go` picks up the new route. CI fails if this file is stale.
 
 ### Adding New Skills
 

Makefile

@@ -6,11 +6,14 @@ LDFLAGS = -X github.com/airbytehq/airbyte-cli/cmd.Version=$(VERSION) \
           -X github.com/airbytehq/airbyte-cli/cmd.Commit=$(COMMIT) \
           -X github.com/airbytehq/airbyte-cli/cmd.Date=$(DATE)
 
-.PHONY: build test lint install clean
+.PHONY: build generate test lint install clean
 
-build:
+build: generate
 	go build -ldflags "$(LDFLAGS)" -o airbyte .
 
+generate:
+	go generate ./...
+
 test:
 	go test ./... -v
 

README.md

@@ -31,6 +31,9 @@ main.go
 | `cmd/` | Root Cobra command, persistent flags, version |
 | `internal/registry/` | `Resource` interface, dynamic command builder |
 | `internal/resources/` | Resource implementations |
+| `internal/spec/` | Generated OpenAPI request/response schemas |
+| `cmd/extract-schemas/` | Build-time generator: extracts the routes the CLI uses from `api/*.json` |
+| `api/` | Checked-in OpenAPI specs |
 | `skills/` | Per-command agent skill documents (`<command>/SKILL.md`) |
 | `internal/client/` | HTTP client (3x exponential-backoff retry on 429/5xx, 30s timeout) |
 | `internal/auth/` | Credential resolution, OAuth token caching |
@@ -163,9 +166,12 @@ This is **client-side**: the full payload still travels from the API to the CLI.
 ```bash
 airbyte --help                              # list resources
 airbyte connectors --help                   # list operations
-airbyte connectors execute --describe       # show parameter schema
+airbyte connectors execute --describe       # CLI params + OpenAPI request/response schema
+airbyte schema connectors execute           # equivalent top-level form
 ```
 
+`--describe` and `airbyte schema <resource> <operation>` return the same payload: CLI-level parameters under `params`, plus the underlying OpenAPI route (path, method, parameters, request body, response) under `api`. The OpenAPI schemas are extracted at build time from `api/*.json` and cover only the routes the CLI actually uses, so the dump stays focused.
+
 ### Command surface
 
 | Resource | Operation | Description |