authgear-server: Skill for Claude Code

Add a new Site Admin API feature: $ARGUMENTS

Follow the stages below in order. Confirm with the user before moving from one stage to the next.

---

Stage 1: Design and confirm OpenAPI spec

Add the endpoint to docs/api/siteadmin-api.yaml:

• Add the path under paths: with appropriate HTTP method(s)
• Use $ref: "#/components/responses/BadRequest", Forbidden, NotFound for error responses
• Add any new request/response schemas to components/schemas:
• Follow existing conventions: snake_case fields, hyphenated paths, format: date for date strings

Stop here. Present the spec diff to the user and wait for confirmation before proceeding.

---

Stage 2: Generate models

make generate

Avoid external type imports: pkg/siteadmin/model/oapi-codegen.yaml maps format: date → string and format: email → string so that no github.com/oapi-codegen/runtime/types import is generated. If you add a new OpenAPI format that would otherwise pull in an external type, add a mapping to output-options.type-mapping in that file before regenerating.

Commit: "[Site Admin] Generate models for <feature>"

---

Stage 3: Create and wire the handler file

Create pkg/siteadmin/transport/handler_<name>.go. No dummy data — leave ServeHTTP as a stub that returns http.NotFound:

package transport

import "net/http"

func Configure<Name>Route(route httproute.Route) httproute.Route {
    return route.WithMethods("OPTIONS", "GET"). // always include "OPTIONS" for CORS preflight
        WithPathPattern("/api/v1/...")
}

type <Name>Handler struct {
    // Service dependencies added in Stage 5
}

type <Name>Params struct {
    // path and query params
}

func parse<Name>Params(r *http.Request) (<Name>Params, error) {
    // parse path params via httproute.GetParam(r, "paramName")
    // query params: use helpers from params.go (getIntParam, getDateParam, etc.)
    // POST body: decode JSON, validate with validation.NewSimpleSchema
}

func (h *<Name>Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    _, err := parse<Name>Params(r)
    if err != nil {
        writeError(w, r, err)
        return
    }
    http.NotFound(w, r)
}