К основному содержанию
скилл CX Codex

schema-e2e-validation — скилл для Claude Code: проверка схем

Скилл schema-e2e-validation запускает генерацию и E2E-проверку YAML-схемы через Earthly. Пригодится перед коммитом или для сверки схемы с ClickHouse Cloud.

MIT 123 установок ★ 3 обновлён 2026-10-25

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add terrylica/cc-skills --skill schema-e2e-validation -a claude-code
Открыть на GitHub

Что делает schema-e2e-validation

Скилл помогает проверить изменения схемы и заново получить типы Python, DDL и документацию. Для генерации используется earthly +test-schema-generate; полный E2E-сценарий запускается через ./scripts/earthly-with-doppler.sh +test-schema-e2e. Результаты появляются в ./earthly-artifacts/, а для E2E — в каталогах e2e/types/, e2e/ddl/ и e2e/docs/.

Для Earthly нужен Docker Runtime, а перед запуском следует запустить Colima командой colima start. Цели +test-schema-validate и +test-schema-e2e требуют доступа к Doppler; обёртка загружает секреты ClickHouse и передаёт их Earthly. Без запущенного Colima Earthly не сможет обратиться к Docker.

Скилл охватывает генерацию, проверку схемы относительно ClickHouse и полный workflow. Для проектирования схемы в описании предлагается сначала вызвать quality-tools:clickhouse-architect; сам этот скилл проверяет схемы, а не проектирует их.

Какие задачи решает

  • проверить изменения YAML-схемы перед коммитом
  • сверить контракт схемы с ClickHouse Cloud
  • сгенерировать типы Python, DDL и документацию
  • запустить полный E2E workflow со схемой

Примеры запросов агенту

  • Проверь изменения YAML-схемы и запусти полную E2E-проверку.
  • Сгенерируй типы Python, DDL и документацию для схемы.
  • Сверь YAML-схему с ClickHouse Cloud перед коммитом.

Как установить schema-e2e-validation

1Через Skills CLI (Vercel)

npx skills add terrylica/cc-skills --skill schema-e2e-validation -a claude-code

2Вручную: положить файлы

~/.claude/skills/schema-e2e-validation/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/schema-e2e-validation/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о schema-e2e-validation

Как установить schema-e2e-validation в Claude Code?

Выполните npx skills add terrylica/cc-skills --skill schema-e2e-validation -a claude-code. Файл скилла будет доступен по пути ~/.claude/skills/schema-e2e-validation/SKILL.md.

Что делает schema-e2e-validation?

Скилл запускает генерацию типов Python, DDL и документации, а также проверку YAML-схемы относительно ClickHouse Cloud через Earthly.

Что нужно для E2E-проверки схемы?

Нужны Docker Runtime и запущенный Colima. Для целей +test-schema-validate и +test-schema-e2e также требуется доступ к Doppler.

Исходный текст

SKILL.md · MIT
---
name: schema-e2e-validation
description: Earthly E2E validation for YAML schema contracts. TRIGGERS - schema validation, YAML schema, schema contracts, regenerate types.
allowed-tools: Read, Bash, Grep
---

# Schema E2E Validation

> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

## When to Use This Skill

Use this skill when:

- Validating schema changes before commit
- Verifying YAML schema matches live ClickHouse Cloud
- Regenerating Python types, DDL, or docs
- Running full schema workflow validation

## Prerequisites

### Docker Runtime (Required)

Earthly requires Docker. Start Colima before running:

```bash
colima start
```

**Check if running:**

```bash
docker ps  # Should not error
```

### Doppler Access (For validation targets)

Required for `+test-schema-validate` and `+test-schema-e2e`:

```bash
doppler configure set token <token_from_1password>
doppler setup --project gapless-network-data --config prd
```

### Earthly Installation

```bash
brew install earthly
```

---

## Quick Commands

### Generation only (no secrets)

```bash
cd ~/eon/gapless-network-data
colima start  # If not already running
earthly +test-schema-generate
```

### Full E2E with validation (requires Doppler)

```bash
cd ~/eon/gapless-network-data
colima start  # If not already running
./scripts/earthly-with-doppler.sh +test-schema-e2e
```

### All non-secret targets

```bash
cd ~/eon/gapless-network-data
earthly +all
```

---

## Artifacts

