cli-tool-template
Shared stack and consistency checklist for Filip's personal CLI tools (annoterm, wtree, devps) published through filipgutica/homebrew-tap. Use when creating a new CLI tool, adding a tool to the tap, or aligning an existing tool's repo, CI, release, or formula setup.
How do I install this agent skill?
npx skills add https://github.com/filipgutica/filip-stack --skill cli-tool-templateIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a standardized template for creating and maintaining personal CLI tools, including GitHub Actions workflows and release configurations. It follows security best practices for CI/CD and repository management.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
Personal CLI tool template
Every tool is one repo at ~/code/<tool> and github.com/filipgutica/<tool>, released by release-please and installed with brew install filipgutica/tap/<tool>. The tools are consistent when each item below holds. Language, CI steps, and README body vary by tool.
Stack
Releases use release-please on every tool. Merged PRs accumulate in a release PR, and merging that release PR tags and publishes the version. That gives one review point before each release. semantic-release is not used: it publishes on every merge, with no release PR.
Pick the language by what the tool needs, then follow that row. The reference tool in each row is the live implementation to copy from.
| Language | Pick when | Reference | Build and CI | release-please release-type (version source) | Formula |
|---|---|---|---|---|---|
| Rust | Interactive TUI, speed, or a native macOS bundle | annoterm | rust-toolchain.toml pin; cargo fmt --check, clippy -D warnings, test --locked | rust (Cargo.toml) | depends_on "rust" => :build; cargo install *std_cargo_args |
| TypeScript on Node | Git, GitHub, process, or JSON-heavy logic that wants npm packages and types | wtree, devps | npm with package-lock.json; npm ci, typecheck, test, build; Node 22 | node (package.json) | depends_on "node"; npm ci, npm run build, npm install *std_npm_args |
Repo contract
-
Files:
README.md, MITLICENSE,.gitignore,.github/workflows/{ci,pr-title,release}.yml,release-please-config.json,.release-please-manifest.json. release-please writesCHANGELOG.md. -
Workflows: copy
templates/release.ymlandtemplates/pr-title.ymlbyte for byte.ci.ymlis per language. It runs the tool's tests onmacos-latest, addsubuntu-latestwhen the tool supports Linux, and asserts that--versionmatches the manifest version. -
Release config: start from
templates/release-please-config.json. Setrelease-typetorustornode. -
CLI surface:
<tool> --versionand<tool> --help, with a one-line usage per command. -
README sections, in order: one-line summary and a sample output, Install (the brew command), Use, how it works and safety rules, Development (local check commands), Releases (one line pointing to Conventional PR titles).
-
Repo settings: these are not copied with the files. Set them on every new repo:
gh repo edit filipgutica/<tool> --enable-squash-merge --enable-merge-commit=false --enable-rebase-merge=false gh api -X PATCH repos/filipgutica/<tool> -f squash_merge_commit_title=PR_TITLE -f squash_merge_commit_message=PR_BODY gh api -X PUT repos/filipgutica/<tool>/actions/permissions/workflow -f default_workflow_permissions=read -F can_approve_pull_request_reviews=trueThe last command lets release-please open its release PR. Without it, the Release workflow fails with "GitHub Actions is not permitted to create or approve pull requests". The release PR gets no CI run, because PRs opened by
GITHUB_TOKENdo not trigger workflows.
Pages site
Each tool has one page at https://filipgutica.github.io/<tool>/. Start from a sibling tool's docs/site/, then replace its content, captures, links, and tests with the new tool's. Keep the page's look in @filipgutica/ui, not in the site.
- Stack: Astro with Vue in
docs/site/, with its ownpackage.jsonandpackage-lock.json. Copyastro.config.mjsandtsconfig.jsonbyte for byte, changing only the tool name. Pin@filipgutica/uito its latest release. - Frame: wrap the page in the library's
.fg-site-docsshell, withUiSiteHeader,UiSiteNav(label="On this page"), and.fg-site-footer. UseUiCapturefor terminal output,.fg-site-legendfor what the screen shows, and.fg-site-definitionsfor notes.src/styles/site.csskeeps the sibling's@layerand@importheader unchanged, then holds only page-specific rules. The library owns the frame, rail, footer, base type,kbd, the terminal palette, and every control: use its components, or its classes on a link that looks like a button, and add only layout in the site. - Sections, in order: intro (H1 that says what the tool does, one-line summary, install command, facts row), the capture, Commands, Keys, then tool-specific sections, and Good to know last. Facts are plain text, not badges. Good to know terms are noun phrases.
- Links: the header links to GitHub and Releases, and a "Full reference" link to the README closes the page. The footer links to the author, the Homebrew tap, issues, and Releases. Do not add a "Guide" link: the page is the guide.
- CI: copy
site-ci.ymlandpages.ymlbyte for byte, changing only the tool name.pages.ymldeploysmain. Both use Node 22 indocs/site. Site CI runsnpm ci,npm run check(astro checkandvue-tsc),npm run build,npx playwright install --with-deps chromium, andnpm run test:e2e. The Playwright tests cover phone and desktop widths and a no-JavaScript render.
Versioning
- The squash commit is the PR title plus the PR body. release-please reads only that:
fix:bumps patch,feat:bumps minor, and!in the title or aBREAKING CHANGE:footer in the body bumps major. Breaking markers inside the PR's own commits are lost when the PR is squashed. - Before 1.0, a breaking change goes to 1.0.0, because both
bump-*-pre-majoroptions arefalse. - Tags are
vX.Y.Z. First release: set the manifest to0.1.0, push thev0.1.0tag, and rungh release create v0.1.0. release-please takes over from there.
Homebrew tap
The tap is ~/code/homebrew-tap. Change it only through a PR, never by pushing to main.
A tool reaches users in this order: its release PR merges and tags vX.Y.Z; the tap's Update formulae workflow (every 6 hours, or run by hand) hashes the new archive and opens a formula PR; merging that PR ships brew upgrade <tool>. Adding a new tool:
- Add
Formula/<tool>.rb, modelled on the reference tool's formula from the Stack table. Theurlis the tag archive, which lets Homebrew infer the version, so leave outversion. Thetest doblock checks--versionand runs one real command. - Hash the archive with
gh release download vX.Y.Z -R filipgutica/<tool> --archive=tar.gzand thenshasum -a 256. - Add the tool to
TOOLSinscripts/update-formulae.py, to the bot PR text inupdate-formulae.yml, to the README install and check lists, and to.github/workflows/tests.yml. Guard a macOS-only tool withif: runner.os == 'macOS'. - Done:
brew audit --strict filipgutica/tap/<tool>is clean, andbrew install --build-from-sourceandbrew testpass locally and in tap CI.
For a local test before merge, copy the formula into $(brew --repo filipgutica/tap)/Formula/, test it, and delete the copy. Leave HOMEBREW_NO_INSTALL_FROM_API unset, because it clones all of homebrew-core. Afterwards, run brew developer off, because brew audit turns developer mode on.
Aligning an existing tool
Compare the tool against every item in the repo contract, the repo settings, the Pages site, and its formula. Done: each item matches or is recorded as an intended per-language difference. Open one PR per repo for the gaps.
Gotchas
- Hosted macOS runners hide sockets from unprivileged
lsof. Run socket tests withsudo --preserve-env=PATH.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/filipgutica/filip-stack/cli-tool-template">View cli-tool-template on skillZs</a>