convez.ai
SkillDesenvolvimento WebAvançado
setia141

Conversor de Skills Claude para Agentes ADK

setia141/claude-skills-to-adk-agent

Transforme Skills Claude em agentes ADK production-ready com validação automática

Ver no GitHub
InicialPluginScore · de 0 a 100

Converte arquivos de Skill do Claude em código pronto para produção na plataforma Google ADK. Utiliza um Agent Arquiteto para gerar um Architecture Decision Record (ADR), um Generator para produzir código fundamentado em RAG, e inclui validação automática com loop de correção antes do download.

Instalação

$npx convez-ai setia141/claude-skills-to-adk-agent

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
14%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Converter múltiplos Skills Claude em um único agente ADK compostos
  • Gerar código Python fundamentado em decisões arquiteturais documentadas
  • Validar e corrigir automaticamente código gerado antes do deploy
  • Testar agentes end-to-end com credenciais do usuário

Veredito

Ferramenta especializada para engenheiros que precisam migrar Skills Claude para o ecossistema ADK com garantias arquiteturais e validação rigorosa. Exige conhecimento prévio de ADK, Python e o modelo de Skills do Claude; valor alto para equipes já investidas nessa stack.

README

A tradução para o português deste README ainda está na fila.

Skill → ADK Agent Platform

Convert Claude Skill files into production-ready Google ADK agent code. An Architect Agent produces a reviewed Architecture Decision Record (ADR), a Generator produces RAG-grounded code that strictly follows it, and a built-in sanity check + auto-fix loop validates and corrects the output before you download.

No Claude API key — uses claude-agent-sdk with local CLI auth (claude login).


Features

Multi-skill supportSingle SKILL.md or a ZIP of multiple skills — composed into one agent
ADR-driven generationArchitect Agent reasons about architecture first; code strictly follows the ADR
ADR ChatConversational interface to refine architecture decisions before generating
RAG-grounded code3,252 chunks of official ADK docs retrieved per ADR via semantic search
Permission gatesEvery file write shown to user for approval before touching disk
Session persistenceResume after page refresh or server restart — localStorage + filesystem
ValidatorGenerated code checked against ADR decisions; auto-fixed if mismatched
Sanity checkIsolated sandbox venv → pip install → py_compile → import test, Claude auto-fix loop (7 attempts)
Smoke testRuns the generated agent end-to-end via ADK Runner with your credentials
Fix with ClaudePaste any runtime error — Claude rewrites the affected file
DockerfileDockerfile + .dockerignore generated alongside agent code
Python-only outputAll generated code is Python; existing shell scripts called via subprocess

Architecture

╔══════════════════════════════════════════════════════════════════════╗
║  OFFLINE SETUP  (once — or when adk_docs.txt is updated)            ║
║                                                                      ║
║   adk_docs.txt ──► chunk (3,252 chunks) ──► text-embedding-3-small  ║
║   3 MB · 66k lines        500 tokens each        OpenAI API         ║
║                                    │                                 ║
║                               ChromaDB  ◄── persisted to disk       ║
║                            adk_chroma_db/                            ║
╚══════════════════════════════════════════════════════════════════════╝

