gws skills
gws skills manages the global AI-skill installation. Skills are the playbooks your AI agent follows when you type /gws-setup, /gws-up, /gws-status, /gws-down, or /gws-debug.
The installation is machine-wide (one set of skills for your user account, shared across every project) and idempotent — re-running it never duplicates anything. No authentication required.
Usage
gws skills <subcommand> [options]
| Subcommand | Description |
|---|---|
install | Symlink the bundled AI skills into every supported tool's skills directory |
list,doctor,uninstall, and--target <tool>are deferred to a later release. Until then, manage the symlinks viainstalland the install script.
install
Symlink every skill under ~/.gws/skills/ into each supported AI tool's skills directory. Idempotent — safe to re-run any time.
The same logic runs inside the install script on first install and inside gws update on every CLI upgrade, so the skill set self-heals when you upgrade.
Usage
gws skills install # default — link into every detected tool
gws skills install --force # overwrite foreign files at target paths
gws skills install --json # structured report for scripts and CI
Output:
Installing AI skills from /home/you/.gws/skills
Tools (verified): claude, agents
✓ Linked gws-setup → ~/.claude/skills/gws-setup
✓ Linked gws-up → ~/.claude/skills/gws-up
✓ Linked gws-setup → ~/.agents/skills/gws-setup
…
✓ All skills installed.
With --json, the same information is emitted as a structured report ({ sourceDir, tools, actions: [{ action: "linked" | "skipped" | "overwritten", target, source, reason? }], skipped }) suitable for piping into other tools.
Arguments and options
| Argument / option | Description |
|---|---|
--force | Overwrite a foreign file or symlink at a target path. Without it, the installer skips foreign paths and prints a remediation tip. |
--json | Emit a structured JSON report instead of human-readable lines. |
Target directories:
| Target directory | Picked up by |
|---|---|
~/.claude/skills/<skill> | Claude Code, GitHub Copilot CLI |
~/.agents/skills/<skill> | OpenAI Codex CLI, Cursor, Amp |
If neither directory exists, no tools are detected and the installer reports Tools (verified): (none) without erroring — create the parent directory by installing the corresponding agent first, then re-run.
What ships with the CLI
| Skill | Purpose |
|---|---|
gws-setup | Full project bootstrap — analyze repo, generate gws.json, write Dockerfiles + K8s manifests + Helm values, deploy, validate, iterate (5-attempt cap) |
gws-up | Wraps gws up with sanity checks and post-deploy verification |
gws-status | Wraps gws status and surfaces actionable failures |
gws-down | Wraps gws down (does not delete the cluster) |
gws-debug | 8-step debug runbook: doctor → pod signals → log signature catalog → exec → file-sync → URL probe → fix → escalate |
The skill sources live in the CLI tarball at ~/.gws/skills/<skill>/SKILL.md. Inspect them anytime — they're plain Markdown.
On Windows
The installer creates symlinks unconditionally. Windows requires either administrator privileges or Developer Mode to create symlinks without elevation — without one of those, gws skills install will fail with EPERM. A copy-mode fallback is on the roadmap; until then, enable Developer Mode.
Per-project overrides
gws skills is global by design — gws init deliberately does not create <project>/.claude/skills/ or <project>/.gws/skills/. If you want a project-specific override, drop a custom skill at <project>/.claude/skills/<name>/SKILL.md (or <project>/.agents/skills/<name>/SKILL.md) and your agent will pick it up. GWS won't manage it.
Troubleshooting
My AI agent says it can't find /gws-setup
gws skills install
Then restart your AI agent so it re-scans its skills directory.
"Skipping foreign file at ~/.claude/skills/gws-setup"
Some other tool wrote a non-symlink to that path. Inspect it, then re-run with --force:
gws skills install --force
Skills disappeared after a CLI upgrade
gws update calls refreshSkillSymlinks() automatically. If the symlinks are missing it usually means the upgrade was interrupted — re-run:
gws update
# or
gws skills install
See also
- Zero-Config Setup with AI — how the skills are used in practice
- Installation — the install script populates the same symlinks on first install
gws init— what to run after the skills are in place