Agent Skills Best Practices
A condensed summary of the 25 most important best practices drawn from every page in this section.
//
Search across all documentation pages
A condensed summary of the 25 most important best practices drawn from every page in this section.
Skills are playbooks, not tutorials: SKILL.md files tell agents how to execute - Agent Skills Basics defines structure; net/http Basics teaches concepts.
Pin the stack in every skill: Go 1.26.x, golangci-lint team config, frameworks (chi, gin, gRPC-Go, controller-runtime, TinyGo, wazero) - unpinned skills hallucinate deprecated APIs.
One skill per decision domain: Concurrency review, module audit, API design, profiling, testing, operators, WASM - never one mega-skill.
Declare inputs before acting: go.mod, affected packages, ADR links, CI commands - agents guess without them.
Outputs must be verifiable: Commands and checklists, not prose summaries - reject skill runs that omit go test ./....
Guardrails are the highest-value section: Context deadlines, error mapping, go get policy, operator RBAC - see Go API Design Review Skill.
Invoke skills at decision points: Pre-merge review, CVE sweep, incident profiling - not for reading introductory docs.
Human docs remain source of truth: Skills link to Table-Driven Tests, govulncheck doc, Reconciler patterns - don't duplicate.
Run go test -race when concurrency touched: Mandatory gate in Go Concurrency Review Skill output.
Run govulncheck ./... before dependency merges: Go Module & Security Audit Skill orchestrates the same gate as security CI.
No blind go get -u ./...: Surgical pins with changelog review and human approval.
Propagate r.Context() in handlers: Missing deadlines is a blocker finding in API review skill.
Map errors in one layer: Handlers or apierr package - not both with conflicting status codes.
Profile before optimizing: Go Performance Profiling Skill blocks speculative sync.Pool without pprof.
Table-driven subtests from AC: Go Testing & Benchmark Skill maps each bullet to t.Run.
Fuzz pure parsers only: No network/DB in fuzz targets without dedicated integration setup.
Operator Reconcile must be idempotent: No panics; finalizers need removal path - Go Kubernetes Operator Review Skill.
RBAC least privilege: Flag * verbs and cluster-admin markers before merge.
WASI vs browser WASM: Never syscall/js in wasip1 builds - WASM & TinyGo Build Review Skill.
Size budget on WASM artifacts: Measure with wasm-objdump / ls -la before approving new deps.
Align skills with ADRs: Link Writing ADRs for Go Architecture Decisions in References section.
Mirror CI commands in skills: If skill says golangci-lint run, CI must run it - engineers ignore mismatched gates.
Treat skill output like a junior PR: Human review before merge; same bar as assisted code drafts.
Version skills in repo: Commit .cursor/skills/ or registry with semver note in changelog when guardrails change.
Refresh skills after postmortems: Every missed guardrail becomes a new bullet - rerun verification commands on refresh.
Module repo .cursor/skills/ for project-specific conventions; org registry for shared audit and incident playbooks. Always pin Go version.
Skill may draft go get commands - human approves before merge. Guardrails block auto-merge on dependency PRs.
Skills reference the same linter set CI enforces. Do not suggest //nolint without ADR exception path.
No. Skills accelerate checklists; human reviewers own merge authority and architecture judgment.
After Go minor bump, linter config change, framework ADR update, or postmortem action item. Re-run go test and govulncheck in verification section on refresh.
Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).
Reviewed by Chris St. John·Last updated Jul 16, 2026