After running `+test-schema-generate` or `+test-schema-e2e`, check `./earthly-artifacts/`:

| Path                       | Contents                    |
| -------------------------- | --------------------------- |
| `types/blocks.py`          | Pydantic + TypedDict models |
| `types/__init__.py`        | Package init                |
| `ddl/ethereum_mainnet.sql` | ClickHouse DDL              |
| `docs/ethereum_mainnet.md` | Markdown documentation      |

For E2E, artifacts are under `e2e/types/`, `e2e/ddl/`, `e2e/docs/`.

---

## Earthfile Targets Reference

| Target                  | Secrets | Purpose                    |
| ----------------------- | ------- | -------------------------- |
| `+deps`                 | No      | Install uv + dependencies  |
| `+build`                | No      | Copy source files          |
| `+test-unit`            | No      | Run pytest                 |
| `+test-schema-generate` | No      | Generate types/DDL/docs    |
| `+test-schema-validate` | Yes     | Validate vs ClickHouse     |
| `+test-schema-e2e`      | Yes     | Full workflow + artifacts  |
| `+all`                  | No      | Run all non-secret targets |

---

## Troubleshooting

### "could not determine buildkit address - is Docker or Podman running?"

**Cause**: Docker/Colima not running

**Fix**:

```bash
colima start
# Wait for "done" message, then retry
earthly +test-schema-generate
```

### "unable to parse --secret-file argument"

**Cause**: Wrong flag name or malformed secrets file

**Fix**: The correct flag is `--secret-file-path` (NOT `--secret-file`). The wrapper script handles this, but if running manually:

```bash
# WRONG
earthly --secret-file=/path/to/secrets +target

# CORRECT
earthly --secret-file-path=/path/to/secrets +target
```

Also ensure secrets file has no quotes around values:

```bash
# WRONG format
CLICKHOUSE_HOST="host.cloud"

# CORRECT format
CLICKHOUSE_HOST=host.cloud
```

### "OSError: Readme file does not exist: README.md"

**Cause**: hatchling build backend requires README.md in container

**Fix**: Ensure Earthfile copies README.md in deps target:

```earthfile
deps:
    COPY pyproject.toml uv.lock README.md ./  # README.md required!
```

### "missing secret" during validation

**Cause**: Doppler not configured or secrets not passed

**Fix**:

```bash
# Verify Doppler has the secrets
doppler secrets --project gapless-network-data --config prd | grep CLICKHOUSE

# Use the wrapper script (handles secret injection)
./scripts/earthly-with-doppler.sh +test-schema-validate
```

### Cache Issues

Force rebuild without cache:

```bash
earthly --no-cache +test-schema-e2e
```

---

## Implementation Details

### Doppler Secret Injection

The wrapper script `scripts/earthly-with-doppler.sh`:

1. Downloads secrets from Doppler
2. Filters for `CLICKHOUSE_*` variables
3. Strips quotes (Doppler outputs `KEY="value"`, Earthly needs `KEY=value`)
4. Passes via `--secret-file-path` flag
5. Cleans up temp file on exit

### Secrets Required

| Secret                         | Purpose               |
| ------------------------------ | --------------------- |
| `CLICKHOUSE_HOST_READONLY`     | ClickHouse Cloud host |
| `CLICKHOUSE_USER_READONLY`     | Read-only user        |
| `CLICKHOUSE_PASSWORD_READONLY` | Read-only password    |

---

## Related Files

| File                                                                   | Purpose                  |
| ---------------------------------------------------------------------- | ------------------------ |
| `~/eon/gapless-network-data/Earthfile`                                 | Main build file          |
| `~/eon/gapless-network-data/scripts/earthly-with-doppler.sh`           | Secret injection wrapper |
| `~/eon/gapless-network-data/schema/clickhouse/ethereum_mainnet.yaml`   | SSoT schema              |
| `~/eon/gapless-network-data/docs/adr/2025-12-03-earthly-schema-e2e.md` | ADR                      |

---

## Validation History

- **2025-12-03**: Created and validated with full E2E run against ClickHouse Cloud
- **Lessons Learned**:
  - `--secret-file-path` not `--secret-file` (Earthly v0.8.16)
  - Doppler `--format env` outputs quotes, must strip with `sed 's/"//g'`
  - README.md must be copied for hatchling build backend
  - Colima must be started before Earthly runs

---

## Design Authority

