brew-skill

A reference collection of Homebrew tap patterns, templates, and opencode skill for creating Homebrew formulae on Apple Silicon (aarch64-apple-darwin).

Renamed from bendzgerona/opencode-agent-homebrew — the original is the safe upstream.

Reference: How Homebrew Taps Work

A tap is a GitHub repo named homebrew-<tapname> under any user/org. Users install it with brew tap <user>/<tapname>.

GitHub repo           -> brew tap              -> local path
─────────────────────────────────────────────────────────────
oven-sh/homebrew-bun  -> brew tap oven-sh/bun  -> /opt/homebrew/Library/Taps/oven-sh/homebrew-bun
bendzgerona/homebrew-litellm -> brew tap bendzgerona/litellm -> /opt/homebrew/Library/Taps/bendzgerona/homebrew-litellm

Tap Structure Variants

| Pattern | Repo Name | .github/workflows/ | Formula/ dir | scripts/ | Tap Template | |---|---|---|---|---|---|---| | Full CI suite | homebrew-* | ✅ tests+publish+autobump | ✅ subdir | optional | 01 | | Root-level .rb | homebrew-* | ❌ | ❌ .rb at root | ❌ | 02 | | Simple + script | homebrew-* | ❌ | ✅ subdir | ✅ release.rb | 03 | | Python virtualenv | homebrew-* | optional | ✅ subdir | ✅ update-formula.rb | 04 | | JS Runtime (npm/bun) | homebrew-* | optional | ✅ subdir | optional | 05 | | Keg-only system tool | homebrew-* | optional | ✅ subdir | ❌ | 06 | | Cask-only | homebrew-* | optional | Casks/ subdir | ❌ | 07 | | Go binary | homebrew-* | optional | ✅ subdir | optional | 08 |

Formula Location Rules

Homebrew finds formulae by scanning:

1. Formula/<formula>.rb (subdirectory) — preferred for multi-formula taps
2. <formula>.rb (root level) — acceptable for 1-2 formula taps
3. formula.rb, Formula/<formula>.rb, or HomebrewFormula/<formula>.rb — all valid

Key Files in a Tap

| File | Purpose | |---|---| | Formula/<name>.rb | The formula definition (Ruby DSL) | | .github/workflows/tests.yml | brew test-bot — CI for PRs/pushes | | .github/workflows/publish.yml | brew pr-pull — publishes bottles from labeled PRs | | .github/workflows/autobump.yml | Auto-update formula via livecheck | | scripts/release.rb | Manual version bump script (bun pattern) | | LICENSE | MIT (or other open-source license) | | README.md | Install/upgrade/uninstall docs | | formula_renames.json | Track renamed formulae for seamless upgrades | | tap_migrations.json | Track formulae moved to other taps |

Templates

Eight ready-to-use tap templates live under frozen/templates/taps/. Each includes a template.md reference, a tap-structure/ skeleton with copy-paste-ready file stubs (.rb, .yml, .sh), and an AGENTS.md agent definition installable to ~/.config/opencode/agents/.

To bootstrap a new tap: cp -r frozen/templates/taps/<pattern>/tap-structure /path/to/homebrew-<name>/ Or start with brew tap-new <user>/homebrew-<tapname> and overlay the template stubs on top.

| # | Template | Pattern | Best For | |---|---|---|---| | 01 | Full CI suite | gromgit/homebrew-fuse | Multi-formula taps needing test-bot + bottle publishing | | 02 | Root-level .rb | yakitrak/homebrew-yakitrak | 1-2 formula taps, minimal structure | | 03 | Simple + script | oven-sh/homebrew-bun | Single-formula taps with script-driven releases | | 04 | Python virtualenv | bendzgerona/homebrew-litellm | Python CLI tools with pip dependencies | | 05 | JS Runtime (npm/bun) | Personal npm- or bun-driven CLI taps | JS/TS CLI tools distributed via npm or bun | | 06 | Keg-only system tool | homebrew-core (gnuwhich) | System tool replacements shadowing macOS binaries | | 07 | Cask-only | Personal cask taps | macOS GUI apps (.app, .dmg, .pkg) | | 08 | Go binary | Modern CLI tools in Go | Go CLI tools built from source |

Platform Requirements

This project is designed exclusively for aarch64-apple-darwin (Apple Silicon Macs). All dependencies must be installed via Homebrew.

Required dependencies:

• brew — Homebrew (macOS package manager)
• ruby-lsp — Ruby LSP for formula DSL autocomplete
• fish-lsp — Fish shell LSP for shell scripts
• bash-language-server — Shell language server
• shfmt — Shell formatter
• typos-lsp — Typo checking

Install with:

brew install ruby-lsp fish-lsp bash-language-server shfmt typos-lsp

brew sh Development Shell

All formula development should be done inside brew sh shells:

brew sh --ruby      # For writing/validating .rb files (brew's Ruby 4.0.5 + RuboCop)
brew sh             # For testing formula installation (build environment)

See the template AGENTS.md files for agent-level guidance on each pattern.

Skills

Skills in each template's AGENTS.md teach AI agents how to work with that tap pattern. They are designed to be copied to ~/.config/opencode/agents/.

A root-level skill lives at src/skills/homebrew-tap/SKILL.md that teaches agents how to navigate the full template collection. Each template also has its own AGENTS.md for pattern-specific agent guidance.

For the litellm tap specifically, see the lite-llm skill.

License

MIT

Homebrew Agent Ecosystem

This project includes a complete AI-assisted Homebrew packaging ecosystem.

Quick Start

# Analyze a project
bash src/workflows/analyze-source.sh --dir /path/to/project

# Create a tap
bash src/workflows/create-tap.sh \
  --source /path/to/project \
  --name MyCli \
  --tap myuser/homebrew-mycli \
  --output ./mytap \
  --non-interactive

# Convert npm formula to bun
bash src/workflows/convert-npm-to-bun.sh --formula Formula/my-cli.rb --dry-run

Agent Commands

| Command | Purpose | |---------|---------| | homebrew:env | Inspect brew environment | | homebrew:deps <formula> | Show dependencies | | homebrew:search <query> | Search packages | | homebrew:create <source> | Create tap from source | | homebrew:analyze <source> | Analyze project type |

To install the agent, link the assets in src/ to ~/.config/opencode/:

ln -sf "$(pwd)/src/agents" ~/.config/opencode/agents/brew-skill
ln -sf "$(pwd)/src/commands" ~/.config/opencode/commands/brew-skill
ln -sf "$(pwd)/src/skills" ~/.config/opencode/skills/brew-skill

Tool Scripts

All scripts in src/scripts/ and src/workflows/:

• Environment inspection, dependency analysis, package search
• Source type detection (Go, Python, Node, Rust, etc.)
• Template scaffolding and formula generation
• npm to bun conversion