Go CLI Ship

Go CLI Ship

Use this skill to turn a Go CLI into a reproducible product: stable command contract, testable implementation, npm installer, GitHub Release artifacts, concise README, optional Agent Skill package, and release gates that prevent drift.

First Principles

• Treat the CLI as an automation API, not only a terminal UI.
• Keep stdout for results, stderr for diagnostics, and exit codes stable.
• Make JSON output additive and backward compatible.
• Make release repeatable: one version, one tag, verified artifacts, tested installer.
• Keep skills/ as content only. Put Go code in internal/, not under Agent Skill folders.
• Keep README and SKILL.md operational. Remove internal paths, release process noise, and maintenance notes unless the target user needs them.

Reject These Anti-Patterns

• Do not use labels like "Unix-friendly" or "Agent Native" as decoration. Convert them into concrete contracts: stable stdout/stderr, exit codes, JSON, noninteractive commands, and repeatable install flows.
• Do not put source code, generated files, changelog notes, or repository maintenance instructions inside skills/.
• Do not copy skills/<name>/SKILL.md into internal/ or any other second source of truth. Runtime code should read the packaged or repository skills/ directory.
• Do not publish a release after changing install behavior unless npm install, GitHub Release artifacts, checksum verification, and optional skills list/read all pass from a fresh environment.
• Do not make README or SKILL.md explain the whole architecture when the user only needs to install, configure, run, and verify the CLI.
• Do not rely on local success alone. CI must run the same gates, and release workflows must verify the packaged artifact.

Start Here

Before changing a project:

git status --short
go version
npm --version

Identify:

• CLI binary name.
• Go module and main package.
• npm package name.
• GitHub repo.
• target OS/ARCH matrix.
• whether the CLI ships an Agent Skill.
• whether the CLI should expose skills list/read.

Template Replacement Protocol

When copying files from templates/, replace every placeholder before running tests:

After replacing placeholders, run:

rg "__[A-Z0-9_]+__" .
node -c scripts/install.js
node -c scripts/run.js
bash -n scripts/release-check.sh

If rg "__[A-Z0-9_]+__" . returns any template placeholder, stop and replace it before continuing.

Required Project Shape

Use this baseline unless the existing repository has stronger conventions:

cmd/<cli>/          CLI entrypoint
internal/          private implementation
e2e/               end-to-end tests
scripts/           install, smoke, release checks
.github/workflows/ CI and release automation
skills/<name>/     Agent Skill content only

Rules:

• Do not put .go files under skills/.
• Do not duplicate skills/<name>/SKILL.md under internal/.
• If the CLI reads skills, keep reader and locator code under internal/skillcontent.
• Let npm scripts/run.js set <PREFIX>_SKILLS_DIR to the package skills/ directory when present.
• Let local development read the repository skills/ directory.

CLI Contract

Define these before implementation:

• commands and subcommands.
• human output versus --json output.
• stable error and exit codes.
• config precedence: flags, environment, config file, defaults.
• compatibility policy for new fields and flags.

Prefer explicit commands and flags over hidden global state, background daemons, caches, or browser scraping.

Required Agent Skill Commands

When a CLI ships an Agent Skill under skills/, add these commands:

<cli> skills list --json
<cli> skills read <name>
<cli> skills read <name> --json
<cli> skills read <name>/<path> --json

Contract:

• skills list returns JSON with version, skills, and count.
• skills read returns raw Markdown by default.
• skills read --json returns version, skill, path, content, and optional guidance.
• reject absolute paths, .., backslashes, directories, and unknown skills.
• tests cover list, read, JSON read, unknown skill, and path traversal.

Use templates/go/internal/skillcontent/ as the starting point, then wire it into the CLI parser.

If the CLI intentionally ships skills/ without skills list/read, remove the corresponding release-check assertions and document why. Do not leave the default checks failing.

Quality Gates

Every production CLI should expose:

make release-check

The gate should cover:

• version consistency.
• required files.
• README install command.
• npm package metadata and npm run pack:check.
• gofmt -l ..
• go vet ./....
• go test -count=1 ./....
• locked golangci-lint.
• no Go files under skills/.
• if skills/ exists: README documents npx skills add, package.json includes skills/**, and the release smoke test exercises skills list/read when available.

If local sandboxing blocks Go cache or httptest, rerun with a writable GOCACHE or with the same permissions CI has. Do not mark the gate green without a real command result.

Failure Handling

Use this table instead of guessing through release failures:

Version Checks

Before tagging a release, align all version sources:

• package.json version.
• Makefile version when present.
• CLI version variable or ldflags value.
• top CHANGELOG.md entry.
• Git tag vX.Y.Z.
• GitHub Actions GITHUB_REF_NAME when running in CI.

Release checks should fail fast on drift. A patch release is required after changing published install behavior, package contents, or release workflow outputs.

npm Distribution

Recommend npm for developer installation:

npm install -g <package-name>
<cli-name> version

The npm package is a thin wrapper:

• package.json declares bin, files, postinstall, pack:check, and publishConfig.access.
• scripts/install.js downloads the matching GitHub Release archive and verifies SHA256SUMS.
• scripts/run.js forwards args, stdio, and exit code to the real binary.
• no binary is committed to git or packed from the working tree.
• first publish does not require manually creating the npm package; npm publish --access public creates it when the account or scope has permission.

If the project ships an Agent Skill, include skills/** in the npm package and let scripts/run.js set <PREFIX>_SKILLS_DIR.

Agent Skill Packaging

Use Agent Skills for agent instructions, not project maintenance documentation.

Recommended README command:

npx skills add <owner>/<repo>

Skill rules:

• SKILL.md frontmatter contains only name and description.
• Body is concise, procedural, and English unless the project explicitly requires another language.
• Body describes how to use the CLI, not how to maintain the repository.
• Do not include changelogs, internal source paths, release process, or test commands unless the skill is specifically for development work.
• Keep skills/<name>/ free of Go code and generated binaries.

Release Automation

Use tag-triggered release workflow:

CHECKPOINT - STOP before pushing a release tag. Confirm with the user:

• final version and tag.

• npm package name and access.

• GitHub repository target.

• NPM_TOKEN is configured when npm publish is in scope.

• make release-check passed from the current commit.

• fresh npm install smoke test passed when install behavior changed.

• trigger: push.tags: v*.

• build linux, darwin, and windows for amd64 and arm64 when supported.

• inject version from the tag.

• archive README.md, LICENSE, CHANGELOG.md, and skills/ when present.

• generate SHA256SUMS from flattened artifacts.

• smoke-test npm install on Linux and Windows before publishing.

• if the CLI supports skills list/read, smoke-test those commands from the npm-installed wrapper.

• publish GitHub Release before npm.

• publish npm with NPM_TOKEN after version-tag validation.

README Standard

First screen should answer:

• what is this CLI?
• who is it for?
• how do I install it?
• what is the fastest useful command?

Keep README practical. Avoid internal architecture unless users need it to operate the CLI.

Delivery Report

When finishing work, report:

• scope changed.
• important files changed.
• commands run and results.
• known risks or skipped checks.
• whether the work was committed, tagged, or only left in the worktree.