⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v2.0.1

go-api-design

eduardo-sl@eduardo-sl⭐ 88 stars· last commit 1mo ago· 1 open issues

>

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐ 88 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

npx skills add eduardo-sl/go-agent-skills

Why

AI coding agents write Go that compiles. Writing Go that reads like Go takes more than that. Left to defaults, an agent returns errors with no context, declares interfaces next to their only implementation, starts goroutines nothing ever stops, and reaches for interface{} where a type parameter belongs.

go-agent-skills gives the agent the judgment an experienced Go reviewer brings: 35 focused skills grounded in Effective Go, Go Code Review Comments, and patterns from large-scale production Go services. They follow the open Agent Skills standard, work in any compatible agent, and load on demand. Until a skill is relevant, it costs about 135 tokens.

// ❌ Before: the caller gets "sql: no rows in result set" and nothing else
func (s *Service) User(id int) (*User, error) {
    u, err := s.repo.Find(id)
    if err != nil {
        return nil, err
    }
    return u, nil
}

// ✅ After (go-error-handling + go-context): cancellable, wrapped, still matchable
func (s *Service) User(ctx context.Context, id int) (*User, error) {
    u, err := s.repo.Find(ctx, id)
    if err != nil {
        return nil, fmt.Errorf("find user %d: %w", id, err)
    }
    return u, nil
}

Highlights

  • 🎯 35 skills across six areas. Code quality, architecture, data, safety and performance, testing, and workflow.
  • 🪶 Progressive disclosure. About 4,800 tokens of descriptions at startup. Bodies and 62 reference files load only when a task needs them.
  • 🧭 A router for overlap. go-skills-router maps a task to the skill that owns it and draws the line where two overlap.
  • 🧪 Measured, not asserted. 159 eval cases you run with and without the skills. The difference between the two runs is the result.
  • 🔐 Least privilege. Every skill declares scoped allowed-tools. Review and audit skills cannot write.
  • 🔄 Current with Go. Covers Go 1.21 through 1.27. A weekly workflow opens an issue when a new Go release ships that go-modernize doesn't cover yet.
  • 🔌 Agent-agnostic. Works in Claude Code, Cursor, Codex, GitHub Copilot, Windsurf, OpenCode, Cline, and more.

🚀 Quick start

Install with the npx skills CLI. It detects the agents you have and puts each skill where that agent looks for it. That covers Claude Code, Cursor, Codex, GitHub Copilot, Windsurf, OpenCode, Cline, and 37+ more agents.

# Everything, interactive
npx skills add eduardo-sl/go-agent-skills

# Look before you install
npx skills add eduardo-sl/go-agent-skills --list

# Only the skills you want
npx skills add eduardo-sl/go-agent-skills --skill go-code-review --skill go-defensive-coding

# Globally, for every project
npx skills add eduardo-sl/go-agent-skills -g

# Non-interactive, for CI and dotfiles
npx skills add eduardo-sl/go-agent-skills --all -y
/plugin marketplace add eduardo-sl/go-agent-skills
/plugin install go-agent-skills@eduardo-sl

Or install the files directly: npx skills add eduardo-sl/go-agent-skills -a claude-code

npx skills add eduardo-sl/go-agent-skills -a cursor

Cursor auto-discovers skills from .cursor/skills/ and .agents/skills/.

npx skills add eduardo-sl/go-agent-skills -a copilot

Copilot auto-discovers skills from .github/skills/.

npx skills add eduardo-sl/go-agent-skills -a codex

Codex auto-discovers skills from ~/.agents/skills/ and .agents/skills/.

npx skills add eduardo-sl/go-agent-skills -a windsurf
npx skills add eduardo-sl/go-agent-skills -a opencode
npx skills add eduardo-sl/go-agent-skills -a cline
git clone https://github.com/eduardo-sl/go-agent-skills.git
./go-agent-skills/scripts/install.sh /path/to/your-go-project --agent claude

# Preview without changing anything
./go-agent-skills/scripts/install.sh /path/to/project --agent claude --dry-run

# Symlink instead of copying, so a `git pull` updates every project
./go-agent-skills/scripts/install.sh /path/to/project --agent claude --symlink

Agents: claude, cursor, copilot, codex, windsurf. Add --global to install into your home directory.

mkdir -p .claude/skills && cp -r go-agent-skills/skills/*/* .claude/skills/   # Claude Code
mkdir -p .cursor/skills && cp -r go-agent-skills/skills/*/* .cursor/skills/   # Cursor
mkdir -p .github/skills && cp -r go-agent-skills/skills/*/* .github/skills/   # Copilot
mkdir -p .agents/skills && cp -r go-agent-skills/skills/*/* .agents/skills/   # Codex / OpenCode
npx skills check      # anything out of date?
npx skills update     # bring them current
npx skills list       # what is installed
npx skills remove go-performance-review

