Agent Skills Basics

What a Go SME Agent Skill contains and when to invoke it - ten examples for teams using AI assistants on Go 1.26.x. These pages document skills, not application code. A skill is a SKILL.md playbook your agent reads before acting.

Prerequisites

Skills live in your repo (or team skill registry) beside the module they govern:

.cursor/skills/
├── go-api-design-review/
│   └── SKILL.md
├── go-concurrency-review/
│   └── SKILL.md
├── go-module-audit/
│   └── SKILL.md
└── go-testing-benchmark/
    └── SKILL.md

Pin the stack in every skill header so agents never drift to outdated APIs:

## Stack pin
- Go 1.26.x (verify patch at build)
- golangci-lint (team linter set)
- HTTP: stdlib net/http per ADR-014 (or chi - verify at build)

Scope: Skills orchestrate how an agent should work. Human-readable cookbooks in net/http Basics, Go Testing Basics, and Go Security Basics remain the authoritative reference.

Basic Examples

1. What an Agent Skill Is

An Agent Skill is a structured instruction file - typically SKILL.md - that tells an AI assistant what to do, what to ask for, and what not to do on a Go task.

Skill artifact	Purpose
`SKILL.md`	Trigger phrases, inputs, outputs, guardrails
`references/`	Optional deep links to internal ADRs or runbooks
`examples/`	Invocation prompts that passed review

Skills are not feature tutorials - they are operational contracts for assisted development
Skills should be Go-pinned - agents hallucinate pre-1.22 routing without explicit version context
One skill = one decision domain (concurrency review, module audit, API design, operator RBAC)

2. Minimum SKILL.md Structure

Every Go skill should open with the same skeleton:

# Go API Design Review Skill
 
## What this skill does
Reviews net/http handlers for context, errors, and status codes.
 
## When to invoke
- Before merging handler changes
- When scaffolding a new REST package
- When agent drafts middleware chains
 
## Inputs (required)
- go.mod, affected packages, team error-handling ADR
- Router choice: stdlib ServeMux vs chi/gin
 
## Outputs
- Review checklist with file:line findings
- Suggested fixes (no auto-merge)
- Verification: go test ./..., golangci-lint run
 
## Guardrails
- Never remove context deadlines on outbound calls
- Never return 500 for validation errors
- Never disable linters without ADR exception
 
## Stack pin
Go 1.26.x · golangci-lint · net/http (ADR-014)
 
## Example prompts
See §10 below.

Inputs prevent the agent from guessing module path or skipping ADR links
Outputs must be verifiable - commands, not prose
Guardrails are the highest-value section - agents over-refactor without them

3. When to Invoke vs When to Read Docs

Situation	Use a skill	Read human docs
"Review this handler PR"	Go API Design Review Skill	HTTP Servers, Handlers & ServeMux
"Audit goroutines in worker pool"	Go Concurrency Review Skill	Concurrency Basics
"Run govulncheck before release"	Go Module & Security Audit Skill	Dependency Scanning with govulncheck
"Profile latency regression"	Go Performance Profiling Skill	CPU and Heap Profiling with pprof
"Scaffold table-driven tests"	Go Testing & Benchmark Skill	Table-Driven Tests and Subtests

Invoke skills at decision points where wrong automation is expensive
Read docs when learning concepts - skills assume you want an executable plan now

4. Inputs the Agent Must Collect

Before executing, a well-written skill forces the agent to gather:

## Inputs checklist
- [ ] go.mod and go.sum (module path, Go version directive)
- [ ] Affected packages (`./internal/api/...`)
- [ ] Team ADRs for errors, logging, auth
- [ ] CI commands (test, lint, race, vuln)
- [ ] Framework choice if not stdlib (chi, gin, echo, gRPC)
- [ ] Incident context (if triage): pprof snapshot, goroutine dump path

Missing module path breaks import suggestions and test commands
Missing ADR links produces generic error handling that conflicts with team policy
Agents should paste collected values back to the human for confirmation before destructive commands

5. Outputs You Should Expect

A skill run should end with concrete deliverables:

Output type	Example
Command sequence	`go test -race ./internal/api/...`
Review checklist	Handler missing `r.Context()` on DB call at `handler.go:42`
Config diff	Suggested `golangci-lint` exclude only with ADR reference
Test scaffold	Table-driven subtests from acceptance criteria
Decision tree	OTA vs binary N/A for Go - use deploy rollback ADR instead

No output = failed skill - reject agent responses that only summarize docs
Outputs should reference verification - go test, govulncheck, golangci-lint run
For services, always include go vet ./... when agents touch concurrency or unsafe patterns

6. Guardrails Every Go Skill Needs

Copy these defaults into each SKILL.md:

