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

Run ./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 script serves as the unified entry point for the 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:

# 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 tool exposes four primary commands. Each command follows a consistent interface: ./skills.sh <command> <skill-name> [options].

list — Discover Available Skills

./skills.sh list

Outputs all skill directories containing a valid SKILL.md file. Use with grep to filter:

./skills.sh list | grep analytics

describe — View Skill Documentation

./skills.sh describe <skill-name>

Displays the contents of the skill's SKILL.md file, including purpose, prerequisites, and usage examples without executing any code.

run — Execute a Skill

./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

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

---

Practical Code Examples

Execute cloud workload management examples with project-specific configurations:

# 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, index.js, go.mod, etc.).

---

How 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. In 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 processes prerequisite documentation:

• Locates 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).

Phase 3: Dependency Installation

The tool detects the implementation language and installs dependencies:

Language	Detection	Installation Command
Python	requirements.txt or pyproject.toml	pip install -r requirements.txt
Node.js	package.json	npm install
Go	go.mod	go mod download
Java	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/skills/cloud/workload-manager-basics/references/client-library-usage.md) in each skill directory (lines 85–105 in skills.sh).

Phase 4: Execution and Cleanup

The final phase invokes the skill's entry point (lines 120–145 in skills.sh):

# 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	Main CLI implementation with discovery, setup, and execution logic	Repository root
SKILL.md	Per-skill documentation defining purpose, prerequisites, and usage	skills/<category>/<skill-name>/SKILL.md
setup-prerequisites.md	Cloud resource provisioning steps for each skill	skills/<category>/<skill-name>/references/setup-prerequisites.md
client-library-usage.md	Language-specific dependency and authentication guidance	skills/<category>/<skill-name>/references/client-library-usage.md
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 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: Run chmod +x skills.sh or invoke with bash skills.sh instead of direct execution.

---

Summary

• Clone and execute: The 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, setup-prerequisites.md, and client-library-usage.md files define self-contained, runnable examples.

---

Frequently Asked Questions

What prerequisites must I install before using 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 files.

Can I run 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?

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}