README.md

Curated Go skills for AI coding agents. One command, works everywhere.

npx skills add eduardo-sl/go-agent-skills

🚀 Install

Works with Claude Code, Cursor, Codex, GitHub Copilot, Windsurf, OpenCode, Cline, and 37+ more agents via the npx skills CLI.

# Everything, interactive — picks up the agents you have installed
npx skills add eduardo-sl/go-agent-skills

# Look before you leap
npx skills add eduardo-sl/go-agent-skills --list

# Just the ones you want
npx skills add eduardo-sl/go-agent-skills --skill go-code-review --skill go-defensive-coding

# Globally, for every project
npx skills add eduardo-sl/go-agent-skills -g

# Non-interactive, for CI
npx skills add eduardo-sl/go-agent-skills --all -y

/plugin marketplace add eduardo-sl/go-agent-skills
/plugin install go-agent-skills@eduardo-sl

npx skills add eduardo-sl/go-agent-skills -a cursor

npx skills add eduardo-sl/go-agent-skills -a copilot

npx skills add eduardo-sl/go-agent-skills -a codex

npx skills add eduardo-sl/go-agent-skills -a windsurf
npx skills add eduardo-sl/go-agent-skills -a opencode
npx skills add eduardo-sl/go-agent-skills -a cline

git clone https://github.com/eduardo-sl/go-agent-skills.git
./go-agent-skills/scripts/install.sh /path/to/your-go-project --agent claude

# See what it would do first
./go-agent-skills/scripts/install.sh /path/to/project --agent claude --dry-run

# Symlink instead of copy, to stay in sync with the repo
./go-agent-skills/scripts/install.sh /path/to/project --agent claude --symlink

mkdir -p .claude/skills && cp -r go-agent-skills/skills/*/* .claude/skills/   # Claude Code
mkdir -p .cursor/skills && cp -r go-agent-skills/skills/*/* .cursor/skills/   # Cursor
mkdir -p .github/skills && cp -r go-agent-skills/skills/*/* .github/skills/   # Copilot
mkdir -p .agents/skills && cp -r go-agent-skills/skills/*/* .agents/skills/   # Codex / OpenCode

npx skills check      # anything out of date?
npx skills update     # bring them current
npx skills list       # what is installed
npx skills remove go-performance-review

🗺 The map

                            ┌───────────────────────────┐
                            │      go-skills-router     │  ← "which skill is this?"
                            └─────────────┬─────────────┘
                                          │
   ┌──────────────┬──────────────┬────────┴─────┬──────────────┬──────────────┐
   ▼              ▼              ▼              ▼              ▼              ▼
┌────────────┐┌────────────┐┌────────────┐┌────────────┐┌────────────┐┌────────────┐
│Code Quality││Architecture││   Data     ││Safety&Perf ││  Testing   ││  Workflow  │
├────────────┤├────────────┤├────────────┤├────────────┤├────────────┤├────────────┤
│coding-stds ││arch-review ││ database   ││concurrency ││test-quality││ dep-audit  │
│code-review ││proj-layout ││            ││  -review   ││test-table  ││ ci         │
│error-handl ││iface-design││            ││security    ││  -driven   ││ refactoring│
│context     ││api-design  ││            ││  -audit    ││            ││ semantic   │
│modernize   ││openapi     ││            ││defensive   ││            ││  -tools    │
│data-structs││graphql     ││            ││  -coding   ││            ││ binary-size│
│docs        ││grpc        ││            ││performance ││            ││ skills     │
│            ││design-patt ││            ││  -review   ││            ││  -router   │
│            ││dep-inject  ││            ││observabil. ││            ││ git-commit │
│            ││cli         ││            ││troublesh.  ││            ││            │
└────────────┘└────────────┘└────────────┘└────────────┘└────────────┘└────────────┘

Unsure which one applies? That is what go-skills-router is for — it maps a task to the skill that owns it, and draws the boundary when two overlap.

📊 Catalogue

Skills load automatically from context. You can also invoke one directly: /go-code-review.

Reading the columns. Desc is the description weight, loaded at startup for every skill — it is what makes a skill trigger. SKILL.md is what loads when one fires. Tree includes the references/ files, which load only when the skill sends the agent to them. 📚 marks a skill with reference files. All figures are approximate tokens (bytes ÷ 4).

Code Quality

Architecture & Design

Data

Safety & Performance