╔══════════════════════════════════════════════════════════════════════╗
║  PIPELINE  (per request)                                             ║
║                                                                      ║
║  SKILL.md × N  ──────────────────────────────────────────────────   ║
║  or ZIP                                                          │   ║
║                                                                  ▼   ║
║                              ┌─────────────────────────────────┐    ║
║                              │  Parser Agent                   │    ║
║                              │  SKILL.md → structured JSON     │    ║
║                              │  per step: type · purpose ·     │    ║
║                              │  deps · script refs             │    ║
║                              └──────────────┬──────────────────┘    ║
║                                             │ parsed skills[]       ║
║                              ┌──────────────▼──────────────────┐    ║
║                              │  Architect Agent                 │    ║
║                              │  reasons about topology ·        │    ║
║                              │  memory · error strategy ·       │◄───╫── ADR Chat
║                              │  autonomy · context · recovery   │    ║  (iterative
║                              └──────────────┬──────────────────┘    ║   refinement)
║                                             │ ADR (JSON)            ║
║                              ┌──────────────▼──────────────────┐    ║
║                              │  ADR Review  (UI)               │    ║
║                              │  user reads · edits · approves  │    ║
║                              └──────────────┬──────────────────┘    ║
║                                             │ approved ADR          ║
║                 ┌───────────────────────────▼──────────────────┐    ║
║                 │  RAG Retrieval                                │    ║
║                 │  Query Planner → ~14 targeted queries         │    ║
║                 │  ChromaDB cosine search (text-embedding-3-sm) │    ║
║                 │  top-20 unique chunks · up to 18k chars       │    ║
║                 └───────────────────────────┬──────────────────┘    ║
║                                             │ ADK doc context       ║
║                 ┌───────────────────────────▼──────────────────┐    ║
║                 │  Generator Agent                              │    ║
║                 │  ADR + doc context → Python-only code        │    ║
║                 │                                               │    ║
║                 │  tools.py      @tool per ADR granularity      │    ║
║                 │  agent.py      topology from ADR              │    ║
║                 │  prompts/*.md  one instruction file / Agent() │    ║
║                 │  Dockerfile    python:3.11-slim               │    ║
║                 │  .dockerignore                                │    ║
║                 └───────────────────────────┬──────────────────┘    ║
║                                             │                       ║
║                          ✍ permission popup per file ──────────────►║
║                                             │                       ║
║                 ┌───────────────────────────▼──────────────────┐    ║
║                 │  Validator Agent                              │    ║
║                 │  checks code against every ADR decision       │    ║
║                 │  auto-fixes mismatches (permission popup)     │    ║
║                 └───────────────────────────┬──────────────────┘    ║
║                                             │                       ║
║                 ┌───────────────────────────▼──────────────────┐    ║
║                 │  Test Generator Agent                         │    ║
║                 │  tools.py → pytest suite                      │    ║
║                 │  error strategy + HITL points from ADR        │    ║
║                 └───────────────────────────┬──────────────────┘    ║
║                                             │                       ║
║                 ┌───────────────────────────▼──────────────────┐    ║
║                 │  AST Syntax Verifier                          │    ║
║                 │  py_compile on every generated .py file       │    ║
║                 └───────────────────────────┬──────────────────┘    ║
║                                             │                       ║
║                 ┌───────────────────────────▼──────────────────┐    ║
║                 │  HITL Gate  (if ADR hitl_points non-empty)    │    ║
║                 │  pauses pipeline · waits for user approval    │    ║
║                 └───────────────────────────┬──────────────────┘    ║
║                                             │                       ║
║                 ┌───────────────────────────▼──────────────────┐    ║
║                 │  Package                                      │    ║
║                 │  tools.py · agent.py · prompts/ · tests/      │    ║
║                 │  requirements.txt · adr.json · README.md      │    ║
║                 │  Dockerfile · .dockerignore · run_tests.*     │    ║
║                 └───────────────────────────┬──────────────────┘    ║
║                                             │                       ║
║                             Download ZIP ◄──┘                       ║
║                                                                      ║
║  ┌─────────────────────────────────────────────────────────────┐    ║
║  │  Sanity Check  (on demand, post-download)                   │    ║
║  │                                                             │    ║
║  │  0. create isolated sandbox venv (_venv/) — app venv safe  │    ║
║  │  1. pip install -r requirements.txt   ► approval popup      │    ║
║  │  2. py_compile on tools.py + agent.py (no execution)       │    ║
║  │  3. python -c "import tools; import agent"  ► popup        │    ║
║  │                                                             │    ║
║  │  On failure → Claude rewrites file → approval → re-check   │    ║
║  │              (up to 7 auto-fix attempts per step)           │    ║
║  └─────────────────────────────────────────────────────────────┘    ║
║                                                                      ║
║  ┌─────────────────────────────────────────────────────────────┐    ║
║  │  Smoke Test  (on demand)                                    │    ║
║  │  ADK Runner + user-supplied env vars → live agent run       │    ║
║  │  model-agnostic: ANTHROPIC_API_KEY / GOOGLE_API_KEY / etc.  │    ║
║  └─────────────────────────────────────────────────────────────┘    ║
╚══════════════════════════════════════════════════════════════════════╝

ADR decisions

DecisionOptionsControls
Topologyflat / hierarchical / pipeline / routerAgent class structure and sub-agent wiring
Memory — short-termsession_only / tool_output_passingHow state flows between tool calls
Memory — long-termnone / sqlite / file_basedSession service class selected
Tool granularityper_step / per_skill / groupedNumber and naming of @tool functions
Error strategystop / retry / warn_continue / fallbacktry/except pattern in every tool
Recovery strategyrestart / checkpoint_resume / manual_interventionPost-failure resumption behaviour
Autonomy levelsupervised / semi_autonomous / autonomousDensity of HITL approval gates
Context strategyfull / filtered / summarizedHow much state each agent receives
Parallelismparallel groups / sequential chainsasyncio.gather or SequentialAgent
HITL pointslist of step + reasoninput() confirmation before each flagged tool
Data flowfrom / produces / to / viaTool output passing between skills

Project structure

skill_adk_v4/
├── app.py                    Flask backend + SSE pipeline routes
├── requirements.txt
├── agents/
│   ├── __init__.py
│   ├── claude_sdk.py         ask() wrapper over claude-agent-sdk
│   ├── rag.py                chunk · embed · retrieve ADK docs (ChromaDB)
│   ├── parser.py             SKILL.md → structured JSON
│   ├── architect.py          Architect Agent → ADR + ADR Chat
│   ├── generator.py          Generator · Validator · Test Generator
│   ├── fixer.py              Fix-with-Claude (runtime error → patched file)
│   └── verifier.py           AST syntax check on generated files
├── prompts/
│   ├── architect.md          Architect Agent system prompt
│   ├── adr_chat.md           ADR Chat system prompt
│   ├── generator_base.md     Generator system prompt (Python-only rule)
│   ├── validator.md          Validator system prompt
│   ├── test_gen.md           Test generator system prompt
│   ├── fixer.md              Fixer system prompt
│   ├── parse_skill.md        Parser system prompt
│   └── query_planner.md      RAG query planner system prompt
├── templates/
│   └── index.html            Single-page Flask UI
├── examples/
│   ├── code-quality-skill/   Example: SKILL.md + scripts + reference docs
│   └── code-quality-skill.zip  Drag-and-drop into the UI
└── sessions/                 Server-side session files (gitignored)

Generated output

my-adk-agent/
├── agent.py              root_agent wired to ADR topology
├── tools.py              @tool per step, namespaced across skills
├── prompts/
│   └── *.md              one instruction file per Agent() instance
├── requirements.txt      inferred pip dependencies
├── adr.json              the ADR that drove this generation
├── Dockerfile            python:3.11-slim · runtime env vars documented
├── .dockerignore
├── README.md
├── run_tests.sh          local pytest runner (not executed on server)
├── run_tests.bat
└── tests/
    └── test_tools.py     pytest suite, ADR error-strategy-aware

Setup

# 1. Install dependencies
pip install -r requirements.txt

# 2. Authenticate Claude (no API key — uses local CLI)
claude login

# 3. Configure environment — copy and edit .env
cp .env.example .env   # then fill in your values

.env (all values required unless marked optional):

# Embedding gateway (used by ChromaDB / RAG index)
EMBEDDING_BASE_URL=https://your-gateway.company.com/v1
EMBEDDING_API_KEY=your-api-key-here
EMBEDDING_MODEL=text-embedding-3-small

# Flask session signing key — generate with: python -c "import secrets; print(secrets.token_hex(32))"
FLASK_SECRET_KEY=change-me

# Auth (optional — leave SECRET_TOKEN blank to disable login page for local use)
SECRET_TOKEN=
# 4. Get ADK docs (3 MB — indexed once, reused forever)
curl -o adk_docs.txt https://google.github.io/adk-docs/llms-full.txt

# 5. Start
python app.py
# → http://localhost:5000

First run builds the RAG index automatically (~3,252 chunks, 2–5 min). Every subsequent start loads from disk in under a second.


Authentication

The app supports an optional shared-secret login page for team/shared deployments.

ModeHow to configureBehaviour
Local (single user)Leave SECRET_TOKEN= blank in .envNo login page — app opens directly
Shared deploymentSet SECRET_TOKEN=<long random string>Login page shown on first visit; signed browser cookie keeps user signed in

To generate a strong token:

python -c "import secrets; print(secrets.token_hex(32))"
  • /login — login page (GET) / token submit (POST)
  • /logout — clears session cookie

Session cookies are signed with FLASK_SECRET_KEY — changing this key invalidates all active sessions.


RAG index management

# Check status
curl http://localhost:5000/rag/status

# Force rebuild (after updating adk_docs.txt)
curl -X POST http://localhost:5000/rag/build \
     -H "Content-Type: application/json" \
     -d '{"force": true}'

Dependencies

PackagePurpose
flaskWeb UI + SSE streaming pipeline
claude-agent-sdkClaude calls — local CLI auth, no API key needed
openaiEmbedding model calls via gateway
chromadbLocal persistent vector store
python-dotenvLoads .env at startup
Ver o original no GitHub

Bom para

Relacionados