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

> Discover Terraform code style guidelines for google/skills. Learn how HCL infrastructure code adheres to domain-specific conventions embedded in skill documentation for better maintainability.

- Repository: [Google/skills](https://github.com/google/skills)
- Tags: best-practices
- Published: 2026-08-16

---

**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`](https://github.com/google/skills/blob/main/non-negotiable-architectural-rules.md) and [`terraform_validator_instructions.md`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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:

```hcl

# ✅ 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`](https://github.com/google/skills/blob/main/SKILL.md)
- Each skill's [`SKILL.md`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/non-negotiable-architectural-rules.md) and [`terraform_validator_instructions.md`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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.