golang-spf13-viper Skill for Claude: What It Does and How to Install It

Makes Claude load Go configuration with spf13/viper in the right order: flags, then env vars, then files, then defaults.

Installs: 37.6K; on skills.sh
Stars: 3.7K; on GitHub
Files: 6; besides SKILL.md
Updated: Nov 2026; last repo commit

golang-spf13-viper gives Claude a checklist for viper, the Go library that answers "what is the value of this config key?". It covers the fixed precedence order, env var binding, binding cobra flags, Unmarshal with mapstructure tags, hot reload and test isolation.

It triggers when you use or adopt spf13/viper or when the code imports github.com/spf13/viper. The frontmatter lists go as the only required command.

Good for

Go developers reading config from flags, env vars and files
CLI authors who pair viper with cobra
Anyone debugging a config key that never resolves

Install golang-spf13-viper

Claude Code

Copy this prompt.

Install the golang-spf13-viper skill in Claude Code. Run this command:

npx skills add https://github.com/samber/cc-skills-golang --skill golang-spf13-viper

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

Golang configuration library using spf13/viper — layered precedence (flag > env > file > KV > default), BindPFlag/BindPFlags, SetEnvPrefix + SetEnvKeyReplacer + AutomaticEnv, ReadInConfig + ConfigFileNotFoundError, Unmarshal + mapstructure struct tags, Sub for sub-trees, WatchConfig + OnConfigChange for hot reload, viper.New() for test isolation, and remote KV integration. Apply when using or adopting spf13/viper, or when the codebase imports `github.com/spf13/viper`. For CLI command structure alongside viper, see the `samber/cc-skills-golang@golang-spf13-cobra` skill. For general CLI architecture, see `samber/cc-skills-golang@golang-cli`.

Sections in SKILL.md

Viper vs. cobra
The precedence pipeline
Sources and config files
Env binding and key replacers
Flag binding (the cobra seam)
Unmarshaling into structs
Sub-trees
Hot reload
Test isolation
Best Practices
Common Mistakes
Further Reading
Cross-References

Key facts

Author: samber
Repository: samber/cc-skills-golang
Installs on skills.sh: 37,621 as of 2026-11-02
GitHub stars: 3,749 for the whole samber/cc-skills-golang repo, 2026-11-02
License: MIT (SKILL.md frontmatter)
Last commit to the repo: 2026-11-01
What is inside: 7 files including SKILL.md: evals/evals.json and 5 reference guides (binding-and-env, sources-and-formats, testing-and-isolation, unmarshal, watch-and-reload)
Version: 1.1.2 (SKILL.md frontmatter)
Works in: Frontmatter says: "Designed for Claude Code, Codex or similar harness, and for projects using Golang."
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk pass

What it includes

Set, flag, env, config file, remote KV, default
The skill states viper walks sources in a fixed order and that the order cannot be changed. Claude uses it to explain why a file value is hidden by an env var or a flag default.
Read · Precedence pipeline
ReadInConfig, ConfigFileNotFoundError, MergeInConfig
Claude handles a missing config file gracefully and only returns real read errors. The sources-and-formats guide covers file formats and remote KV.
Write · Sources and config files
SetEnvPrefix, SetEnvKeyReplacer and AutomaticEnv together
The skill calls this the highest-bug-density area. All three settings must be wired together or nested keys such as database.host do not resolve.
Write · Env binding with prefix and key replacer
BindPFlag in init or PersistentPreRunE, never in RunE
Claude binds cobra flags before Execute runs so the bindings are not missed.
Write · Flag binding (the cobra seam)
Unmarshal and UnmarshalKey with mapstructure tags
Claude adds explicit mapstructure tags and prefers UnmarshalKey over Sub, which returns nil when the key is missing.
Write · Unmarshal into structs
WatchConfig and OnConfigChange
The skill warns that editors that save by renaming a file, such as vim, can stop the callback from firing. Test with an append instead of an editor save.
Write · Hot reload
viper.New() per test instead of the global instance
Claude creates a fresh viper per test so state does not leak between cases.
Write · Test isolation

From the official docs

Permissions

Low risk

Claude can edit your Go files and run go and git commands in your project. Review the diff before you commit.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It can edit your config code and run go commands
Hot reload and env binding changes touch startup code. Commit first and run your tests after. github.com
It shows a go get command for viper
The SKILL.md code block shows go get github.com/spf13/viper@latest, which adds or updates viper in your go.mod. Run it yourself if you prefer to control versions. github.com

Technical details

Turning on read-only	No read-only switch is documented in SKILL.md.
Talks to	WebFetch and the Context7 documentation tools appear in allowed-tools
Scopes	allowed-tools: Read, Edit, Write, Glob, Grep, Agent, WebFetch, LSP Bash limited to go, golangci-lint, git, godig and gopls

Questions

What does golang-spf13-viper do?

It teaches Claude to write and review viper code for Go: precedence, env binding, flag binding, Unmarshal, hot reload and test isolation. It bundles no scripts; viper itself defines no commands or flags.

How do I install golang-spf13-viper?

Use the install box at the top of this page. The README says the Go skills are designed as cross-referencing units, so installing only a subset gives a partial view of the guidelines.

Does it need anything installed besides Go?

The frontmatter lists only the go command as required. The Go library itself comes from your own go.mod.

Is golang-spf13-viper safe to use?

It bundles no scripts. Its allowed-tools line lets Claude read and edit files, run go, golangci-lint, git, godig and gopls commands, and fetch web pages. Review the diff before you commit.

Why does my nested env var not resolve?

The skill says the usual cause is using AutomaticEnv without SetEnvKeyReplacer, so database.host is looked up with the dot kept. Set the prefix, the replacer and AutomaticEnv together.

Do I need viper with cobra?

The skill says cobra alone fits flag-only CLIs, viper alone fits config-file daemons, and both together fit when you bind flags to config. The repo has a separate golang-spf13-cobra skill for the cobra side.

Information

updated Nov 2, 2026

Repository: samber/cc-skills-golang
Folder: skills/golang-spf13-viper

samber/cc-skills-golang skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 2

golang-spf13-viper SKILL.md · github.com
samber/cc-skills-golang README · github.com