go-zero Skills for AI Agents

This skill provides comprehensive go-zero microservices framework knowledge, optimized for AI agents helping developers build production-ready services. It covers REST APIs, RPC services, database operations, resilience patterns, and troubleshooting.

🎯 When to Use This Skill

Invoke this skill when working with go-zero:

• •Creating services: REST APIs, gRPC services, or microservices architectures
• •Database integration: SQL, MongoDB, Redis, or connection pooling
• •Production hardening: Circuit breakers, rate limiting, or error handling
• •Debugging: Understanding errors, fixing configuration, or resolving issues
• •Learning: Understanding go-zero patterns and best practices

📚 Knowledge Structure

This skill organizes go-zero knowledge into focused modules. Load specific guides as needed rather than reading everything at once:

Quick Start Guide

Link: Official go-zero Documentation Contains: Installation, first API service, basic commands, hello-world examples (refer to official docs)

Pattern Guides (Detailed Reference)

1. REST API Patterns

File: references/rest-api-patterns.md When to load: Creating HTTP endpoints, implementing CRUD operations, adding middleware Contains:

• •Handler → Logic → Context three-layer architecture
• •Request/response handling with proper types
• •Middleware (auth, logging, metrics, CORS)
• •Error handling with httpx.Error() and httpx.OkJson()
• •Complete CRUD examples with ✅ correct vs ❌ incorrect patterns

2. RPC Service Patterns

File: references/rpc-patterns.md When to load: Building gRPC services, service-to-service communication Contains:

• •Protocol Buffers definition and code generation
• •Service discovery with etcd/consul/kubernetes
• •Load balancing strategies
• •Client configuration and interceptors
• •Error handling in RPC contexts

3. Database Patterns

File: references/database-patterns.md When to load: Implementing data persistence, caching, or complex queries Contains:

• •SQL operations with sqlx (CRUD, transactions, batch inserts)
• •MongoDB integration patterns
• •Redis caching strategies and cache-aside pattern
• •Model generation with goctl model
• •Connection pooling and performance tuning

4. Resilience Patterns

File: references/resilience-patterns.md When to load: Production hardening, handling failures, managing system load Contains:

• •Circuit breaker configuration (Breaker)
• •Rate limiting and API throttling
• •Load shedding under pressure
• •Timeout and retry strategies
• •Graceful shutdown and degradation

Supporting Resources

Best Practices

File: best-practices/overview.md When to load: Production deployment, code review, optimization Contains: Configuration management, logging, monitoring, security, performance

Troubleshooting

File: troubleshooting/common-issues.md When to load: Debugging errors, configuration issues, runtime problems Contains: Common error messages, solutions, configuration pitfalls, debugging tips

Claude Code Integration

File: getting-started/claude-code-guide.md When to load: Setting up Claude Code for zero-skills usage Contains: Installation, invocation methods, advanced features (subagents, dynamic context)

🚀 Common Workflows

These workflows guide you through typical go-zero development tasks:

Creating a New REST API Service

Steps:

1. •Define API specification in .api file with types and routes
2. •Generate code: goctl api go -api user.api -dir .
3. •Implement business logic in internal/logic/ layer
4. •Add validation and error handling with httpx
5. •Test endpoints with proper request/response handling

Detailed guide: references/rest-api-patterns.md

Implementing Database Operations

Steps:

1. •Design database schema and create tables
2. •Generate model: goctl model mysql datasource -url="..." -table="users" -dir="./model"
3. •Inject model into ServiceContext in internal/svc/service_context.go
4. •Use sqlx methods in logic layer (Insert, FindOne, Update, Delete)
5. •Handle transactions and errors properly with ctx propagation

Detailed guide: references/database-patterns.md

Adding Middleware

Steps:

1. •Create middleware function in internal/middleware/ directory
2. •Define middleware in .api file or register programmatically
3. •Implement authentication/authorization logic
4. •Pass validated data through r.Context()
5. •Handle errors with appropriate HTTP status codes

Detailed guide: references/rest-api-patterns.md

Building an RPC Service

Steps:

1. •Define service in .proto file with messages and RPCs
2. •Generate code: goctl rpc protoc user.proto --go_out=. --go-grpc_out=. --zrpc_out=.
3. •Implement service logic in internal/logic/
4. •Configure service discovery (etcd/consul/kubernetes)
5. •Test with RPC client and handle errors

Detailed guide: references/rpc-patterns.md

⚡ Key Principles

When generating or reviewing go-zero code, always apply these principles:

✅ Always Follow

• •Three-layer separation: Keep Handler (routing) → Logic (business) → Model (data) distinct
• •Structured errors: Use httpx.Error(w, err) for HTTP errors, not fmt.Errorf
• •Configuration: Load with conf.MustLoad(&c, *configFile) and inject via ServiceContext
• •Context propagation: Pass ctx context.Context through all layers for tracing and cancellation
• •Type safety: Define request/response types in .api files, generate with goctl
• •goctl generation: Always use goctl to generate boilerplate, never hand-write handlers/routes

❌ Never Do

• •Put business logic directly in handlers (violates three-layer architecture)
• •Return raw errors with w.Write() or fmt.Fprintf() instead of using httpx helpers
• •Hard-code configuration values (ports, hosts, database credentials)
• •Skip validation of user inputs or forget to check err != nil
• •Modify generated code (customize via logic layer instead)
• •Bypass ServiceContext injection (leads to tight coupling and testing issues)

📖 Progressive Learning Path

Follow this path based on your needs:

🟢 New to go-zero?

1. •

   Start here: Official go-zero Quick Start Install go-zero, create your first API, understand basic concepts

   Connect to MySQL/PostgreSQL, generate models, implement CRUD

🟡 Building production services?

1. •

   Review best practices: best-practices/overview.md Configuration, logging, monitoring, security checklist

2. •

   Add resilience: references/resilience-patterns.md Circuit breakers, rate limiting, graceful degradation

3. •

   Check common pitfalls: troubleshooting/common-issues.md Avoid typical mistakes and know how to debug issues

🔵 Extending capabilities?

1. •

   Use with Claude Code: getting-started/claude-code-guide.md Learn advanced features like subagents, dynamic context, and argument passing Run demo projects to validate your environment

2. •

   Verify knowledge: examples/verify-tutorial.sh Script to check if examples work correctly

🔗 Integration with go-zero AI Ecosystem

This skill is part of a three-tool ecosystem for AI-assisted go-zero development:

Usage in Claude Code:

• •This skill loads automatically when working with go-zero projects
• •Use /zero-skills to invoke manually for go-zero guidance
• •Combine with mcp-zero tools for automatic code generation
• •Reference specific pattern files when needed (Claude loads them on demand)

See getting-started/claude-code-guide.md for detailed usage instructions.

🌐 Additional Resources

• •Official docs: go-zero.dev - Latest API reference and guides
• •GitHub: zeromicro/go-zero - Source code and examples
• •Community: Discussions, issues, and contributions welcome in the main repository

📝 Version Compatibility

• •Target version: go-zero 1.5+
• •Go version: Go 1.19 or later recommended
• •Updates: Patterns updated regularly to reflect framework evolution
• •Breaking changes: Check official docs for API changes between versions

Quick invocation: Use /zero-skills or ask "How do I [task] with go-zero?" Need help? Reference the specific pattern guide for detailed examples and explanations.