Agent Skills Best Practices

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.

FAQs

Where should SKILL.md files live?

Module repo .cursor/skills/ for project-specific conventions; org registry for shared audit and incident playbooks. Always pin Go version.

Should agents edit go.mod without human approval?

Skill may draft go get commands - human approves before merge. Guardrails block auto-merge on dependency PRs.

How do skills relate to golangci-lint config?

Skills reference the same linter set CI enforces. Do not suggest //nolint without ADR exception path.

Can skills replace code review?

No. Skills accelerate checklists; human reviewers own merge authority and architecture judgment.

When is a skill stale?

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.

Agent Skills for Go Teams - conceptual overview
Agent Skills Basics - SKILL.md anatomy with ten examples
Go API Design Review Skill - handler review
Go Concurrency Review Skill - goroutine audits
Go Module & Security Audit Skill - govulncheck workflow
Go Performance Profiling Skill - pprof workflow
Go Testing & Benchmark Skill - test scaffolding
Go Kubernetes Operator Review Skill - operator audit
WASM & TinyGo Build Review Skill - WASM builds

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).

Agent Skills Best Practices

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.

FAQs

Where should SKILL.md files live?

Module repo .cursor/skills/ for project-specific conventions; org registry for shared audit and incident playbooks. Always pin Go version.

Should agents edit go.mod without human approval?

Skill may draft go get commands - human approves before merge. Guardrails block auto-merge on dependency PRs.

How do skills relate to golangci-lint config?

Skills reference the same linter set CI enforces. Do not suggest //nolint without ADR exception path.

Can skills replace code review?

No. Skills accelerate checklists; human reviewers own merge authority and architecture judgment.

When is a skill stale?

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).

Agent Skills Best Practices

FAQs

Related

Search Documentation

Agent Skills Best Practices

FAQs

Related