Code Style Guidelines for google/skills: Terraform Standards and Architecture

The google/skills repository uses domain-specific style conventions embedded directly in skill documentation rather than a single monolithic style guide, with the most explicit rules governing Terraform (HCL) infrastructure code.

This repository acts as a knowledge base of AI-generated skills that produce production-ready sample code. Because generated code is designed to deploy directly into production environments, google/skills enforces validation-ready style rules at the source—particularly for infrastructure-as-code patterns. Understanding these conventions helps contributors and consumers align with the repository's quality standards.

Terraform Style Guidelines: The Core Standard

Terraform receives the most detailed treatment in google/skills because cloud infrastructure skills dominate the repository. Two primary documents govern HCL style: non-negotiable-architectural-rules.md and terraform_validator_instructions.md.

General Structure Rules (general-style-structure)

Located in skills/cloud/google-cloud-solution-n-tier-serverless-web-app/references/non-negotiable-architectural-rules.md (lines 38-48), this specification enforces:

• Typed variables with explicit type declarations
• Descriptive names following domain terminology
• Unit-named numeric fields (e.g., memory_size_gb not memory)
• Boolean flags using positive naming (enable_cdn not disable_cdn)
• Explicit output blocks for all consumable values
• Required deletion_protection = true on stateful resources

These rules guarantee consistency across all skill infrastructure code, enable automated validation, and reduce misconfiguration risks.

Terraform Validation Expectations

The terraform_validator_instructions.md file in skills/cloud/design-deploy/references/design/references/ (lines 10-20) adds generation-time constraints:

• Prefer modules over raw resource blocks
• Match user-supplied code style when extending existing configurations
• Forbid locals, for_each, and count to keep logic predictable
• Enforce pinned module sources with ?ref= tags

These constraints align generated infrastructure with enterprise module catalogs and prevent accidental drift.

Practical Example: Valid Terraform Skill Code

The following HCL demonstrates all enforced conventions from the general-style-structure specification:

# ✅ Typed variable with unit-named number and description

variable "memory_size_gb" {
  type        = number
  description = "Memory allocated per container (GiB)"
  default     = 2
}

# ✅ Boolean flag with positive naming convention

variable "enable_cdn" {
  type        = bool
  description = "Enable Cloud CDN on the LB backend"
  default     = true
}

# ✅ Module preference with pinned source reference

module "cloud_run_service" {
  source = "github.com/googlecloudplatform/cloud-run-service?ref=v1.2.3"

  name        = "my-service"
  memory_gb   = var.memory_size_gb
  enable_cdn  = var.enable_cdn
  project     = var.project_id
  region      = var.region
}

# ✅ Explicit output for downstream consumption

output "service_url" {
  description = "Public URL of the Cloud Run service"
  value       = module.cloud_run_service.url
}

If a skill must integrate with user-provided raw resources rather than modules, the validator respects the existing code style per lines 17-20 of the validator instructions.

Language-Agnostic Skills: Per-Skill Style References

For non-Terraform languages, google/skills delegates to official documentation:

• Python, Go, Java and other runtimes inherit style from the Google Cloud SDK guidelines referenced in each skill's SKILL.md
• Each skill's SKILL.md file specifies the expected runtime and links to the appropriate official style documentation
• No repository-wide linter configuration exists, keeping the codebase lightweight and polyglot-friendly

Example: skills/cloud/workload-manager-basics/SKILL.md describes Python expectations and references Google Cloud client library conventions rather than imposing custom rules.

Contribution Policy and Quality Enforcement

The CONTRIBUTING.md file (line 5) establishes a critical boundary: external pull requests are not accepted. Instead, internal teams follow the "Agent Skills Program," which incorporates automated style checks against the specifications above.

This policy ensures every published skill has passed:

1. Structural validation against general-style-structure rules
2. Terraform validator compliance (for infrastructure skills)
3. Integration testing with downstream AI/LLM generation components

Architectural Rationale: Why Embedded Style Works

The google/skills repository embeds style guidance in Markdown rather than traditional linter configs for two reasons:

Design Choice	Benefit
Markdown-based rules	Keeps repository language-independent while still enforcing strict conventions where needed
Co-location with templates	Enables AI/LLM components to generate validation-ready code without a separate linting step
Domain-specific guidance	Allows precision—Terraform skills need infrastructure rigor; Python skills reference mature SDK standards

This approach optimizes for the repository's core purpose: producing copy-paste-ready code that satisfies enterprise best practices at generation time.

Summary

• Terraform/HCL receives the most detailed code style guidelines in google/skills, enforced through non-negotiable-architectural-rules.md and terraform_validator_instructions.md
• Required patterns include typed variables, unit-named fields, positive boolean flags, explicit outputs, module preference, and pinned source references
• Other languages follow per-skill references to official Google Cloud SDK documentation rather than custom rules
• External contributions are not accepted; internal teams use the "Agent Skills Program" for automated style validation
• Embedded Markdown specifications enable AI-generated code to meet enterprise standards without post-generation linting

Frequently Asked Questions

Does google/skills follow the Google JavaScript or Python style guides?

No. The repository does not impose language-wide style guides. Python, JavaScript, Go, and other languages inherit their conventions from the official Google Cloud SDK documentation referenced in each skill's SKILL.md file. Only Terraform/HCL has repository-specific rules due to its central role in infrastructure skills.

Where are the Terraform style rules defined?

Two files contain the canonical specifications: skills/cloud/google-cloud-solution-n-tier-serverless-web-app/references/non-negotiable-architectural-rules.md defines the general-style-structure conventions, while skills/cloud/design-deploy/references/design/references/terraform_validator_instructions.md lists generation constraints for AI components.

Can I contribute style improvements to google/skills?

No. The CONTRIBUTING.md file explicitly states that external pull requests are not merged. The repository maintains quality through an internal "Agent Skills Program" with automated style checks. Suggestions may be submitted through Google's internal channels if you are a Google employee.

Why doesn't google/skills use .editorconfig or standard linters?

The repository prioritizes language independence and AI-generation compatibility. Markdown-based specifications allow the embedded LLM components to consume style rules directly during code generation, producing validated output without requiring a separate linting pipeline. This design eliminates tooling dependencies while maintaining strict quality standards.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}