google-adk-skill-creator

Google ADK Skill Creator

A library and Claude skill for building, testing, and composing Google ADK skills — modular agent capabilities with dynamic tool injection.

What this is

ADK skills are discrete agent behaviours: a SKILL.md description, a tools.py runtime, and an evals/ suite. This repo provides:

• scaffold.py — generate a new skill from a template
• run_eval.py — run eval prompts against a skill using a live Gemini model on Vertex AI
• run_loop.py — iterate on a skill's description to improve activation accuracy
• compose.py — assemble multiple skills into a single agent
• quick_validate.py — catch mismatches between SKILL.md and tools.py without a model call
• adk-skill-creator Claude skill — drive the whole workflow from a Claude session

---

Prerequisites

• Python 3.11+
• gcloud CLI authenticated with Application Default Credentials
• A Google Cloud project with the Vertex AI API enabled and billing active

---

Install as a Claude Code plugin

Add this repository as a custom plugin source:

/plugin add github:iamdgarcia/google_adk_skill_creator

Then install the skill:

/plugin install google-adk-skill-creator@iamdgarcia

The adk-skill-creator skill will be available in your Claude Code sessions automatically.

Codex CLI: The repo also ships .codex-plugin/plugin.json and is compatible with Codex's plugin system.

---

Auth setup

This is the most common source of errors. Read carefully.

1. Set up Application Default Credentials (ADC):

gcloud auth application-default login

2. If GOOGLE_APPLICATION_CREDENTIALS is set in your environment, unset it:

unset GOOGLE_APPLICATION_CREDENTIALS

The Python google-auth library respects GOOGLE_APPLICATION_CREDENTIALS and uses the service account it points to — which often lacks Vertex AI access. The gcloud CLI ignores this variable and reads ADC directly. This mismatch causes 404s that look like a model access problem but are actually an auth problem.

3. Verify ADC works for your project:

PROJECT_ID="your-project-id"
MODEL_ID="gemini-3.1-flash-lite"

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/publishers/google/models/${MODEL_ID}:streamGenerateContent" \
  -d '{"contents": {"role": "user", "parts": [{"text": "Hello"}]}}'

If this returns a response, your auth is correct and the model is accessible.

---

Install

pip install -r requirements.txt

---

Creating a skill

PYTHONPATH=skills/adk-skill-creator python3 skills/adk-skill-creator/scripts/scaffold.py my-skill-name

This creates:

my-skill-name/
  SKILL.md              # description + metadata
  tools.py              # SkillRuntime class with your tools
  assets/               # optional files the skill references
  references/           # optional docs for the skill author
  evals/
    evals.json          # eval cases
    eval_factory.py     # mock runtime for evals (no real API needed)

---

Skill anatomy

SKILL.md

---
name: my-skill
description: "Use this skill when the user asks about X."
metadata:
  adk_additional_tools:
    - tool_one
    - tool_two
---

# My Skill

Instructions for the agent...

adk_additional_tools declares which methods from SkillRuntime are injected when the skill activates. Only declared tools are available to the agent.

tools.py

class SkillRuntime:
    def __init__(self, base_url: str, session=None):
        self.base_url = base_url
        self.session = session or requests.Session()

    def tool_one(self) -> list:
        """Description shown to the agent."""
        ...

    def tool_two(self, param: str) -> dict:
        """Description shown to the agent."""
        ...

    def get_tools(self) -> list:
        return [self.tool_one, self.tool_two]

Dependencies go in __init__ — inject mocks in evals, real clients in production.

evals/eval_factory.py

def build_eval_runtime() -> SkillRuntime:
    return SkillRuntime(base_url="http://mock.local", session=MockSession())