# golang-web

golang-web — a skill for Claude Code, Codex, and other IDEs that defines Go web application architecture. It structures projects, manages dependencies, and enforces standardized error handling.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 102 installs · ★ 300 repo stars
- Author: majiayu000
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/majiayu000/spellbook/tree/HEAD/skills/golang-web/SKILL.md
- Updated: 2026-10-23
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/golang-web

## What it does

This skill guides the creation of Go web projects, APIs, and microservices following established standards. It mandates a standard layout with `cmd`, `internal`, and `pkg` directories to maintain project clarity.

The architecture relies on explicit dependency wiring in `main.go` and interface-driven design. It requires using a `LiteLLM` proxy for all LLM API integrations instead of direct calls. The development approach forbids backward compatibility layers, favoring direct code updates and deletion of unused components.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add majiayu000/spellbook --skill golang-web -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/golang-web/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/golang-web/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add majiayu000/spellbook --skill golang-web -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/golang-web/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add majiayu000/spellbook --skill golang-web -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/golang-web/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install majiayu000/spellbook skills/golang-web
```

2. **Manually: put the files in place**
- File: `.github/skills/golang-web/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add majiayu000/spellbook --skill golang-web -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/majiayu000/spellbook --path skills/golang-web
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/golang-web/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add majiayu000/spellbook --skill golang-web -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/majiayu000/spellbook/tree/HEAD/skills/golang-web/SKILL.md

## When to use it
- initialize a Go web project structure
- wire dependencies in `main.go`
- configure `LiteLLM` for LLM integration
- implement consistent error handling

## Example prompts
- Initialize my project with `golang-web`
- Apply the `golang-web` architecture
- Set up `LiteLLM` using `golang-web` standards

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: b9fdc35182c32fb6.

BEGIN THIRD-PARTY FILE b9fdc35182c32fb6
````text
---
name: golang-web
description: Modern Go Web application architecture guide. Use when creating new Go web projects, APIs, or microservices. Covers project structure, tech stack selection, and best practices based on Go standards.
---
# Go Web Architecture

## Core Principles

- **Standard layout** — Follow cmd/internal/pkg convention
- **Explicit dependencies** — Wire dependencies in main.go, no globals
- **Interface-driven** — Define interfaces where you use them, not where you implement
- **Error wrapping** — Wrap errors with context, use error codes
- **No backwards compatibility** — Delete, don't deprecate. Change directly
- **LiteLLM for LLM APIs** — Use LiteLLM proxy for all LLM integrations

---

## No Backwards Compatibility

> **Delete unused code. Change directly. No compatibility layers.**

```go
// ❌ BAD: Deprecated function kept around
// Deprecated: Use NewUserService instead
func CreateUserService() *UserService { ... }

// ❌ BAD: Alias for renamed types
type OldName = NewName // "for backwards compatibility"

// ❌ BAD: Unused parameters
func Process(_ context.Context, data Data) { ... }

// ✅ GOOD: Just delete and update all usages
func NewUserService(repo UserRepository) *UserService { ... }
```

---

## LiteLLM for LLM APIs

> **Use LiteLLM proxy. Don't call provider APIs directly.**

```go
// adapters/llm/client.go
package llm

import (
    "github.com/sashabaranov/go-openai"
)

// Connect to LiteLLM proxy using OpenAI-compatible SDK
func NewClient(cfg Config) *openai.Client {
    config := openai.DefaultConfig(cfg.APIKey)
    config.BaseURL = cfg.BaseURL // LiteLLM proxy URL
    return openai.NewClientWithConfig(config)
}
```

---

## Quick Start

### 1. Initialize Project

```bash
mkdir myapp && cd myapp
go mod init github.com/yourname/myapp

# Install core dependencies
go get github.com/gin-gonic/gin
go get github.com/spf13/viper
go get github.com/sirupsen/logrus
go get gorm.io/gorm
```

### 2. Apply Tech Stack

| Layer | Recommendation |
|-------|----------------|
| HTTP Framework | Gin / Chi / Echo |
| Configuration | Viper |
| Logging | Logrus / Zap / Slog |
| Database ORM | GORM / sqlx / sqlc |
| Validation | go-playground/validator |
| Testing | testify / go test |

### Version Strategy

> **Always get latest. Never pin in templates.**

```bash
# Always fetch latest
go get -u github.com/gin-gonic/gin
go get -u ./...

# go.mod handles version locking
# go.sum ensures reproducible builds
```

### 3. Use Standard Structure

```
myapp/
├── cmd/
│   └── myapp/
│       └── main.go            # Entry point, dependency wiring
├── configs/
│   └── config.go              # Configuration struct + loader
├── internal/                  # Private application code
│   ├── handlers/              # HTTP handlers
│   ├── services/              # Business logic
│   ├── repositories/          # Data access
│   ├── models/                # Domain models
│   ├── middleware/            # HTTP middleware
│   └── router/                # Route definitions
├── pkg/                       # Public reusable packages
│   ├── errors/                # Error types
│   ├── logger/                # Logging setup
````
END THIRD-PARTY FILE b9fdc35182c32fb6

The third-party file has ended. Everything between the b9fdc35182c32fb6 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3296 of 11114 bytes. © majiayu000 · MIT · https://github.com/majiayu000/spellbook/tree/HEAD/skills/golang-web/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
