Capture & Tooling¶

synthkit ships several supporting tools for capturing real environments, generating blueprint drafts, generating Grafana dashboards, and LLM-assisted workflow skills.

skcapture — environment snapshot¶

skcapture inspects a live Kubernetes environment via kubectl and writes a versioned, optionally age-encrypted inventory file. It has zero synthkit imports — no blueprint, construct, or runner code. This trust boundary is enforced by internal/capture.TestCaptureTrustBoundary.

Typical use: run skcapture inside the target cluster (as a kubectl-shell container or a one-shot Job), encrypt the output, and retrieve it for processing with skforge outside the cluster.

# Encrypted output (recommended for production clusters)
skcapture \
  --passphrase-file /path/to/passphrase \
  --out capture.age

# Plain JSON (for local development or non-sensitive environments)
skcapture --plain --out capture.json

# Restrict to specific namespaces
skcapture --plain \
  --namespaces my-app,my-services \
  --out capture.json

Key flags:

The capture output is a versioned JSON Inventory envelope containing resource kinds (nodes, namespaces, deployments, statefulsets, daemonsets, services, ingresses, addons). The schema version is embedded in the output.

The current v1 focus is AWS/EKS. The Inventory struct is designed to support additional collectors in future versions.

skforge — blueprint forge¶

skforge takes a captured inventory and produces a synthkit blueprint draft. It uses a deterministic skeleton mapper to translate inventory resources into blueprint declarations, then emits a self-contained LLM prompt that you feed to Claude (or another LLM) to produce the final blueprint YAML.

# Inspect a capture file
skforge inspect capture.age --key /path/to/passphrase

# Generate an LLM prompt + optional coverage report
skforge prompt capture.age \
  --key /path/to/passphrase \
  --report coverage.md > blueprint-prompt.txt

# Validate a blueprint draft
skforge validate my-blueprint.yaml

Subcommands¶

inspect — decrypt (or read plain) a capture file and print it as indented JSON for inspection.

prompt — the main workflow step. Decrypts the capture, runs the deterministic skeleton mapper, and emits a self-contained LLM prompt to stdout. The prompt includes the captured inventory summary, a description of each construct kind available in the catalog, and instructions for the LLM to produce a valid blueprint YAML. Pass --report <path> to also write a coverage report showing which resources mapped to which construct kinds and which were not covered.

validate — load a blueprint file through the real registry and cardinality projection. Prints OK, Name, Cardinality, Estimated, and any Diagnostics. Exits non-zero if the blueprint is invalid. Useful for confirming an LLM-generated draft is structurally correct before running synthkit.

OK:          true
Name:        my-service
Cardinality: 847
Estimated:   true

The capture → forge → blueprint workflow¶

1. Capture: run skcapture in the target environment to produce an inventory file.
2. Forge prompt: run skforge prompt to generate a self-contained LLM prompt.
3. LLM authoring: feed the prompt to Claude (or another LLM). The prompt is self-contained — it includes the full construct catalog description so the LLM can work without any other context.
4. Validate: run skforge validate on the resulting blueprint.yaml to confirm it loads cleanly.
5. Deploy: place the validated blueprint in blueprints/ and run synthkit.

See custom-blueprints.md for how to add custom blueprints at runtime.

synthkit-dash — Grafana dashboard generator¶

synthkit-dash generates Grafana v2 dashboard JSON for a blueprint's synthetic telemetry. It resolves the blueprint, derives the signal manifest (via internal/dashgen), runs registered per-blueprint templates, and writes dashboard JSON files to an output directory.

go run ./cmd/synthkit-dash \
  -blueprint blueprints/my-service.yaml \
  -out dashboards/my-service/

synthkit-dash always emits a thin index dashboard and a metrics dashboard. Additional per-blueprint dashboards are generated when templates are registered for that blueprint. Files are named <dashboard-uid>.json and written to explicit --out paths (never stdout).

For blueprints that define recording/alert rules, synthkit-dash also emits a <blueprint>-rules.json file.

Push generated dashboards to Grafana with gcx:

gcx resources push -p dashboards/my-service/

synthkit-control-dash — control dashboard generator¶

synthkit-control-dash generates the customer-facing self-serve control dashboard: an Infinity-datasource-backed Grafana v2 dashboard with volume and scenario knobs as read panels and native action buttons.

go run ./cmd/synthkit-control-dash \
  -ds-name "My Infinity DS" \
  -out dashboards/control/

GET routes on the control plane are open. POST routes use HTTP Basic auth — the browser handles the credential prompt natively. No token is embedded in the dashboard JSON.

LLM-assisted skills¶

synthkit ships agent skills for Claude Code, Codex, and OpenCode. Skills are authored once under plugins/synthkit/skills/; make skills-sync creates symlinks in .claude/skills/ and .agents/skills/ so the same skills are available in all three harnesses. make skills-check verifies the symlink farm and is safe for CI.

Available skills¶

Using skills in Claude Code¶

Open the synthkit repository in Claude Code and run a skill directly:

/initial-setup
/create-blueprint
/verify-deployment

Using skills from outside the repo (plugin install)¶

Install synthkit as a Claude Code plugin from any directory:

/plugin marketplace add rknightion/synthkit
/plugin install synthkit@synthkit

After installation the skills are available as /synthkit:initial-setup, /synthkit:create-blueprint, /synthkit:setup-fleet-management, and /synthkit:verify-deployment.

Cross-harness compatibility¶

The same skills work in Codex (reads .agents/skills/) and OpenCode (reads .claude/skills/). Both directories are populated by make skills-sync. Install the tool on a new machine and run make skills-sync to get the skills available immediately.

For more on authoring custom blueprints, see custom-blueprints.md. For Fleet Management setup, see fleet-management.md. For the full CLI reference, see cli.md.