## Guardrails (Go 1.26)
1. Use `go get` with team MVS policy - never blind `go get -u ./...`.
2. Propagate `r.Context()` to all outbound I/O (DB, HTTP, gRPC).
3. Return typed errors; map to HTTP status in one layer only.
4. Run `go test -race` when skill touches goroutines or shared state.
5. Run `govulncheck ./...` before suggesting dependency merges.
6. Do not disable golangci-lint rules without ADR exception.
7. Operator changes require RBAC manifest review before apply.

Guardrails convert agent enthusiasm into engineering discipline
Pair with Agent Skills Best Practices for team-wide rules

7. Go 1.26 Pinning in Skills

Agents default to training-data versions. Pin explicitly:

## Stack pin (required)
| Tool | Version |
| --- | --- |
| go | 1.26.x (verify patch) |
| golangci-lint | team config (verify at build) |
| HTTP router | stdlib ServeMux (Go 1.22+ patterns) |
 
## Go 1.26 specifics
- Green Tea GC default - profile before assuming GOGC tweaks needed.
- `go fix` modernizers available - skill should not fight automated fixes.
- ServeMux supports `GET /users/{id}` - prefer stdlib unless ADR mandates chi/gin.

Re-pin skills on every Go minor bump - stale skills are worse than no skills
Cross-check agent output with go test ./... and golangci-lint run

