How to Test Code Changes in google/skills: A Complete Guide

Test code changes in google/skills by running skill validate, markdownlint, and agents-cli run locally, then pushing to trigger GitHub Actions CI validation.

The google/skills repository holds a collection of Skill definitions written in Markdown (SKILL.md) together with supporting reference material. Because the repository does not contain compiled binaries, testing focuses on validation, linting, and execution‑time checks that ensure a Skill can be rendered by the Instagit Agents platform and that any associated scripts run correctly.

---

Three Core Testing Components

The test workflow in google/skills is built around three core components:

• Skill Validation — Checks the structure of SKILL.md, verifies required front‑matter fields, and confirms that all referenced assets exist. Run with skill validate <path‑to‑skill>. Source: skills/cloud/spanner-basics/SKILL.md.

• Markdown Linting — Runs a Markdown linter to enforce style conventions and catch broken links. Run with npm run lint or markdownlint .. Source: skills/cloud/workload-manager-basics/SKILL.md.

• Local Agent Execution — Executes the skill with the agents‑cli tool, simulating end‑user interaction to verify generated code snippets behave correctly. Run with agents-cli run --skill <path‑to‑skill>. Source: skills/cloud/google-agents-cli-onboarding/SKILL.md.

---

Step‑by‑Step Testing Process

Set Up the Development Environment

Install the shared tooling before running any tests:

# Python is required for the validation helpers

python3 -m pip install -r requirements.txt

# Node‑based linter (if not already installed globally)

npm install -g markdownlint-cli

# Instagit agents CLI – the official runner for Skills

npm install -g @google/agents-cli

All required versions are documented in the repository's root README.md.

Run the Full CI Suite Locally

The repository ships with a convenience script that mirrors the GitHub Actions workflow:

./ci/run_all_tests.sh

The script runs skill validate on every SKILL.md, executes markdownlint, and finally launches a dry‑run of each skill with agents-cli. Inspect the implementation in ci/run_all_tests.sh.

Validate a Single Skill

When working on a specific skill, focus the test suite:

skill validate skills/cloud/spanner-basics
markdownlint skills/cloud/spanner-basics
agents-cli run --skill skills/cloud/spanner-basics

The skill command is a thin wrapper around python -m skill.validator; its source lives under tools/skill_validator.py.

Check Reference Links and Assets

The validator confirms every link resolves (HTTP 200) and that local files (images, YAML templates, etc.) are present. Broken links appear as errors in the validator output.

Review CI Results

After the local run, the script prints a summary:

┌─────────────────────────────┐
│  Skills validation summary   │
├─────────────────────────────┤
│  ✅  42 skills passed        │
│  ❌  0 skills failed         │
└─────────────────────────────┘

Failures include exact file and line numbers for quick correction.

Push and Let GitHub Actions Verify

Once local checks pass, push changes to a feature branch. The repository's CI workflow .github/workflows/ci.yml automatically re‑runs the same validation steps on the remote runner.

---

Complete Testing Example

# Example: testing the Firebase basics skill locally

cd /path/to/google/skills

# 1️⃣ Validate the skill structure

skill validate skills/cloud/firebase-basics

# 2️⃣ Lint the Markdown for style issues

markdownlint skills/cloud/firebase-basics

# 3️⃣ Run the skill with the agents CLI (dry‑run mode)

agents-cli run --skill skills/cloud/firebase-basics --dry-run

A typical CI log snippet from the GitHub Actions run:

[2026-08-14 10:15:23] skill validate skills/cloud/spanner-basics
✔️  skills/cloud/spanner-basics/SKILL.md – front‑matter OK
✔️  skills/cloud/spanner-basics/SKILL.md – all references reachable

[2026-08-14 10:15:24] markdownlint skills/cloud/spanner-basics
✔️  No lint errors found

[2026-08-14 10:15:25] agents-cli run --skill skills/cloud/spanner-basics --dry-run
✔️  Skill executed successfully (no runtime errors)

---

Key Files in the Testing Workflow

Path	Role
skills/*/SKILL.md	Core Skill definition files with front‑matter, instructions, and reference links
tools/skill_validator.py	Python validator parsing SKILL.md front‑matter and validating links
ci/run_all_tests.sh	Convenience wrapper for full repository validation
.github/workflows/ci.yml	GitHub Actions workflow for remote CI
requirements.txt	Python dependencies (requests, pyyaml, etc.)
package.json (root)	npm dependencies for markdownlint-cli and @google/agents-cli

---

Summary

• Install dependencies via requirements.txt and global npm packages
• Run ./ci/run_all_tests.sh to mirror the full CI suite locally
• Test individual skills with skill validate, markdownlint, and agents-cli run
• Fix validator errors using provided file/line references
• Push to trigger .github/workflows/ci.yml for final verification

---

Frequently Asked Questions

What is the skill command and where is it implemented?

The skill command is a thin wrapper around python -m skill.validator as implemented in google/skills. Its source code resides in tools/skill_validator.py, which parses SKILL.md front‑matter, checks required fields, and validates both internal and external links.

How do I test code changes in google/skills for just one skill?

Navigate to your skill directory and run the three individual commands: skill validate <skill-path>, markdownlint <skill-path>, and agents-cli run --skill <skill-path>. This focused approach avoids running the full repository test suite during development.

What does the GitHub Actions CI workflow check?

The workflow defined in .github/workflows/ci.yml re‑runs the same validation steps as the local script: Skill structure validation, Markdown linting, and dry‑run execution via agents-cli. It ensures every contribution passes all tests before merging.

Why does google/skills use validation instead of unit tests?

Because google/skills contains Markdown-based Skill definitions rather than compiled code, traditional unit tests do not apply. The validation approach ensures Skills render correctly in the Instagit Agents platform, maintain consistent style, and include reachable references and assets.

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