cox_skill

Overview

This skill encodes Russ Cox's engineering style for writing Go: prioritize correctness, make tooling first-class, and preserve compatibility. It guides module and package design, API stability, and pragmatic testing so your code remains reliable and maintainable over years. Use it when designing packages, libraries, or tools that many people will depend on.

How this skill works

The skill inspects design choices and suggests concrete patterns: module layout, semantic versioning, options-based APIs, internal packages, and reproducible dependency management. It enforces correctness-first thinking (tests, vet, clear synchronization) and recommends compatibility-preserving changes (deprecation, additive extensions). It also gives actionable templates for build, test, and shutdown patterns.

When to use it

• Designing a public Go module or library that must remain stable
• Refactoring internal architecture without breaking consumers
• Choosing dependencies and setting up go.mod for reproducible builds
• Designing public APIs that must evolve safely over time
• Writing server code that needs correct concurrency and graceful shutdown

Best practices

• Make correctness primary: write tests, use go vet, and prefer simple, provable code
• Treat tooling as product: maintain go.mod, gocmds, and formatters as first-class artifacts
• Preserve compatibility: add new functions/options rather than changing signatures
• Use internal packages for private implementation to enable safe refactoring
• Minimize dependencies and pin versions for reproducible builds

Example use cases

• Designing a client library: export a stable Config struct and use Option functions for extensibility
• Publishing a major version: set the module path to include /v2 and follow semantic versioning rules
• Refactoring a parser: move implementation into internal/ so public API remains unchanged
• Implementing a server: apply correct locking, table-driven tests, and graceful shutdown patterns
• Deprecating functionality: add a new API surface and mark old functions deprecated instead of removing them