<!-- ADR: 2025-12-10-clickhouse-skill-delegation -->

This skill validates schemas but does not design them. For schema design guidance (ORDER BY, compression, partitioning), invoke **`quality-tools:clickhouse-architect`** first.

## Related Skills

| Skill                                      | Purpose                         |
| ------------------------------------------ | ------------------------------- |
| `quality-tools:clickhouse-architect`       | Schema design before validation |
| `devops-tools:clickhouse-cloud-management` | Cloud credentials for E2E tests |
| `devops-tools:clickhouse-pydantic-config`  | Client configuration            |


## Post-Execution Reflection

After this skill completes, check before closing:

1. **Did the command succeed?** — If not, fix the instruction or error table that caused the failure.
2. **Did parameters or output change?** — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. **Was a workaround needed?** — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

© terrylica · MIT · terrylica/cc-skills

Похожие скиллы

Все скиллы по теме «Тесты и QA» →
data360-schema-get forcedotcom Скилл data360-schema-get для Claude Code и других кодеров запрашивает схему объектов Data Lake Object (DLO) и Data Model Object (DMO) из Salesforce Data Cloud через REST API. CX Codex +1 5 100установок dms-schema-conversion aws Управляет миграцией схем между разными СУБД через AWS DMS Schema Conversion. Запускается при создании проекта миграции, оценке совместимости или конвертации схемы и SQL. CX Codex +1 5 500установок planetscale-schema-recommendations-agent-loop planetscale Скилл planetscale-schema-recommendations-agent-loop для Claude Code обрабатывает рекомендации PlanetScale по схеме БД и превращает их в планы миграций, веток и PR без применения к production. CX Codex +1 2 000установок schema coreyhaines31 Помогает добавлять и проверять разметку Schema.org в формате JSON-LD. Он разбирает тип страницы, текущую разметку и подходящие поисковые функции Google. CX Codex +1 91 700установок convex-schema-validator waynesutton Скилл convex-schema-validator для Claude Code, Codex, Cursor и других платформ: создаёт convex/schema.ts с типами, индексами и валидаторами. Запускается при создании таблиц, добавлении полей, ошибках валидации или проектировании связей. CX Codex +1 3 100установок zod-validation-utilities giuseppe-trisciuoglio Скилл zod-validation-utilities для Claude Code и Codex: создание переиспользуемых схем Zod v4 с полной типизацией TypeScript для валидации API-запросов, форм и конфигураций. CX Codex +1 4 100установок

Из того же набора79

Весь набор →
issues-workflow Скилл issues-workflow держит план, иерархию и статус в GitHub Issues: подзадачи под родителем, связка issue с веткой и PR, автозакрытие после мержа. CX Codex +1 124установок ml-failfast-validation Скилл ml-failfast-validation для Claude Code запускает быстрые проверки ML-экспериментов перед долгим обучением на GPU и выявляет ошибки данных и градиентов. CX Codex +1 124установок pr-gfm-validator Скилл pr-gfm-validator переписывает относительные ссылки в описании пул-реквеста в абсолютные blob-URL с вашей ветки, чтобы ревьюеры не упирались в 404. CX Codex +1 123установок pypi-doppler Скилл pypi-doppler для Claude Code и пяти других платформ: публикует Python-пакет в PyPI с токеном из Doppler — только с локальной машины. CI/CD намеренно заблокирован: скрипт проверяет окружение и останавливается при обнаружении пайплайна. CX Codex +1 123установок plugin-validator Скилл plugin-validator проверяет структуру плагинов перед релизом и находит скрытые ошибки в хуках — команды без обработки исключений, которые молча падают. Нужен перед публикацией в маркетплейс. CX Codex +1 122установок evolutionary-metric-ranking Скилл evolutionary-metric-ranking находит лучшие конфигурации моделей и стратегий через процентильные пороги, пересечение метрик и эволюционный поиск. CX Codex +1 121установок pre-ship-review Скилл pre-ship-review проводит структурированную проверку качества кода перед PR, релизом или вехой. Находит ошибки на границах компонентов, где должны совпадать контракты, примеры и тесты. CX Codex +1 120установок pueue-job-orchestration Скилл pueue-job-orchestration управляет длинными задачами и пакетами команд через очередь pueue с контролем параллелизма и сохранением логов. CX Codex +1 120установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой