# How to Use the Google Skills `skills.sh` Command-Line Tool

> Learn to use the Google skills.sh command-line tool. Discover prepare and execute skills from the Google Skills collection with one simple command. Get started now.

- Repository: [Google/skills](https://github.com/google/skills)
- Tags: how-to-guide
- Published: 2026-08-15

---

**Run [`./skills.sh`](https://github.com/google/skills/blob/main/./skills.sh) from the repository root to discover, prepare, and execute any skill in the Google Skills collection with a single command.**

The [`skills.sh`](https://github.com/google/skills/blob/main/skills.sh) script serves as the unified entry point for the [google/skills](https://github.com/google/skills) repository, automating the workflow of locating skill directories, setting up cloud prerequisites, installing dependencies, and running language-specific code examples. This guide covers installation, core commands, and the internal mechanics of the tool based on its implementation in the source code.

---

## Quick Start: Running Your First Skill

Get started with three simple steps:

```bash

# 1. Clone the repository

git clone https://github.com/google/skills.git
cd skills

# 2. Ensure the script is executable

chmod +x skills.sh

# 3. Run a skill (e.g., Workload Manager basics)

./skills.sh run workload-manager-basics

```

The tool automatically handles discovery, environment preparation, and execution without manual intervention.

---

## Core Commands and Usage Patterns

The [`skills.sh`](https://github.com/google/skills/blob/main/skills.sh) tool exposes four primary commands. Each command follows a consistent interface: `./skills.sh <command> <skill-name> [options]`.

### **list** — Discover Available Skills

```bash
./skills.sh list

```

Outputs all skill directories containing a valid [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) file. Use with grep to filter:

```bash
./skills.sh list | grep analytics

```

### **describe** — View Skill Documentation

```bash
./skills.sh describe <skill-name>

```

Displays the contents of the skill's [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) file, including purpose, prerequisites, and usage examples without executing any code.

### **run** — Execute a Skill

```bash
./skills.sh run <skill-name> [options]

```

**Common options:**
- `--dry-run` — Preview commands without execution
- `--project=<gcp-project-id>` — Specify Google Cloud project
- `--region=<gcp-region>` — Set compute region (e.g., `us-central1`)
- `--clean` — Remove temporary resources after execution

### **help** — Display Command Reference

```bash
./skills.sh help
./skills.sh help <command>

```

---

## Practical Code Examples

Execute cloud workload management examples with project-specific configurations:

```bash

# Run Workload Manager with explicit project and region

./skills.sh run cloud/workload-manager-basics \
    --project=my-production-project \
    --region=us-east1

# Dry-run to verify what will execute

./skills.sh run ads/google-mobile-ads-get-started --dry-run

# Clean up resources after running Analytics API demo

./skills.sh run google-analytics-data-api-basics --clean

```

For skills with multiple implementation languages, the tool selects the appropriate runtime based on detected files ([`main.py`](https://github.com/google/skills/blob/main/main.py), [`index.js`](https://github.com/google/skills/blob/main/index.js), `go.mod`, etc.).

---

## How [`skills.sh`](https://github.com/google/skills/blob/main/skills.sh) Works Internally

The script operates through a four-phase pipeline. Understanding these phases helps troubleshoot execution issues.

### Phase 1: Skill Discovery

The tool scans the `skills/` directory recursively, identifying valid skills by the presence of [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md). In [`skills.sh`](https://github.com/google/skills/blob/main/skills.sh) lines 45–68, the discovery logic builds an internal index mapping skill names to their filesystem paths.

**Key implementation detail:** Skills may be nested (e.g., `cloud/workload-manager-basics` or `ads/google-mobile-ads-get-started`). The tool flattens these into runnable identifiers.

### Phase 2: Prerequisite Setup

Before executing code, [`skills.sh`](https://github.com/google/skills/blob/main/skills.sh) processes prerequisite documentation:

- Locates [`references/setup-prerequisites.md`](https://github.com/google/skills/blob/main/references/setup-prerequisites.md) within the skill directory
- Executes shell commands embedded in markdown code blocks
- Provisions required Google Cloud resources (service accounts, APIs, buckets)
- Authenticates using Application Default Credentials or provided service account keys

For the Workload Manager skill, this phase activates the `workloadmanager.googleapis.com` API and creates necessary IAM bindings as documented in [[`skills/cloud/workload-manager-basics/references/setup-prerequisites.md`](https://github.com/google/skills/blob/main/skills/cloud/workload-manager-basics/references/setup-prerequisites.md)](https://github.com/google/skills/blob/main/skills/cloud/workload-manager-basics/references/setup-prerequisites.md).

### Phase 3: Dependency Installation

The tool detects the implementation language and installs dependencies:

| Language | Detection | Installation Command |
|----------|-----------|----------------------|
| Python | [`requirements.txt`](https://github.com/google/skills/blob/main/requirements.txt) or [`pyproject.toml`](https://github.com/google/skills/blob/main/pyproject.toml) | `pip install -r requirements.txt` |
| Node.js | [`package.json`](https://github.com/google/skills/blob/main/package.json) | `npm install` |
| Go | `go.mod` | `go mod download` |
| Java | [`pom.xml`](https://github.com/google/skills/blob/main/pom.xml) or `build.gradle` | `mvn dependency:resolve` or `gradle build` |

Dependency guidance originates from [[`references/client-library-usage.md`](https://github.com/google/skills/blob/main/references/client-library-usage.md)](https://github.com/google/skills/blob/main/skills/cloud/workload-manager-basics/references/client-library-usage.md) in each skill directory (lines 85–105 in [`skills.sh`](https://github.com/google/skills/blob/main/skills.sh)).

### Phase 4: Execution and Cleanup

The final phase invokes the skill's entry point (lines 120–145 in [`skills.sh`](https://github.com/google/skills/blob/main/skills.sh)):

```bash

# Example internal logic (simplified)

python main.py --project="$PROJECT" --region="$REGION"

```

Output streams directly to your terminal with real-time logging. With `--clean`, the tool executes teardown routines defined in the skill's cleanup section (lines 150–165), removing temporary resources to minimize cloud costs.

---

## Key Source Files and References

| File | Purpose | Location in Repository |
|------|---------|------------------------|
| [`skills.sh`](https://github.com/google/skills/blob/main/skills.sh) | Main CLI implementation with discovery, setup, and execution logic | Repository root |
| [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) | Per-skill documentation defining purpose, prerequisites, and usage | `skills/<category>/<skill-name>/SKILL.md` |
| [`setup-prerequisites.md`](https://github.com/google/skills/blob/main/setup-prerequisites.md) | Cloud resource provisioning steps for each skill | `skills/<category>/<skill-name>/references/setup-prerequisites.md` |
| [`client-library-usage.md`](https://github.com/google/skills/blob/main/client-library-usage.md) | Language-specific dependency and authentication guidance | `skills/<category>/<skill-name>/references/client-library-usage.md` |
| [`README.md`](https://github.com/google/skills/blob/main/README.md) | Repository overview and contribution guidelines | Repository root |

Reference these files when extending the tool or creating custom skills that integrate with the [`skills.sh`](https://github.com/google/skills/blob/main/skills.sh) framework.

---

## Troubleshooting Common Issues

- **"Skill not found" error:** Verify the skill identifier matches the directory structure exactly, including category prefixes (`cloud/workload-manager-basics` not `workload-manager-basics`).
- **Authentication failures:** Ensure `gcloud auth application-default login` has been run or set `GOOGLE_APPLICATION_CREDENTIALS` to a valid service account key.
- **Dependency installation hangs:** Check network connectivity to package registries (PyPI, npm, proxy.golang.org) and verify no corporate firewalls block these endpoints.
- **Permission denied on [`skills.sh`](https://github.com/google/skills/blob/main/skills.sh):** Run `chmod +x skills.sh` or invoke with `bash skills.sh` instead of direct execution.

---

## Summary

- **Clone and execute:** The [`skills.sh`](https://github.com/google/skills/blob/main/skills.sh) tool requires only a git clone and executable permissions to run any skill in the repository.
- **Unified interface:** Four commands (`list`, `describe`, `run`, `help`) handle all interactions with the skills collection.
- **Automated pipeline:** Discovery → prerequisites → dependencies → execution → optional cleanup happens transparently.
- **Flexible configuration:** Pass project IDs, regions, and dry-run flags to control cloud resource usage.
- **Extensible structure:** Each skill's [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md), [`setup-prerequisites.md`](https://github.com/google/skills/blob/main/setup-prerequisites.md), and [`client-library-usage.md`](https://github.com/google/skills/blob/main/client-library-usage.md) files define self-contained, runnable examples.

---

## Frequently Asked Questions

### What prerequisites must I install before using [`skills.sh`](https://github.com/google/skills/blob/main/skills.sh)?

You need **Git**, **bash**, and the **Google Cloud SDK** (`gcloud`) installed and authenticated. The tool itself handles all language-specific dependencies (Python, Node.js, Go) per skill. Some skills may require additional tools like Docker or Terraform if specified in their [`setup-prerequisites.md`](https://github.com/google/skills/blob/main/setup-prerequisites.md) files.

### Can I run [`skills.sh`](https://github.com/google/skills/blob/main/skills.sh) on Windows?

Yes, through **Windows Subsystem for Linux (WSL)** or **Git Bash**. The script uses Unix-style path handling and shell commands that require a POSIX-compatible environment. Native Windows PowerShell support is not currently implemented in the source code.

### How do I add my own skill to work with [`skills.sh`](https://github.com/google/skills/blob/main/skills.sh)?

Create a directory under `skills/<category>/<your-skill-name>/` containing: a [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) file with description and usage instructions, a [`references/setup-prerequisites.md`](https://github.com/google/skills/blob/main/references/setup-prerequisites.md) for resource provisioning, a [`references/client-library-usage.md`](https://github.com/google/skills/blob/main/references/client-library-usage.md) for dependency guidance, and your implementation code. The discovery logic in [`skills.sh`](https://github.com/google/skills/blob/main/skills.sh) automatically picks up new skills on the next `list` or `run` invocation.