💬 Usage

There is nothing to learn. Work as usual, and the agent loads a skill when your task matches its description. Agents that support slash commands can also invoke a skill directly:

/go-code-review
/go-concurrency-review

Real tasks usually need more than one skill. These combinations come from go-skills-router:

Ask your agentSkills it loads
"Review this PR"go-code-review
"Build a gRPC service with tests"go-grpc + go-test-quality + go-error-handling
"This endpoint is slow under load"go-troubleshooting + go-performance-review + go-database
"Harden this service before launch"go-security-audit + go-dependency-audit + go-defensive-coding + go-ci
"Split this monolith"go-architecture-review + go-refactoring + go-semantic-tools
"Scaffold a new CLI"`go-project-layou

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/(architecture)/go-api-design/SKILL.md7.7 KBupstream ↗
    ---
    name: go-api-design
    description: >
      REST and gRPC API design patterns for Go services. Covers HTTP handlers,
      middleware, routing, request/response patterns, versioning, pagination,
      graceful shutdown, and OpenAPI documentation. Use when designing APIs,
      writing HTTP handlers, implementing middleware, structuring REST
      endpoints, or setting up gRPC services. Trigger examples: "design API",
      "REST endpoints", "HTTP handler", "middleware pattern", "graceful
      shutdown", "gRPC service", "API versioning".
      Not for: general architecture (go-architecture-review), concurrency in
      handlers (go-concurrency-review).
    user-invocable: true
    license: MIT
    compatibility: Designed for Claude Code or similar AI coding agents working on Go projects. Requires the Go toolchain.
    allowed-tools: Read Edit Write Glob Grep Bash(go:*) Bash(gofmt:*)
    metadata:
      author: eduardo-sl
      version: "1.1.1"
    ---
    
    # Go API Design
    
    APIs are contracts. Once published, they're promises. Design them as if
    you'll maintain them for a decade — because you probably will.
    
    ## 1. HTTP Handler Structure
    
    ### Use the standard `http.Handler` interface:
    
    ```go
    // ✅ Good — method on a struct with dependencies
    type UserHandler struct {
        store  UserStore
        logger *slog.Logger
    }
    
    func (h *UserHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
        switch r.Method {
        case http.MethodGet:
            h.handleGet(w, r)
        case http.MethodPost:
            h.handleCreate(w, r)
        default:
            http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
        }
    }
    ```
    
    ### Handler function signature pattern:
    
    ```go
    // Handler methods return nothing — they write directly to ResponseWriter.
    // Errors are handled inside the handler, not returned.
    func (h *UserHandler) handleGet(w http.ResponseWriter, r *http.Request) {
        ctx := r.Context()
    
        id := chi.URLParam(r, "id") // or mux.Vars(r)["id"]
        if id == "" {
            h.respondError(w, http.StatusBadRequest, "missing user id")
            return
        }
    
        user, err := h.store.GetByID(ctx, id)
        if err != nil {
            if errors.Is(err, ErrNotFound) {
                h.respondError(w, http.StatusNotFound, "user not found")
                return
            }
            h.logger.Error("get user", slog.Any("error", err))
            h.respondError(w, http.StatusInternalServerError, "internal error")
            return
        }
    
        h.respondJSON(w, http.StatusOK, user)
    }
    ```
    
    ### JSON response helpers:
    
    ```go
    func (h *UserHandler) respondJSON(w http.ResponseWriter, status int, data interface{}) {
        w.Header().Set("Content-Type", "application/json")
        w.WriteHeader(status)
        if err := json.NewEncoder(w).Encode(data); err != nil {
            h.logger.Error("encode response", slog.Any("error", err))
        }
    }
    
    func (h *UserHandler) respondError(w http.ResponseWriter, status int, msg string) {
        h.respondJSON(w, status, map[string]string{"error": msg})
    }
    ```
    
    ## 2. Middleware Pattern
    
    Middleware wraps handlers. Use the standard `func(http.Handler) http.Handler` signature:
    
    ```go
    func RequestID(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            id := r.Header.Get("X-Request-ID")
            if id == "" {
                id = uuid.New().String()
            }
            ctx := context.WithValue(r.Context(), requestIDKey, id)
            w.Header().Set("X-Request-ID", id)
            next.ServeHTTP(w, r.WithContext(ctx))
        })
    }
    
    func Recoverer(logger *slog.Logger) func(http.Handler) http.Handler {
        return func(next http.Handler) http.Handler {
            return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
                defer func() {
                    if rec := recover(); rec != nil {
                        logger.Error("panic recovered",
                            slog.Any("panic", rec),
                            slog.String("stack", string(debug.Stack())),
                        )
                        http.Error(w, "internal server error", http.StatusInternalServerError)
                    }
                }()
                next.ServeHTTP(w, r)
            })
        }
    }
    ```
    
    ### Middleware ordering (outside → inside):
    
    ```text
    Recoverer → RequestID → Logger → Auth → RateLimit → Handler
    ```
    
    Recover MUST be outermost. Auth before business logic. Logger captures timing.
    
    ## 3. Request Validation
    
    ### Decode and validate in one step:
    
    ```go
    type CreateUserRequest struct {
        Name  string `json:"name"  validate:"required,min=2,max=100"`
        Email string `json:"email" validate:"required,email"`
    }
    
    func decodeAndValidate[T any](r *http.Request) (T, error) {
        var req T
        if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
            return req, fmt.Errorf("decode: %w", err)
        }
        if err := validate.Struct(req); err != nil {
            return req, fmt.Errorf("validate: %w", err)
        }
        return req, nil
    }
    ```
    
    ### Limit request body size:
    
    ```go
    r.Body = http.MaxBytesReader(w, r.Body, 1<<20) // 1 MB
    ```
    
    ## 4. URL and Naming Conventions
    
    ```text
    GET    /api/v1/users          → list users
    POST   /api/v1/users          → create user
    GET    /api/v1/users/{id}     → get user
    PUT    /api/v1/users/{id}     → replace user
    PATCH  /api/v1/users/{id}     → partial update
    DELETE /api/v1/users/{id}     → delete user
    
    GET    /api/v1/users/{id}/orders → list user orders (nested resource)
    ```
    
    Rules:
    - Plural nouns for resources: `/users`, not `/user`
    - Kebab-case for multi-word paths: `/order-items`
    - camelCase for JSON fields: `"createdAt"`, `"firstName"`
    - Version in URL path: `/api/v1/...`
    - No verbs in URLs: `/users/search?q=alice`, NOT `/searchUsers`
    
    ## 5. Pagination
    
    ```go
    type PageRequest struct {
        Cursor string `json:"cursor"`
        Limit  int    `json:"limit"`
    }
    
    type PageResponse[T any] struct {
        Items      []T    `json:"items"`
        NextCursor string `json:"next_cursor,omitempty"`
        HasMore    bool   `json:"has_more"`
    }
    ```
    
    Prefer cursor-based pagination over offset/limit for large datasets.
    Offset pagination breaks under concurrent writes.
    
    ## 6. Graceful Shutdown
    
    ```go
    func main() {
        srv := &http.Server{
            Addr:         ":8080",
            Handler:      router,
            ReadTimeout:  5 * time.Second,
            WriteTimeout: 10 * time.Second,
            IdleTimeout:  120 * time.Second,
        }
    
        // Start server
        go func() {
            if err := srv.ListenAndServe(); err != http.ErrServerClosed {
                log.Fatalf("server error: %v", err)
            }
        }()
    
        // Wait for interrupt
        quit := make(chan os.Signal, 1)
        signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
        <-quit
    
        // Graceful shutdown with timeout
        ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
        defer cancel()
    
        if err := srv.Shutdown(ctx); err != nil {
            log.Fatalf("shutdown error: %v", err)
        }
        log.Println("server stopped gracefully")
    }
    ```
    
    Programs should exit only in `main()`, preferably at most once.
    
    ## 7. Health Check Endpoints
    
    ```go
    // Liveness: is the process alive?
    // GET /healthz → 200 OK
    
    // Readiness: can the process serve traffic?
    // GET /readyz → 200 OK or 503 Service Unavailable
    func (h *HealthHandler) handleReady(w http.ResponseWriter, r *http.Request) {
        if err := h.db.PingContext(r.Context()); err != nil {
            h.respondError(w, http.StatusServiceUnavailable, "database unavailable")
            return
        }
        h.respondJSON(w, http.StatusOK, map[string]string{"status": "ready"})
    }
    ```
    
    ## 8. Error Response Format
    
    Consistent error responses across the entire API:
    
    ```json
    {
        "error": {
            "code": "VALIDATION_ERROR",
            "message": "invalid request parameters",
            "details": [
                {"field": "email", "message": "must be a valid email"}
            ]
        }
    }
    ```
    
    Map internal errors to HTTP status codes at the handler boundary.
    Internal errors should NEVER leak to clients.
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/eduardo-sl-go-agent-skills-skills-architecture-go-api-design.md

// REPO STATS

88 stars
1 open issues
Last commit: 1mo ago