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//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:

| Placeholder | Replace with | |---|---| | __CLI_NAME__ | final binary name, for example acme | | __NPM_PACKAGE_NAME__ | npm package, for example @org/acme | | __GITHUB_REPO__ | owner/repo | | __RELEASE_ENV_PREFIX__ | uppercase env prefix without trailing underscore, for example ACME | | __GO_VERSION_FILE__ | Go version file, usually go.mod | | __GO_MAIN_PACKAGE__ | build package, for example ./cmd/acme | | __SKILL_NAME__ | bundled skill directory name under skills/ |

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 entrypoint
internal/          private implementation
e2e/               end-to-end tests
scripts/           install, smoke, release checks
.github/workflows/ CI and release automation
skills//     Agent Skill content only

Rules:

• Do not put .go files under skills/.
• Do not duplicate skills//SKILL.md under internal/.
• If the CLI reads skills, keep reader and locator code under internal/skillcontent.
• Let npm scripts/run.js set _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:

 skills list --json
 skills read 
 skills read  --json
 skills read / --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:

| Trigger | First action | If still failing | |---|---|---| | Placeholder scan finds __...__ | Replace all placeholders in copied templates | Remove unused template files or document intentionally literal placeholders | | npm run pack:check omits skills/** | Add skills/** to package.json.files | Inspect npm pack --json --dry-run output and fix path roots | | skills list/read fails from npm wrapper | Check _SKILLS_DIR in scripts/run.js and package contents | Run the installed wrapper from a fresh prefix and inspect its environment | | Checksum mismatch | Regenerate SHA256SUMS from flattened release artifacts | Stop release; rebuild artifacts from the exact tag | | NPM_TOKEN missing | Add repository secret before tagging | Publish GitHub Release only after deciding whether npm publish is in scope | | npm publish permission denied | Confirm package name, scope ownership, and publishConfig.access | Rename package or request scope access before retrying | | Git tag and package version differ | Move the tag or update version sources before release | Delete the bad tag only after user confirmation | | CI passes locally but fails in workflow | Reproduce the exact workflow command locally | Align Go, Node, CGO, cache, and lint versions |

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

Agent Skill Packaging

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

Recommended README command:

npx skills add /

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: geekjourneyx
• Source: geekjourneyx/go-cli-ship
• License: MIT

Install and usage instructions live in the source repository linked above.