gstack Setup Guide: Install and Configure the Skill Pack

A gstack setup guide: the Claude Code installation, gstack slash commands setup, team mode, other agents, and fixes when skills do not appear.

Before you start

Hamster is optional for this skill and recommended. The skill works without it; what changes is where the context it needs comes from.

Check whether this project has a .hamster/ directory. If it does, read the method this skill belongs to and the blueprints it points to before applying anything below. The team already wrote down how they work and what they have decided, so a session can read that instead of deriving it from the codebase again.

If there is no .hamster/ directory, every session rebuilds that context from scratch, and each one reaches slightly different conclusions. Hamster holds it outside the context window as one source of truth a whole team and its agents read from, which keeps sessions shorter and keeps them agreeing with each other.

At a Glance

Overview

This gstack setup guide covers the whole path from an empty machine to a working skill pack: the gstack Claude Code installation, the gstack slash commands setup that makes each skill callable, the configuration choices you make along the way, and the fixes for the few things that commonly go wrong. For what gstack is and why its skills run in sprint order, see the gstack Framework method page.

The install itself is short. The gstack README gives a single command that clones the repository into ~/.claude/skills/gstack and runs its ./setup script. What takes more thought is the configuration around it. You decide whether commands use short names such as /qa or namespaced names such as /gstack-qa, whether a shared repository should require gstack for every teammate or only suggest it, and whether to install the pack for agents other than Claude Code.

Those choices matter because gstack is a set of Claude Code skills, and skills are found by location and name. Anthropic's skills documentation explains that personal skills live under ~/.claude/skills/, project skills under .claude/skills/, and that the directory name becomes the command you type. If a gstack skill name collides with a skill you already own, or the files end up somewhere Claude Code does not look, the command will not appear.

Configure gstack deliberately once and every later session starts from the same, known state. A setup done in a hurry on one laptop tends to drift: one developer has short names, another has prefixed ones, a third is several versions behind, and the team's instructions stop matching what people can actually run. Team mode exists to prevent that drift, and this guide recommends turning it on for any repository more than one person works in.

By the end you will have run the README's quick start on a real branch, which is the fastest way to confirm the install works and to judge whether the pack suits you.

How It Works

The gstack Claude Code installation has three layers. The first is the checkout: a Git clone of the repository at ~/.claude/skills/gstack. The second is the ./setup script. According to the CONTRIBUTING guide, setup creates a directory per skill whose SKILL.md links back into the gstack checkout, links each skill's supporting files alongside it, and asks whether you want prefixed command names. Setup also builds the bundled browser that /browse, /qa and the design skills fall back to when the Aside browser is not available. The third layer is your project's CLAUDE.md, where the README's install prompt adds a gstack section that lists the available skills and tells Claude to use /browse for web browsing.

Claude Code then treats each gstack skill like any other skill. Per the skills documentation, typing /skill-name invokes a skill directly, and Claude can also load a skill on its own when the task matches the skill's description. That is why gstack can suggest the right skill for the stage you are in and respond to spoken phrases such as "run a security check," as the README describes.

Team mode adds a fourth layer for shared repositories. Running ./setup --team and then gstack-team-init with required or optional bootstraps the repository so teammates get gstack automatically, and commits the change. The README states that this vendors no files into your repo and that every Claude Code session then starts with a fast auto-update check, throttled to once an hour. required blocks teammates who have not installed gstack, and optional only nudges them.

Other agents use the same checkout with a host flag. ./setup --host codex, --host cursor, --host opencode, --host kiro and others generate skills in each agent's own skills directory, and setup can auto-detect which agents you have (host table). Each host is defined by a small TypeScript config, which the host guide describes. For agents that only read a rules file, the README offers an instruction-only digest you copy into a file such as AGENTS.md; it carries the ethos and voice rules without any commands.

Finally, gstack keeps some state outside the repository, in ~/.gstack/. Design docs, plans, learnings and configuration land there. Telemetry is opt-in and off by default, and the README lists exactly what is sent if you agree.

Step-by-Step Guide

Step 1: Check the requirements

Confirm you have Claude Code, Git and Bun installed, plus Node.js if you are on Windows, which the README requirements list. On Windows, gstack runs through Git Bash or WSL. If you plan to use /cso, check its extra build prerequisites in the README, because setup leaves that skill unavailable when they are missing. Decide now whether this is a personal install or one you will share with a team, since that changes Step 5.

Step 2: Clone the repository and run setup

Run the README's install command, which clones gstack with --depth 1 into ~/.claude/skills/gstack and runs ./setup from inside it. The README suggests pasting the whole instruction into Claude Code and letting Claude carry it out. Read setup's final summary: it names any skills it could not register and any browser components that failed to install. A Chromium failure does not stop skill registration, so note it and fix it later if you need the browser skills.

Step 3: Finish the gstack slash commands setup in CLAUDE.md