8. Skill Composition (Don't Duplicate Docs)

Skills delegate to human docs; they don't replace them:

## References (read, don't rewrite)
- HTTP: ../net-http/net-http-basics.md
- Context: ../context-package/context-basics.md
- Testing: ../testing-benchmarking/table-driven-tests-and-subtests.md
- Security: ../security/dependency-scanning-with-govulncheck-and-sbom.md

Skill output = plan + commands + gates
Doc output = concepts + edge cases + FAQs
Link both directions: skills point to docs; docs can say "invoke X skill for assisted review"

9. Verifying Skill Output

After any skill-assisted change:

# Unit and race gate
go test ./...
go test -race ./internal/...
 
# Static analysis
go vet ./...
golangci-lint run
 
# Security (before dependency merges)
govulncheck ./...

Check	Catches
`go test -race`	Data races, bad goroutine shutdown
`golangci-lint run`	Style, errcheck, context leaks per team config
`govulncheck`	Known vulns in module graph
`go vet`	Common mistakes (printf, struct tags)

Treat skill output like a junior engineer PR - review before merge
CI should run the same gates - see GitHub Actions for Go Repos

10. Example Invocation Prompts

net/http handler review:

Use the Go API Design Review skill. Stack: Go 1.26, stdlib ServeMux.
Inputs: PR diff for internal/api/handlers.go attached.
Review context propagation, error mapping, and status codes.
Guardrails: no auto-merge; output checklist with line refs.

Concurrency audit:

Use the Go Concurrency Review skill.
Package: ./internal/worker/...
Check goroutine lifecycle, channel close rules, and context cancel.
Include go test -race command for affected packages.

Module security sweep:

Use the Go Module & Security Audit skill.
Run govulncheck ./... and summarize actionable CVEs.
Propose go get pins only - human approves before merge.

Profiling workflow:

Use the Go Performance Profiling skill.
Symptom: p99 latency doubled on /api/orders.
Inputs: CPU pprof from staging attached.
Give measure-profile-optimize steps; no premature micro-opts.

Operator review:

Use the Go Kubernetes Operator Review skill.
Review reconciler diff: finalizers, owner refs, RBAC markers.
Flag any cluster-scoped RBAC without ADR approval.

FAQs

Are Agent Skills the same as go generate directives?

No. go generate runs build-time tools. Agent Skills instruct AI assistants how to perform team workflows safely. You may invoke a review skill to audit generated code - different layers.

Should skills live in the module repo or a central registry?

Module repo for project-specific go.mod and handler conventions. Central registry for org-wide module policy and incident playbooks. Always pin Go version in both.

Can one SKILL.md cover the entire Go stack?

Avoid it. Split by decision domain so guardrails stay sharp. A monolithic skill dilutes concurrency boundaries and produces unsafe dependency bumps.

Do skills replace on-call runbooks?

No. Skills accelerate drafting checklists and commands. Human runbooks in Production Troubleshooting Basics own production authority.

How often should we refresh skills?

Every Go minor bump, every golangci-lint config change, and after any postmortem that reveals a missed guardrail. Run verification commands in the skill on refresh.

Agent Skills for Go Teams - conceptual overview
Go API Design Review Skill - handler review cookbook
Go Concurrency Review Skill - goroutine audits
Go Module & Security Audit Skill - govulncheck workflow
Go Testing & Benchmark Skill - table-driven scaffolding
Agent Skills Best Practices - 25-item team summary
net/http Basics - human reference for handlers

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 Basics

Prerequisites

Skills live in your repo (or team skill registry) beside the module they govern:

.cursor/skills/
├── go-api-design-review/
│   └── SKILL.md
├── go-concurrency-review/
│   └── SKILL.md
├── go-module-audit/
│   └── SKILL.md
└── go-testing-benchmark/
    └── SKILL.md

Pin the stack in every skill header so agents never drift to outdated APIs:

## Stack pin
- Go 1.26.x (verify patch at build)
- golangci-lint (team linter set)
- HTTP: stdlib net/http per ADR-014 (or chi - verify at build)

Scope: Skills orchestrate how an agent should work. Human-readable cookbooks in net/http Basics, Go Testing Basics, and Go Security Basics remain the authoritative reference.

Basic Examples

1. What an Agent Skill Is

An Agent Skill is a structured instruction file - typically SKILL.md - that tells an AI assistant what to do, what to ask for, and what not to do on a Go task.

Skill artifact	Purpose
`SKILL.md`	Trigger phrases, inputs, outputs, guardrails
`references/`	Optional deep links to internal ADRs or runbooks
`examples/`	Invocation prompts that passed review

Skills are not feature tutorials - they are operational contracts for assisted development
Skills should be Go-pinned - agents hallucinate pre-1.22 routing without explicit version context
One skill = one decision domain (concurrency review, module audit, API design, operator RBAC)

2. Minimum SKILL.md Structure

Every Go skill should open with the same skeleton:

# Go API Design Review Skill
 
## What this skill does
Reviews net/http handlers for context, errors, and status codes.
 
## When to invoke
- Before merging handler changes
- When scaffolding a new REST package
- When agent drafts middleware chains
 
## Inputs (required)
- go.mod, affected packages, team error-handling ADR
- Router choice: stdlib ServeMux vs chi/gin
 
## Outputs
- Review checklist with file:line findings
- Suggested fixes (no auto-merge)
- Verification: go test ./..., golangci-lint run
 
## Guardrails
- Never remove context deadlines on outbound calls
- Never return 500 for validation errors
- Never disable linters without ADR exception
 
## Stack pin
Go 1.26.x · golangci-lint · net/http (ADR-014)
 
## Example prompts
See §10 below.

Inputs prevent the agent from guessing module path or skipping ADR links
Outputs must be verifiable - commands, not prose
Guardrails are the highest-value section - agents over-refactor without them

3. When to Invoke vs When to Read Docs

Situation	Use a skill	Read human docs
"Review this handler PR"	Go API Design Review Skill	HTTP Servers, Handlers & ServeMux
"Audit goroutines in worker pool"	Go Concurrency Review Skill	Concurrency Basics
"Run govulncheck before release"	Go Module & Security Audit Skill	Dependency Scanning with govulncheck
"Profile latency regression"	Go Performance Profiling Skill	CPU and Heap Profiling with pprof
"Scaffold table-driven tests"	Go Testing & Benchmark Skill	Table-Driven Tests and Subtests

Invoke skills at decision points where wrong automation is expensive
Read docs when learning concepts - skills assume you want an executable plan now

4. Inputs the Agent Must Collect

Before executing, a well-written skill forces the agent to gather:

## Inputs checklist
- [ ] go.mod and go.sum (module path, Go version directive)
- [ ] Affected packages (`./internal/api/...`)
- [ ] Team ADRs for errors, logging, auth
- [ ] CI commands (test, lint, race, vuln)
- [ ] Framework choice if not stdlib (chi, gin, echo, gRPC)
- [ ] Incident context (if triage): pprof snapshot, goroutine dump path

Missing module path breaks import suggestions and test commands
Missing ADR links produces generic error handling that conflicts with team policy
Agents should paste collected values back to the human for confirmation before destructive commands

5. Outputs You Should Expect

A skill run should end with concrete deliverables:

Output type	Example
Command sequence	`go test -race ./internal/api/...`
Review checklist	Handler missing `r.Context()` on DB call at `handler.go:42`
Config diff	Suggested `golangci-lint` exclude only with ADR reference
Test scaffold	Table-driven subtests from acceptance criteria
Decision tree	OTA vs binary N/A for Go - use deploy rollback ADR instead

No output = failed skill - reject agent responses that only summarize docs
Outputs should reference verification - go test, govulncheck, golangci-lint run
For services, always include go vet ./... when agents touch concurrency or unsafe patterns

6. Guardrails Every Go Skill Needs

Copy these defaults into each SKILL.md:

## Guardrails (Go 1.26)
1. Use `go get` with team MVS policy - never blind `go get -u ./...`.
2. Propagate `r.Context()` to all outbound I/O (DB, HTTP, gRPC).
3. Return typed errors; map to HTTP status in one layer only.
4. Run `go test -race` when skill touches goroutines or shared state.
5. Run `govulncheck ./...` before suggesting dependency merges.
6. Do not disable golangci-lint rules without ADR exception.
7. Operator changes require RBAC manifest review before apply.

Guardrails convert agent enthusiasm into engineering discipline
Pair with Agent Skills Best Practices for team-wide rules

7. Go 1.26 Pinning in Skills

Agents default to training-data versions. Pin explicitly:

## Stack pin (required)
| Tool | Version |
| --- | --- |
| go | 1.26.x (verify patch) |
| golangci-lint | team config (verify at build) |
| HTTP router | stdlib ServeMux (Go 1.22+ patterns) |
 
## Go 1.26 specifics
- Green Tea GC default - profile before assuming GOGC tweaks needed.
- `go fix` modernizers available - skill should not fight automated fixes.
- ServeMux supports `GET /users/{id}` - prefer stdlib unless ADR mandates chi/gin.

Re-pin skills on every Go minor bump - stale skills are worse than no skills
Cross-check agent output with go test ./... and golangci-lint run

8. Skill Composition (Don't Duplicate Docs)

Skills delegate to human docs; they don't replace them:

## References (read, don't rewrite)
- HTTP: ../net-http/net-http-basics.md
- Context: ../context-package/context-basics.md
- Testing: ../testing-benchmarking/table-driven-tests-and-subtests.md
- Security: ../security/dependency-scanning-with-govulncheck-and-sbom.md

Skill output = plan + commands + gates
Doc output = concepts + edge cases + FAQs
Link both directions: skills point to docs; docs can say "invoke X skill for assisted review"

9. Verifying Skill Output

After any skill-assisted change:

# Unit and race gate
go test ./...
go test -race ./internal/...
 
# Static analysis
go vet ./...
golangci-lint run
 
# Security (before dependency merges)
govulncheck ./...

Check	Catches
`go test -race`	Data races, bad goroutine shutdown
`golangci-lint run`	Style, errcheck, context leaks per team config
`govulncheck`	Known vulns in module graph
`go vet`	Common mistakes (printf, struct tags)

Treat skill output like a junior engineer PR - review before merge
CI should run the same gates - see GitHub Actions for Go Repos

10. Example Invocation Prompts

net/http handler review:

Use the Go API Design Review skill. Stack: Go 1.26, stdlib ServeMux.
Inputs: PR diff for internal/api/handlers.go attached.
Review context propagation, error mapping, and status codes.
Guardrails: no auto-merge; output checklist with line refs.

Concurrency audit:

Use the Go Concurrency Review skill.
Package: ./internal/worker/...
Check goroutine lifecycle, channel close rules, and context cancel.
Include go test -race command for affected packages.

Module security sweep:

Use the Go Module & Security Audit skill.
Run govulncheck ./... and summarize actionable CVEs.
Propose go get pins only - human approves before merge.

Profiling workflow:

Use the Go Performance Profiling skill.
Symptom: p99 latency doubled on /api/orders.
Inputs: CPU pprof from staging attached.
Give measure-profile-optimize steps; no premature micro-opts.

Operator review:

Use the Go Kubernetes Operator Review skill.
Review reconciler diff: finalizers, owner refs, RBAC markers.
Flag any cluster-scoped RBAC without ADR approval.

FAQs

Are Agent Skills the same as go generate directives?

No. go generate runs build-time tools. Agent Skills instruct AI assistants how to perform team workflows safely. You may invoke a review skill to audit generated code - different layers.

Should skills live in the module repo or a central registry?

Module repo for project-specific go.mod and handler conventions. Central registry for org-wide module policy and incident playbooks. Always pin Go version in both.

Can one SKILL.md cover the entire Go stack?

Avoid it. Split by decision domain so guardrails stay sharp. A monolithic skill dilutes concurrency boundaries and produces unsafe dependency bumps.

Do skills replace on-call runbooks?

No. Skills accelerate drafting checklists and commands. Human runbooks in Production Troubleshooting Basics own production authority.

How often should we refresh skills?

Every Go minor bump, every golangci-lint config change, and after any postmortem that reveals a missed guardrail. Run verification commands in the skill on refresh.

Agent Skills for Go Teams - conceptual overview
Go API Design Review Skill - handler review cookbook
Go Concurrency Review Skill - goroutine audits
Go Module & Security Audit Skill - govulncheck workflow
Go Testing & Benchmark Skill - table-driven scaffolding
Agent Skills Best Practices - 25-item team summary
net/http Basics - human reference for handlers

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 Basics

Search Documentation

Agent Skills Basics