kratos-skills

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

File	When to Load
references/api-patterns.md	Defining Protobuf APIs, generating HTTP/gRPC code
references/transport-patterns.md	HTTP/gRPC server/client configuration
references/encoding-patterns.md	Custom serialization, content negotiation
references/openapi-guide.md	OpenAPI/Swagger documentation generation

Architecture & Design

File	When to Load
references/architecture-patterns.md	DDD layers, repository pattern, Wire DI
references/error-patterns.md	Error definition, assertions, proto errors
references/middleware-patterns.md	Custom middleware, request filtering

Infrastructure

File	When to Load
references/config-patterns.md	Configuration loading, hot reload, config centers
references/registry-patterns.md	Service discovery (etcd, consul, nacos, k8s)
references/selector-patterns.md	Load balancing (P2C, WRR, random)

Resilience & Reliability

File	When to Load
references/circuit-breaker-patterns.md	Fault tolerance, SRE circuit breaker
references/ratelimit-patterns.md	Token bucket, BBR rate limiting
references/recovery-patterns.md	Panic recovery, stack trace logging

Observability

File	When to Load
references/logging-patterns.md	Structured logging, Zap/Logrus adapters
references/metrics-patterns.md	Prometheus metrics collection
references/tracing-patterns.md	OpenTelemetry, Jaeger/Zipkin tracing
references/metadata-patterns.md	Context propagation, trace IDs

Security & Validation

File	When to Load
references/auth-patterns.md	JWT authentication, claims, token generation
references/validate-patterns.md	Proto field validation, protoc-gen-validate

Data & Tools

File	When to Load
references/ent-patterns.md	Ent ORM integration, schema design
references/cli-guide.md	kratos CLI, code generation commands

Supporting Resources

File	When to Load
best-practices/overview.md	Production deployment, code review checklist
troubleshooting/common-issues.md	Debugging errors, protoc/wire issues
getting-started/claude-code-guide.md	Claude Code integration, advanced features

🚀 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

Project	Purpose
kratos	Framework core, CLI tools
kratos-layout	Official project template
contrib	Plugins for config, registry, log, metrics
aegis	Availability algorithms
gateway	API Gateway
examples	Example code

📝 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?"