Testing

Workflow

Budget. All 33 descriptions together are ~4,420 tokens at startup — the only figure paid on every request, Go work or not. A typical session fires 2–4 skills, so ~5,300 tokens of body. The full tree is ~75,700 tokens and is never loaded at once; that gap is the point of progressive disclosure.

🧪 Evaluations

A skill that does not change the output is a skill that costs context for nothing. evals/ is the harness that tells the difference:

scripts/run-evals.py --cmd 'claude -p "{prompt}"' --label with-skills
scripts/run-evals.py --cmd 'claude -p "{prompt}"' --label baseline

Same suite, run in a project with the skills and in one without. The delta is the measurement.

One suite measures something else: go-skills-router asserts which skill a task should route to. With 33 overlapping triggers, picking the wrong skill costs more than any description does. Case format and guidance: evals/README.md.

🔐 Security

Skills are prompts injected into an agent that already holds shell and file-write access. This repo treats them as security-sensitive:

• Every skill declares least-privilege allowed-tools. Review and audit skills cannot write. Every Bash(...) grant is scoped to one binary.
• No skill fetches remote content or runs downloaded code. The only external hosts referenced anywhere in skills/ are github.com and localhost.
• scripts/validate.sh rejects unscoped Bash, and rejects any skill that declares itself read-only while asking for Write.
• Published skills are scanned by skills.sh (Socket, Snyk, Gen Agent Trust Hub).

Threat model and private disclosure: SECURITY.md.

🧱 Repository structure

go-agent-skills/
├── skills/(category)/skill-name/
│   ├── SKILL.md                    # ≤250 lines: procedure, patterns, checklist
│   └── references/                 # depth, loaded only when SKILL.md says so
├── evals/
│   ├── README.md                   # how to measure a skill's worth
│   └── cases/                      # prompt + assertion suites
├── scripts/
│   ├── install.sh                  # shell installer (--dry-run, --symlink)
│   ├── run-evals.py                # drives any agent CLI
│   └── validate.sh                 # format, frontmatter, tools, catalogue sync
├── docs/
│   ├── SKILL_GUIDELINES.md         # quality bar for authoring
│   └── skill-gap-analysis.md       # what exists, what was rejected, and why
│
│  # platform discovery — all must list the same skills, and CI checks it
├── AGENTS.md · CLAUDE.md · .claude-plugin/marketplace.json
├── .cursor/rules/ · .windsurf/rules/ · .clinerules · .github/copilot-instructions.md
└── .opencode/config.json

🎯 Design principles

Written for agents, not readers. Imperative steps, ✅/❌ contrast pairs, and a verification checklist that closes every skill. Agents learn from contrast, not prose.

Negative triggers earn their keep. Every description states what the skill does not cover and names the one that does. Wrong-skill activation is more expensive than no activation.

Verification is executable. Where a tool can prove a rule — go vet, golangci-lint, govulncheck, go test -race — the skill runs it instead of asking the agent to judge.

Progressive disclosure. SKILL.md stays under 250 lines — CI warns above it, fails at 500. Depth lives in references/ and loads only on demand.

Self-contained. No skill requires another to have been loaded. They name each other as pointers only. go-skills-router is the one index, and it is optional too.

🎚 Tuning triggers

If a skill fires too often, or never fires when it should, the description field is the lever — it is the entire triggering mechanism. Open an issue with the prompt that misrouted and the skill you expected. Small wording changes move trigger accuracy a lot.

Adapting to your team's conventions: fork it, edit the SKILL.md files, install from your fork with npx skills add your-org/go-agent-skills. Common customisations are the golangci-lint ruleset, import grouping, and preferred libraries.

✍️ Contributing

Budget, per skill:

Every PR must pass ./scripts/validate.sh and ship at least one eval case that fails without the skill. Full guidelines: CONTRIBUTING.md and docs/SKILL_GUIDELINES.md.

🙏 Standing on

• Uber Go Style Guide — the base for most conventions
• Effective Go — official Go team guidance
• Go Code Review Comments — community review standards
• Agent Skills — the open skill specification
• Vercel Skills CLI — the npx skills distribution ecosystem
• Anthropic Skills — patterns for production-grade skills

The Go gopher was designed by Renée French and is licensed CC BY 3.0. The banner above is an original drawing in that spirit.

📝 License

MIT © Eduardo Spinelli de Lima