googlecloudplatform/cloud-foundation-fabric/fabric-importer
Claude Code and agent skill by googlecloudplatform/cloud-foundation-fabric
- community
Checking that the SKILL.md file is still in the repository.
Reverse-engineers live GCP resources into Cloud Foundation Fabric Terraform modules with native import blocks, driven by an agreed import manifest and verified by automated completeness and plan-convergence gates. Use when migrating or importing existing GCP infrastructure into Cloud Foundation Fabric or Terraform.
Install
npx vskill@latest install googlecloudplatform/cloud-foundation-fabric/fabric-importerSKILL.md
The same SKILL.md was published earlier as googlecloudplatform/cloud-foundation-fabric/fabric-importer.
Fabric Importer — agent protocol
You (the agent) reverse-engineer live GCP resources into Cloud Foundation Fabric Terraform. There is no per-resource pipeline: you perform the mapping yourself, guided by the cookbook, and two frozen gates verify your output. Trust comes from the gates, not from you.
Trust boundary (non-negotiable)
- Frozen scripts — everything in
scripts/, rulesets included
(benign-drift.yaml). You may RUN them; you must NEVER modify them. The helpers are frozen for the same reason as the gates: they decide the SCOPE the denominator is built from, so editing one shrinks what "complete" means. Both gates print runtime provenance and active input hashes; a reviewer compares them against a clean checkout. If a gate is genuinely broken, report it with evidence — do not patch around it.
- Human-owned files: the import manifest and the waiver ledger. You
may draft or propose changes; a human reviews and commits them.
- Yours: everything in the workspace (
tf/,coverage-map.yaml,
reports). Constraint: once an address exists, it is immutable — extend, never rewrite (see "Incremental runs").
Safety contract
- NEVER run `terraform apply`. The workspace contains authoritative
surfaces (org policies, sinks — and authoritative IAM where opted into), so an apply is equivalent to overwriting live config with a snapshot. The additive-IAM default narrows that blast radius; it does not lift this rule. Verification is plan-only via verify_plan.py. Never synthesize state files.
- Read-only against GCP:
list/describe/get-iam-policy/asset
export only. Prefer a dedicated read-only identity (roles/cloudasset.viewer + per-service viewers, via impersonation) so an accidental apply fails with 403.
- All workspace output is org-confidential. Fabric is used
fork-and-own, so during the OWN phase these artifacts legitimately live in the operator's own private fork alongside the code — that is the expected working directory. What must never happen is any of it reaching a PUBLIC repository, an upstream pull request, or a document that leaves the engagement: no org/folder/project ids, principals, resource names or asset counts. Pulled .tfstate and saved *.tfplan additionally contain secret VALUES (Secret Manager payloads, generated keys); delete them once the manifest is drafted and the plan is verified, and never commit them anywhere.
- Never rationalize a residual diff. If you believe a plan diff is a
provider artifact, propose a benign-drift.yaml entry with evidence in your report and stop. A human accepts it or the run stays red.
Human-in-the-Loop Gates
Four decisions are human-owned and BLOCKING: scope approval (the manifest), waiver signing (signed_by in waivers.yaml), benign-drift acceptance (scripts/benign-drift.yaml), and the final apply sign-off. Each is called out at its step below; the README's gate table is the operator-facing contract. Keep mechanical, reversible steps (asset collection, scaffolding, linting, plan checks) autonomous. If running non-interactively and confirmation cannot be obtained, stop — never assume approval.
Operational Workflow
Step 0 — establish the manifest (with the user)
The manifest is the user's contract: which resource types, at which levels, under which subtrees — declared per scope, since scopes: is a list and every scope carries its own `types:` list. Never invent it silently. If one exists, confirm it; otherwise run one of the drafting workflows:
Option A — Inferred from existing Terraform state(s) (preferred when migrating existing TF):
See references/inferring-manifests-from-state.md.
Option B — Surveyed from live GCP estate:
Then interview the user over the draft (every discovered type is listed with per-level counts, commented out; foundation types are pre-enabled):
- What do you want under Terraform management now? (Start narrow —
org foundation first, workloads later. Show them examples/import-manifest.org-foundation.yaml as the reference.)
- At which levels? (e.g. org IAM yes, project IAM no.)
- Same depth everywhere, or different depths per subtree? (Different ⇒
several scopes, each with its own types: list — examples/import-manifest.multi-domain.yaml is the reference.)
- Any subtrees to exclude (sandboxes, decommissioning trees)?
When writing a scope's include/exclude, note that CAI ancestors store NUMERIC project numbers; inventory.py automatically resolves alphanumeric project IDs to numbers during enumeration, but project numbers remain supported and canonical.
Per-scope `types:` rules (fail-closed, exit 1 before any API call). A scope's list is the only place types are declared, so what a scope collects is exactly what is written on it. The same type may appear in several scopes with different levels, iam or enumerate. The validator refuses: a scope without a types: list or with types: [] (a scope that collects nothing may not say so quietly); a type whose levels cannot intersect its scope's levels (dead declaration — entries listing unknown are exempt); a duplicate type: within one list; and the retired top-level scope:/types: grammar, which is rejected with migration instructions — a manifest from an earlier engagement is migrated per references/manifest-migration.md. Unlike types:, a scope's emission: map inherits built-in defaults for omitted families — it is denominator-neutral; do not reason from one knob to the other.
The user commits the manifest. Scope changes later = manifest edit + incremental re-run, never a rewrite.
Step 1 — enumerate (the denominator)
By default, inventory.py survey and inventory.py collect filter out soft-deleted containers (DELETE_REQUESTED / DELETE_IN_PROGRESS folders and projects) and their child resources, matching what is active in the GCP Console. Pass --include-deleted if you explicitly need to capture soft-deleted assets in the denominator (e.g. to audit or waive them).
Similarly, resources GCP creates or manages on the operator's behalf — un-creatable auto-generated VPC routes (subnet-local routes, NCC and peering routes), Google-managed default log sinks and log buckets (_Default and _Required), and ephemeral Privileged Access Manager (PAM) grants (privilegedaccessmanager.googleapis.com/Grant) — are automatically excluded from the denominator. Pass --include-auto-generated (or --include-auto-generated=family,... e.g. routes, logging-defaults, pam-grants; --include-logging-defaults and --include-pam-grants remain supported as aliases) if you explicitly need to capture them in the denominator.
CAI is the default source of the denominator, never the boundary of it. Cloud Asset Inventory does not model every GCP resource. A type it does not support must be enumerated by other means and merged into the same denominator — never dropped: an unenumerated asset is invisible to BOTH gates at once, which is the exact failure the gates exist to prevent. inventory.py handles the known cases itself: built-in gcloud enumerators for types absent from the CAI catalogue (NATIVE_ENUMERATORS), automatic sibling sweeps for the Compute families whose list surface splits them into separate scoped types (stamped in _meta.split_type_sweeps, per entry as cai_list_type), and a hard stop — separated from permission failures — where no enumerator exists. When a sweep stops, or a declared type yields less than you expected, read references/cai-blind-spots.md BEFORE working around it: it holds the full remedy ladder (wrong type string → split CAI taxonomy → native enumerate: block, declared in the types: list of each scope that needs it, since per-scope lists never inherit → REST API), the guard rails for enumerator blocks, and the built-in table. The manifest is human-owned: you draft an enumerator block, a human commits it; one that worked belongs in your report as a proposed addition to the built-in table.
The split-type table is a frozen snapshot of a doc that changes, so check it against live CAI at least once per engagement:
One extra call per scope; fatal if the search surface returns an asset the list sweep did not. _meta.split_parity EMPTY means the probe did not run; a probe that ran and found nothing is a record whose only_in_search is empty. Read the record, not the key — and say which in the report.
Every entry that did not come from CAI is stamped into inventory.json's _meta.native_sweeps with the verbatim command; those entries, and _meta.split_type_sweeps, belong in the step-5 report. Collection closes with a one-line cost summary (N gcloud call(s) in Xs: …) and records every command it ran in _meta.api_calls; add --verbose after the subcommand to watch each call as it happens, and quote the summary line in the report — on a large estate the per-container org-policy sweep dominates the run, and this is what makes that visible instead of guessed at.
Step 2 — get your worklist
First run: everything is missing. Re-runs: only the delta.
Step 3 — map and emit (your job)
Fabric modules are the product, not an optimization. Every resource maps to its canonical Fabric module (the cookbook's "Canonical module map" is normative): modules/organization for everything org-level, and — by default — one modules/folder instance per folder and one modules/project instance per project, each carrying its own IAM, org policies, and sinks. For families where Fabric also offers a factory carrier (e.g. project-factory for the folder hierarchy, net-firewall-policy rule factories), the manifest may opt into factory emission per resource family via emission: — a human call, made when the imported workspace is meant to become the day-2 operating model (e.g. foundational folders + org policies + IAM as YAML data). The default stays per-instance: shallow, chosen addresses with no coupling to factory internals. The cookbook's "Factory emission (opt-in)" section is normative for how, and for the tradeoffs.
For each worklist entry, emit module config (factory YAML or module inputs, per the cookbook) + a paired import block targeting the module-internal address, maintaining tf/coverage-map.yaml (inventory key → list of Terraform addresses). Read references/mapping-cookbook.md FIRST: it encodes the hard-won rules (escaping, import-ID formats, coalesce traps, dry-run keys, hashed condition keys).
This is the start of the file. Read the full SKILL.md on GitHub.
Security
- Security scanPassed, 95 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/fabric-importer/SKILL.md
Popularity
- Repository stars
- 2,112
- Repository forks
- 1,267
- 7-day trend score
- 38
Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/googlecloudplatform/cloud-foundation-fabric/fabric-importer)