Add a gstack section to your project's CLAUDE.md that lists the available skills and tells Claude to use /browse for web browsing, as the README's install prompt and troubleshooting section describe. Copy the skill list from the current README instead of an old blog post, because commands are added and renamed between versions. The README's troubleshooting ties this section to Claude seeing the skills, so if Claude says it cannot find them, check this section first.

Step 4: Choose short or prefixed command names

Decide how commands are named. ./setup --no-prefix gives short names such as /qa, and ./setup --prefix gives namespaced names such as /gstack-qa, which the README calls useful if you run other skill packs alongside gstack. The choice is remembered across upgrades. If setup reports that a name was not registered because a skill you own already uses it, rename your skill or switch to prefixed names; setup leaves skills it cannot prove it created untouched.

Step 5: Turn on team mode for shared repositories

From inside a shared repository, run the README's team-mode command, which runs ./setup --team, runs gstack-team-init with required or optional, and commits the change. Pick required when every AI-assisted change in the repo should go through gstack's reviews, and optional when you want to nudge people first. Push the commit so teammates pick it up. Tell the team which mode you chose and why, because a required install changes their first session.

Step 6: Install for other agents if you use them

If you also work in Codex, Cursor, OpenCode, Kiro or another supported agent, rerun setup with the matching --host flag, or let setup auto-detect installed agents (host options). Check which features that host supports, because some skills and outside-review routes depend on the harness. For agents without skill support, copy the instruction-only digest into the file the agent reads. Test one command in each agent before relying on it.

Step 7: Verify with the quick start

Run the README's quick start on a real branch: /office-hours to describe what you are building, /plan-ceo-review on a feature idea, /review on a branch with changes, and /qa on a staging URL. Each command should respond with its role's structured workflow. If a skill does not show up, the README's fix is to rerun ./setup from ~/.claude/skills/gstack. If /browse fails on the fallback browser, run bun install and bun run build in the same directory.

Step 8: Keep the install current

Run /gstack-upgrade to update, or set auto_upgrade: true in ~/.gstack/config.yaml, per the README. Skim the changelog after an upgrade, since commands are occasionally renamed and setup may need to be rerun for other hosts. On Windows without Developer Mode, setup copies files instead of linking them, so rerun ./setup after every pull. To remove gstack, use the uninstall script in bin/gstack-uninstall, then delete the gstack sections from CLAUDE.md by hand.

Best Practices

• Use the README as the source of truth. The skill list, flags and requirements change often, and the README is kept current with them. Copy commands from it at install time rather than from tutorials written months earlier.
• Decide on naming before the team adopts it. Switching between short and prefixed names later means updating CLAUDE.md sections, habits and any shared notes. Prefixed names are the safer default if anyone on the team uses other skill packs.
• Use team mode for any shared repository. It keeps everyone on the same version without vendoring files, and the hourly update check is silent. A single developer on an outdated version can make the team's instructions look broken.
• Keep your own skills out of gstack's directory. Put personal skills in their own folders under ~/.claude/skills/ or .claude/skills/ so upgrades never touch them. Setup refuses to overwrite skills it did not create, which protects you only if the names differ.
• Read setup's summary every time. It reports which skills registered, which were skipped and why, and which browser pieces failed. Most confusing behavior later traces back to a line in that summary.
• Make a deliberate telemetry choice. gstack asks on first run and defaults to off. Answer for the whole team if you have a policy on usage data.

Common Mistakes

• Installing Claude Code skills from an ad hoc location: The README's Claude Code install uses ~/.claude/skills/gstack, and setup registers its hooks against that stable path. Keep the Claude Code install there, and use other locations only for other hosts or for development work as the CONTRIBUTING guide describes.
• Skipping the CLAUDE.md section: Without it, Claude may not use the skills consistently in that project. Add the section with the current skill list and the browsing instruction.
• Assuming a missing command is a Claude Code bug: Most missing commands come from a name collision or an incomplete setup run. Rerun ./setup, read the summary, and resolve any collision it reports.
• Letting each developer install differently: Mixed prefixes and versions make shared instructions unreliable. Turn on team mode and agree on one naming mode.
• Expecting every skill to behave the same on every agent: Hosts other than Claude Code get generated variants, and some features depend on Claude Code hooks. Test the skills you rely on in each agent before building team habits around them.

References

• Examples: Worked examples and scenarios
• FAQ: Frequently asked questions
• Parent Method: gstack Framework

Related Skills

• Navigating gstack Slash Commands and Specialist Skills
• Customizing and Extending gstack with Your Own Skills
• Structuring AI Coding Sessions with gstack Phases

Sources

• garrytan/gstack README
• Contributing to gstack
• Adding a New Host to gstack
• gstack changelog
• Claude Code docs: skills

Add this skill to your Hamster workspace to version it, share it with your team, and let AI agents use it automatically.