Kratos Skills for AI Agents

This skill provides comprehensive go-kratos microservices framework knowledge, optimized for AI agents helping developers build production-ready services.

🎯 When to Use This Skill

Invoke this skill when working with go-kratos:

• Creating services: REST APIs, gRPC services, or microservices architectures
• Layered architecture: Implementing Service → Biz → Data layers with DDD
• Dependency injection: Using Wire for compile-time DI
• Production hardening: Circuit breakers, rate limiting, middleware
• Debugging: Understanding errors, fixing configuration, or resolving issues
• Learning: Understanding kratos patterns and best practices

📚 Knowledge Structure

Load specific guides as needed rather than reading everything at once:

Quick Start

Link: Official Kratos Documentation Contains: Installation, project creation, basic commands, hello-world examples

Pattern Guides

API & Transport

Architecture & Design

Infrastructure

Resilience & Reliability

Observability

Security & Validation

Data & Tools

Supporting Resources

🚀 Common Workflows

Creating a New Service

1. Create project: kratos new <project-name>
2. Define API: Create .proto with google.api.http annotations
3. Generate code: kratos proto client api/demo/v1/demo.proto
4. Generate service: kratos proto server api/demo/v1/demo.proto -t internal/service
5. Implement layers: Biz logic in internal/biz/, data access in internal/data/
6. Configure Wire: Update cmd/server/wire.go with provider sets
7. Run: go generate ./... && kratos run

Details: references/api-patterns.md

Implementing Layered Architecture

1. Define interfaces in internal/biz/ (biz layer)
2. Implement repositories in internal/data/ (data layer)
3. Write use cases in internal/biz/ (biz layer)
4. Implement handlers in internal/service/ (service layer)
5. Create ProviderSets: data.ProviderSet, biz.ProviderSet, service.ProviderSet
6. Wire together in cmd/server/wire.go

Details: references/architecture-patterns.md

Adding Middleware

http.Middleware(
    recovery.Recovery(),           // 1. Catch panics first
    validate.Validator(),          // 2. Validate requests
    jwt.Server(keyFunc),           // 3. Authentication
    ratelimit.Server(limiter),     // 4. Rate limiting
    logging.Server(logger),        // 5. Logging
)

Details: references/middleware-patterns.md

Configuring Service Discovery

// Server-side
reg := etcd.New(client)
app := kratos.New(kratos.Registrar(reg))

// Client-side
dis := etcd.New(client)
conn, _ := grpc.DialInsecure(
    context.Background(),
    grpc.WithEndpoint("discovery:///service-name"),
    grpc.WithDiscovery(dis),
)

Details: references/registry-patterns.md

⚡ Key Principles

✅ Always Follow

• Layer separation: Service (API) → Biz (Business) → Data (Persistence)
• Dependency Inversion: Interfaces in biz, implementations in data
• Protobuf-first: Define APIs and errors in .proto files
• Wire injection: Compile-time DI, no global state
• Context propagation: Pass ctx context.Context through all layers
• Interface-based design: Program to interfaces, not implementations
• Error codes: Structured errors with code, reason, message, metadata

❌ Never Do

• Put business logic in service handlers (violates layered architecture)
• Skip interface definition and use concrete types directly
• Use global variables for dependencies
• Define HTTP handlers manually (use generated code from proto)
• Hard-code configuration values
• Skip validation or forget to check err != nil
• Modify generated .pb.go files

📖 Progressive Learning Path

🟢 New to kratos?

1. Official Quick Start – Install CLI, create first project
2. references/architecture-patterns.md – Understand Service → Biz → Data
3. references/api-patterns.md – Learn Protobuf API definition

🟡 Building production services?

1. best-practices/overview.md – Production checklist
2. references/circuit-breaker-patterns.md + references/ratelimit-patterns.md – Add resilience
3. references/registry-patterns.md – Service discovery
4. troubleshooting/common-issues.md – Avoid pitfalls

🔵 Extending capabilities?

1. getting-started/claude-code-guide.md – Advanced Claude Code features
2. Kratos Examples – Example projects

🔗 Kratos Ecosystem

📝 Version Compatibility

• Target version: kratos v2.0.0+
• Go version: Go 1.19 or later recommended
• Protoc: 3.0+

Quick invocation: Use /kratos-skills or ask “How do I [task] with kratos?”