[
{
"path": ".claude-plugin/marketplace.json",
"content": "{\n \"name\": \"hashicorp\",\n \"owner\": {\n \"name\": \"HashiCorp\"\n },\n \"metadata\": {\n \"description\": \"Official HashiCorp plugins and skills for Claude Code\",\n \"version\": \"1.0.0\"\n },\n \"plugins\": [\n {\n \"name\": \"terraform-code-generation\",\n \"source\": \"./terraform/code-generation\",\n \"description\": \"Terraform code generation skills including HCL generation, style guides, and testing.\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"HashiCorp\"\n },\n \"keywords\": [\"terraform\", \"hcl\", \"infrastructure\", \"iac\", \"testing\", \"style-guide\"],\n \"category\": \"integration\",\n \"license\": \"MPL-2.0\",\n \"strict\": false\n },\n {\n \"name\": \"terraform-module-generation\",\n \"source\": \"./terraform/module-generation\",\n \"description\": \"Terraform module generation and refactoring skills including module design and Terraform Stacks.\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"HashiCorp\"\n },\n \"keywords\": [\"terraform\", \"modules\", \"infrastructure\", \"iac\", \"stacks\", \"refactoring\"],\n \"category\": \"integration\",\n \"license\": \"MPL-2.0\",\n \"strict\": false\n },\n {\n \"name\": \"terraform-provider-development\",\n \"source\": \"./terraform/provider-development\",\n \"description\": \"Terraform provider development skills including resources, data sources, actions, and acceptance testing.\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"HashiCorp\"\n },\n \"keywords\": [\"terraform\", \"provider\", \"plugin-framework\", \"resources\", \"testing\"],\n \"category\": \"integration\",\n \"license\": \"MPL-2.0\",\n \"strict\": false\n },\n {\n \"name\": \"packer-builders\",\n \"source\": \"./packer/builders\",\n \"description\": \"Packer builder skills for AWS, Azure, and Windows image creation.\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"HashiCorp\"\n },\n \"keywords\": [\"packer\", \"aws\", \"azure\", \"windows\", \"ami\", \"image\", \"builder\"],\n \"category\": \"integration\",\n \"license\": \"MPL-2.0\",\n \"strict\": false\n },\n {\n \"name\": \"packer-hcp\",\n \"source\": \"./packer/hcp\",\n \"description\": \"HCP Packer registry integration for tracking and managing image metadata.\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"HashiCorp\"\n },\n \"keywords\": [\"packer\", \"hcp-packer\", \"registry\", \"metadata\", \"image-tracking\"],\n \"category\": \"integration\",\n \"license\": \"MPL-2.0\",\n \"strict\": false\n }\n ]\n}\n"
},
{
"path": ".copywrite.hcl",
"content": "schema_version = 1\n\nproject {\n license = \"MPL-2.0\"\n copyright_year = 2025\n\n # (OPTIONAL) A list of globs that should not have copyright/license headers.\n # Supports doublestar glob patterns for more flexibility in defining which\n # files or folders should be ignored\n header_ignore = [\n # \"vendor/**\",\n # \"**autogen**\",\n ]\n}\n"
},
{
"path": ".github/.tessl/skill-review-cache.json",
"content": "{\n \"version\": \"1\",\n \"last_updated\": \"2026-02-24T00:00:00Z\",\n \"skills\": {}\n}\n"
},
{
"path": ".github/workflows/tessl-skill-review-comment.yml",
"content": "# Companion workflow to tessl-skill-eval.yml.\n#\n# The main workflow (Tessl Skill Review) runs on pull_request events, which\n# don't have write access to the PR (especially for fork PRs). To work around\n# this, the main workflow saves the review results and the PR number as\n# artifacts. This workflow triggers on workflow_run (after the main workflow\n# completes), downloads those artifacts, and posts/updates the PR comment\n# with pull-requests: write permission.\n#\n# The PR number is read from the artifact file (pr-comment/pr_number) that\n# was written by the main workflow using github.event.pull_request.number.\nname: Post Tessl Review Comment\n\non:\n workflow_run:\n workflows: [\"Tessl Skill Review\"]\n types: [completed]\n\npermissions:\n pull-requests: write\n\njobs:\n post-comment:\n name: Post PR Comment\n runs-on: ubuntu-latest\n if: github.event.workflow_run.event == 'pull_request'\n\n steps:\n # Download the artifact produced by the main workflow's review-skills job.\n # run-id ties this to the specific workflow run that triggered us.\n - name: Download skill-review-comment artifact\n uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1\n with:\n name: skill-review-comment\n path: skill-review-comment\n run-id: ${{ github.event.workflow_run.id }}\n github-token: ${{ secrets.GITHUB_TOKEN }}\n\n # Read the PR number and comment body from the artifact, then create or\n # update the PR comment. Uses an HTML comment marker ()\n # to find and update an existing comment instead of posting duplicates.\n - name: Post skill review comment\n uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1\n with:\n script: |\n const fs = require('fs');\n const prNumber = parseInt(fs.readFileSync('skill-review-comment/pr_number', 'utf8').trim());\n const body = fs.readFileSync('skill-review-comment/comment.md', 'utf8');\n const marker = '';\n\n const { data: comments } = await github.rest.issues.listComments({\n owner: context.repo.owner,\n repo: context.repo.repo,\n issue_number: prNumber,\n });\n\n const existing = comments.find(c => c.body.includes(marker));\n\n if (existing) {\n await github.rest.issues.updateComment({\n owner: context.repo.owner,\n repo: context.repo.repo,\n comment_id: existing.id,\n body: body,\n });\n } else {\n await github.rest.issues.createComment({\n owner: context.repo.owner,\n repo: context.repo.repo,\n issue_number: prNumber,\n body: body,\n });\n }\n"
},
{
"path": ".github/workflows/tessl-skill-review.yml",
"content": "name: Tessl Skill Review\n\non:\n pull_request:\n branches: [main]\n paths:\n - '**/SKILL.md'\n - '**/skills/**'\n - '.github/workflows/tessl-skill-review.yml'\n push:\n branches: [main]\n paths:\n - '**/SKILL.md'\n - '**/skills/**'\n workflow_dispatch:\n\npermissions:\n contents: write # Required for cache commits\n\njobs:\n review-skills:\n name: Review Skills\n runs-on: ubuntu-latest\n\n steps:\n - name: Checkout repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 0\n\n - name: Setup Node.js\n uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0\n with:\n node-version: '20'\n\n - name: Install Tessl CLI\n run: npm install -g @tessl/cli\n\n - name: Detect changed skills\n id: detect\n env:\n EVENT_NAME: ${{ github.event_name }}\n BASE_REF: ${{ github.base_ref }}\n run: |\n if [[ \"$EVENT_NAME\" == \"pull_request\" ]]; then\n CHANGED_SKILLS=$(git diff --name-only --diff-filter=ACMR \\\n \"origin/${BASE_REF}\"...HEAD \\\n -- '**/SKILL.md' '**/skills/**' | \\\n grep 'SKILL.md$' | \\\n xargs -I {} dirname {} | \\\n sort -u)\n else\n # workflow_dispatch: find all skills\n CHANGED_SKILLS=$(find . -name \"SKILL.md\" -not -path \"./node_modules/*\" -not -path \"./.git/*\" | \\\n xargs -I {} dirname {} | \\\n sed 's|^\\\\./||' | \\\n sort -u)\n fi\n\n if [[ -z \"$CHANGED_SKILLS\" ]]; then\n echo \"No skill changes detected.\"\n echo \"skills=\" >> \"$GITHUB_OUTPUT\"\n else\n echo \"Skills to review:\"\n echo \"$CHANGED_SKILLS\"\n EOF_MARKER=$(dd if=/dev/urandom bs=15 count=1 status=none | base64)\n echo \"skills<<${EOF_MARKER}\" >> \"$GITHUB_OUTPUT\"\n echo \"$CHANGED_SKILLS\" >> \"$GITHUB_OUTPUT\"\n echo \"${EOF_MARKER}\" >> \"$GITHUB_OUTPUT\"\n fi\n\n - name: Read review cache\n if: steps.detect.outputs.skills != ''\n id: cache\n run: |\n CACHE_FILE=\".github/.tessl/skill-review-cache.json\"\n\n if [[ -f \"$CACHE_FILE\" ]]; then\n echo \"Cache file found, loading...\"\n if CACHE_CONTENT=$(cat \"$CACHE_FILE\" 2>&1); then\n # Validate JSON\n if echo \"$CACHE_CONTENT\" | jq empty 2>/dev/null; then\n echo \"cache_exists=true\" >> \"$GITHUB_OUTPUT\"\n # Export cache to environment for review step\n EOF_MARKER=$(dd if=/dev/urandom bs=15 count=1 status=none | base64)\n echo \"REVIEW_CACHE<<${EOF_MARKER}\" >> \"$GITHUB_ENV\"\n echo \"$CACHE_CONTENT\" >> \"$GITHUB_ENV\"\n echo \"${EOF_MARKER}\" >> \"$GITHUB_ENV\"\n else\n echo \"::warning::Cache file is invalid JSON, ignoring\"\n echo \"cache_exists=false\" >> \"$GITHUB_OUTPUT\"\n fi\n else\n echo \"::warning::Cache file exists but cannot be read: $CACHE_CONTENT\"\n echo \"cache_exists=false\" >> \"$GITHUB_OUTPUT\"\n fi\n else\n echo \"No cache file found, will create new one\"\n echo \"cache_exists=false\" >> \"$GITHUB_OUTPUT\"\n fi\n\n - name: Run skill reviews\n if: steps.detect.outputs.skills != ''\n id: review\n env:\n SKILLS: ${{ steps.detect.outputs.skills }}\n TESSL_API_KEY: ${{ secrets.TESSL_API_KEY }}\n run: |\n FAILED=0\n TABLE=\"| Skill | Status | Review Score | Change |\"\n TABLE=\"${TABLE}\\\\n|-------|--------|--------------|--------|\"\n DETAILS=\"\"\n\n # Create temporary file for cache entries\n CACHE_FILE_TEMP=\"cache-entries.tsv\"\n echo \"Cache entries file: $CACHE_FILE_TEMP\"\n\n while IFS= read -r dir; do\n [[ -z \"$dir\" ]] && continue\n echo \"::group::Reviewing $dir\"\n\n # Run review with --json flag\n JSON_OUTPUT=$(tessl skill review --json \"$dir\" 2>&1)\n echo \"$JSON_OUTPUT\"\n echo \"::endgroup::\"\n\n # Extract JSON (skip everything before first '{')\n JSON=$(echo \"$JSON_OUTPUT\" | sed -n '/{/,$p')\n\n # Look up previous score from cache\n PREV_SCORE=\"\"\n PREV_DESC=\"\"\n PREV_CONTENT=\"\"\n if [[ -n \"$REVIEW_CACHE\" ]]; then\n CACHE_ENTRY=$(echo \"$REVIEW_CACHE\" | jq -r --arg path \"$dir\" '.skills[$path] // empty')\n if [[ -n \"$CACHE_ENTRY\" ]]; then\n PREV_SCORE=$(echo \"$CACHE_ENTRY\" | jq -r '.score // empty')\n PREV_DESC=$(echo \"$CACHE_ENTRY\" | jq -r '.dimensions.description // empty')\n PREV_CONTENT=$(echo \"$CACHE_ENTRY\" | jq -r '.dimensions.content // empty')\n fi\n fi\n\n # Validate PREV_SCORE is numeric\n if [[ -n \"$PREV_SCORE\" && ! \"$PREV_SCORE\" =~ ^[0-9]+$ ]]; then\n echo \"::warning::Invalid previous score for $dir: $PREV_SCORE, ignoring\"\n PREV_SCORE=\"\"\n fi\n\n # Validate PREV_DESC and PREV_CONTENT are numeric\n if [[ -n \"$PREV_DESC\" && ! \"$PREV_DESC\" =~ ^[0-9]+$ ]]; then\n echo \"::warning::Invalid previous description score for $dir: $PREV_DESC, ignoring\"\n PREV_DESC=\"\"\n fi\n if [[ -n \"$PREV_CONTENT\" && ! \"$PREV_CONTENT\" =~ ^[0-9]+$ ]]; then\n echo \"::warning::Invalid previous content score for $dir: $PREV_CONTENT, ignoring\"\n PREV_CONTENT=\"\"\n fi\n\n # Extract fields via jq\n PASSED=$(echo \"$JSON\" | jq -r '.validation.overallPassed // false')\n\n # Calculate average score from all 8 dimensions\n AVG_SCORE=$(echo \"$JSON\" | jq -r '\n def avg(obj): (obj.scores | to_entries | map(.value.score) | add) / (obj.scores | length) * 100 / 3;\n (\n [(.descriptionJudge.evaluation | avg(.)), (.contentJudge.evaluation | avg(.))] | add / 2\n ) | round\n ')\n\n # Validate AVG_SCORE is numeric before arithmetic\n if [[ ! \"$AVG_SCORE\" =~ ^[0-9]+$ ]]; then\n echo \"::error::Invalid average score calculated for $dir: $AVG_SCORE\"\n AVG_SCORE=0\n fi\n\n # Calculate diff\n CHANGE=\"\"\n if [[ -n \"$PREV_SCORE\" ]]; then\n DIFF=$((AVG_SCORE - PREV_SCORE))\n if [[ $DIFF -gt 0 ]]; then\n CHANGE=\"šŗ +${DIFF}% (was ${PREV_SCORE}%)\"\n elif [[ $DIFF -lt 0 ]]; then\n CHANGE=\"š» ${DIFF}% (was ${PREV_SCORE}%)\"\n else\n CHANGE=\"ā”ļø no change\"\n fi\n fi\n\n # Build status column\n if [[ \"$PASSED\" == \"true\" ]]; then\n STATUS=\"ā PASSED\"\n else\n # Extract first validation error\n ERROR=$(echo \"$JSON\" | jq -r '\n .validation.checks\n | map(select(.status != \"passed\"))\n | first\n | .message // \"Validation failed\"\n ' | cut -c1-60)\n STATUS=\"ā FAILED ā ${ERROR}\"\n FAILED=1\n fi\n\n DIR_DISPLAY=$(echo \"$dir\" | tr '|' '/')\n TABLE=\"${TABLE}\\\\n| \\`${DIR_DISPLAY}\\` | ${STATUS} | ${AVG_SCORE}% | ${CHANGE} |\"\n\n # Calculate dimension scores for cache and details\n DESC_SCORE=$(echo \"$JSON\" | jq -r '\n (.descriptionJudge.evaluation.scores | to_entries | map(.value.score) | add) * 100 / ((.descriptionJudge.evaluation.scores | length) * 3) | round\n ')\n CONTENT_SCORE=$(echo \"$JSON\" | jq -r '\n (.contentJudge.evaluation.scores | to_entries | map(.value.score) | add) * 100 / ((.contentJudge.evaluation.scores | length) * 3) | round\n ')\n\n # Validate dimension scores\n if [[ ! \"$DESC_SCORE\" =~ ^[0-9]+$ ]]; then\n echo \"::warning::Invalid description score for $dir: $DESC_SCORE, using 0\"\n DESC_SCORE=0\n fi\n if [[ ! \"$CONTENT_SCORE\" =~ ^[0-9]+$ ]]; then\n echo \"::warning::Invalid content score for $dir: $CONTENT_SCORE, using 0\"\n CONTENT_SCORE=0\n fi\n\n # --- Extract detailed review for collapsible section ---\n DESC_EVAL=$(echo \"$JSON\" | jq -r '.descriptionJudge.evaluation |\n \" Description: \" + ((.scores | to_entries | map(.value.score) | add) * 100 / ((.scores | length) * 3) | round | tostring) + \"%\\\\n\" +\n (.scores | to_entries | map(\" \\(.key): \\(.value.score)/3 - \\(.value.reasoning)\") | join(\"\\\\n\")) + \"\\\\n\\\\n\" +\n \" Assessment: \" + .overall_assessment\n ')\n\n CONTENT_EVAL=$(echo \"$JSON\" | jq -r '.contentJudge.evaluation |\n \" Content: \" + ((.scores | to_entries | map(.value.score) | add) * 100 / ((.scores | length) * 3) | round | tostring) + \"%\\\\n\" +\n (.scores | to_entries | map(\" \\(.key): \\(.value.score)/3 - \\(.value.reasoning)\") | join(\"\\\\n\")) + \"\\\\n\\\\n\" +\n \" Assessment: \" + .overall_assessment\n ')\n\n # Extract suggestions\n SUGGESTIONS=$(echo \"$JSON\" | jq -r '\n [.descriptionJudge.evaluation.suggestions // [], .contentJudge.evaluation.suggestions // []]\n | flatten\n | map(\"- \" + .)\n | join(\"\\\\n\")\n ')\n\n # Build collapsible details block\n DETAILS=\"${DETAILS}\\\\n\\\\n\\\\n${DIR_DISPLAY} ā ${AVG_SCORE}% (${STATUS#* })\\\\n\\\\n\"\n\n # Show score comparison if previous exists (all three must be valid)\n if [[ -n \"$PREV_SCORE\" && -n \"$PREV_DESC\" && -n \"$PREV_CONTENT\" ]]; then\n DETAILS=\"${DETAILS}**Previous:** ${PREV_SCORE}% (Description: ${PREV_DESC}%, Content: ${PREV_CONTENT}%)\\\\n\"\n DETAILS=\"${DETAILS}**Current:** ${AVG_SCORE}% (Description: ${DESC_SCORE}%, Content: ${CONTENT_SCORE}%)\\\\n\\\\n\"\n DETAILS=\"${DETAILS}---\\\\n\\\\n\"\n fi\n\n DETAILS=\"${DETAILS}\\`\\`\\`\\\\n${DESC_EVAL}\\\\n\\\\n${CONTENT_EVAL}\\\\n\\`\\`\\`\\\\n\"\n\n if [[ -n \"$SUGGESTIONS\" ]]; then\n DETAILS=\"${DETAILS}\\\\n**Suggestions:**\\\\n\\\\n${SUGGESTIONS}\\\\n\"\n fi\n\n DETAILS=\"${DETAILS}\\\\n\"\n\n # Calculate content hash\n if [[ ! -f \"$dir/SKILL.md\" ]]; then\n echo \"::error::SKILL.md not found for $dir\"\n continue\n fi\n CONTENT_HASH=$(shasum -a 256 \"$dir/SKILL.md\" 2>&1)\n if [[ $? -ne 0 ]]; then\n echo \"::error::Failed to calculate hash for $dir: $CONTENT_HASH\"\n continue\n fi\n CONTENT_HASH=\"sha256:$(echo \"$CONTENT_HASH\" | awk '{print $1}')\"\n\n # Build cache entry (compact to single line)\n if ! CACHE_ENTRY=$(jq -nc \\\n --arg score \"$AVG_SCORE\" \\\n --arg passed \"$PASSED\" \\\n --arg hash \"$CONTENT_HASH\" \\\n --arg ts \"$(date -u +\"%Y-%m-%dT%H:%M:%SZ\")\" \\\n --arg desc \"$DESC_SCORE\" \\\n --arg content \"$CONTENT_SCORE\" \\\n '{\n score: ($score | tonumber),\n validation_passed: ($passed == \"true\"),\n content_hash: $hash,\n timestamp: $ts,\n dimensions: {\n description: ($desc | tonumber),\n content: ($content | tonumber)\n }\n }'); then\n echo \"::error::Failed to build cache entry for $dir\"\n continue\n fi\n\n # Write cache entry to file (tab-separated: pathjson)\n printf '%s\\t%s\\n' \"$dir\" \"$CACHE_ENTRY\" >> \"$CACHE_FILE_TEMP\"\n\n done <<< \"$SKILLS\"\n\n # Save cache entries file path for update step\n echo \"CACHE_ENTRIES_FILE=$CACHE_FILE_TEMP\" >> \"$GITHUB_ENV\"\n echo \"Wrote $(wc -l < \"$CACHE_FILE_TEMP\") cache entries to $CACHE_FILE_TEMP\"\n\n # Build PR comment body\n COMMENT_BODY=$(printf '%b' \"\\\\n## Tessl Skill Review Results\\\\n\\\\n${TABLE}\\\\n\\\\n---\\\\n\\\\n### Detailed Review\\\\n${DETAILS}\\\\n\\\\n---\\\\n_Checks: frontmatter validity, required fields, body structure, examples, line count._\\\\n_Review score is informational ā not used for pass/fail gating._\")\n\n EOF_MARKER=$(dd if=/dev/urandom bs=15 count=1 status=none | base64)\n echo \"comment<<${EOF_MARKER}\" >> \"$GITHUB_OUTPUT\"\n echo \"$COMMENT_BODY\" >> \"$GITHUB_OUTPUT\"\n echo \"${EOF_MARKER}\" >> \"$GITHUB_OUTPUT\"\n\n echo \"$COMMENT_BODY\" >> \"$GITHUB_STEP_SUMMARY\"\n\n if [[ \"$FAILED\" -eq 1 ]]; then\n echo \"::error::One or more skills failed validation checks.\"\n exit 1\n fi\n\n - name: Update review cache\n if: always() && steps.review.outcome != 'skipped'\n id: update-cache\n run: |\n CACHE_FILE=\".github/.tessl/skill-review-cache.json\"\n mkdir -p .github/.tessl\n\n # Load existing cache or create new structure\n if [[ -f \"$CACHE_FILE\" ]]; then\n if CACHE=$(cat \"$CACHE_FILE\" 2>&1); then\n if ! echo \"$CACHE\" | jq empty 2>/dev/null; then\n echo \"::warning::Cache file is invalid JSON, recreating\"\n CACHE='{\"version\":\"1\",\"last_updated\":\"\",\"skills\":{}}'\n fi\n else\n echo \"::warning::Cache file exists but cannot be read: $CACHE\"\n CACHE='{\"version\":\"1\",\"last_updated\":\"\",\"skills\":{}}'\n fi\n else\n echo \"Creating new cache file...\"\n CACHE='{\"version\":\"1\",\"last_updated\":\"\",\"skills\":{}}'\n fi\n\n # Update timestamp\n TIMESTAMP=$(date -u +\"%Y-%m-%dT%H:%M:%SZ\")\n if ! CACHE=$(echo \"$CACHE\" | jq --arg ts \"$TIMESTAMP\" '.last_updated = $ts'); then\n echo \"::error::Failed to update cache timestamp\"\n exit 1\n fi\n\n # Merge cache updates (using TAB delimiter)\n MERGED_COUNT=0\n FAILED_COUNT=0\n\n if [[ -f \"$CACHE_ENTRIES_FILE\" ]]; then\n while IFS=$'\\t' read -r skill_path entry_json; do\n [[ -z \"$skill_path\" ]] && continue\n if NEW_CACHE=$(echo \"$CACHE\" | jq --arg path \"$skill_path\" --argjson entry \"$entry_json\" \\\n '.skills[$path] = $entry' 2>&1); then\n CACHE=\"$NEW_CACHE\"\n MERGED_COUNT=$((MERGED_COUNT + 1))\n else\n echo \"::warning::Failed to merge cache entry for $skill_path: $NEW_CACHE\"\n FAILED_COUNT=$((FAILED_COUNT + 1))\n continue\n fi\n done < \"$CACHE_ENTRIES_FILE\"\n fi\n\n # Write cache file\n if ! echo \"$CACHE\" | jq '.' > \"$CACHE_FILE\"; then\n echo \"::error::Failed to write cache file\"\n exit 1\n fi\n\n # Report accurate merge counts\n if [[ $FAILED_COUNT -gt 0 ]]; then\n echo \"Cache updated with $MERGED_COUNT entries ($FAILED_COUNT failed)\"\n else\n echo \"Cache updated with $MERGED_COUNT entries\"\n fi\n\n - name: Upload cache file\n if: always() && steps.update-cache.outcome == 'success'\n uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0\n with:\n name: skill-review-cache\n path: .github/.tessl/skill-review-cache.json\n\n - name: Upload cache entries artifact\n if: always() && steps.review.outcome != 'skipped'\n uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0\n with:\n name: cache-entries\n path: cache-entries.tsv\n retention-days: 1\n\n - name: Save PR comment artifact\n if: >-\n github.event_name == 'pull_request'\n && steps.detect.outputs.skills != ''\n && (steps.review.outcome == 'success' || steps.review.outputs.comment != '')\n env:\n COMMENT_BODY: ${{ steps.review.outputs.comment }}\n PR_NUMBER: ${{ github.event.pull_request.number }}\n run: |\n mkdir -p pr-comment\n echo \"$PR_NUMBER\" > pr-comment/pr_number\n echo \"$COMMENT_BODY\" > pr-comment/comment.md\n\n - name: Upload PR comment artifact\n if: >-\n github.event_name == 'pull_request'\n && steps.detect.outputs.skills != ''\n && (steps.review.outcome == 'success' || steps.review.outputs.comment != '')\n uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0\n with:\n name: skill-review-comment\n path: pr-comment/\n\n commit-cache:\n name: Commit Cache\n runs-on: ubuntu-latest\n needs: review-skills\n if: github.event_name == 'push' && github.ref == 'refs/heads/main'\n permissions:\n contents: write\n\n steps:\n - name: Checkout repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 0\n\n - name: Download cache file\n uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1\n with:\n name: skill-review-cache\n\n - name: Move cache to correct location\n run: |\n mkdir -p .github/.tessl\n mv skill-review-cache.json .github/.tessl/skill-review-cache.json\n\n - name: Check for cache changes\n id: check\n run: |\n if git diff --quiet HEAD .github/.tessl/skill-review-cache.json; then\n echo \"changed=false\" >> \"$GITHUB_OUTPUT\"\n else\n echo \"changed=true\" >> \"$GITHUB_OUTPUT\"\n fi\n\n - name: Commit cache\n if: steps.check.outputs.changed == 'true'\n run: |\n git config user.name \"github-actions[bot]\"\n git config user.email \"github-actions[bot]@users.noreply.github.com\"\n git add .github/.tessl/skill-review-cache.json\n git commit -m \"chore: update skill review cache [skip ci]\"\n if ! git push; then\n echo \"::error::Failed to push cache update to main\"\n exit 1\n fi\n"
},
{
"path": ".github/workflows/validate.yml",
"content": "name: Validate Structure\n\non:\n push:\n branches: [main]\n pull_request:\n branches: [main]\n\npermissions:\n contents: read\n\njobs:\n validate-structure:\n name: Validate Repository Structure\n runs-on: ubuntu-latest\n\n steps:\n - name: Checkout repository\n uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1\n\n - name: Validate structure\n run: |\n chmod +x ./scripts/validate-structure.sh\n ./scripts/validate-structure.sh\n\n validate-json:\n name: Validate JSON Files\n runs-on: ubuntu-latest\n\n steps:\n - name: Checkout repository\n uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1\n\n - name: Validate all JSON files\n run: |\n echo \"Validating all JSON files...\"\n ERRORS=0\n\n for file in $(find . -name \"*.json\" -not -path \"./node_modules/*\" -not -path \"./.git/*\"); do\n if ! jq empty \"$file\" 2>/dev/null; then\n echo \"ERROR: Invalid JSON in $file\"\n ERRORS=$((ERRORS + 1))\n else\n echo \"OK: $file\"\n fi\n done\n\n if [[ \"$ERRORS\" -gt 0 ]]; then\n echo \"Found $ERRORS invalid JSON file(s)\"\n exit 1\n fi\n\n echo \"All JSON files are valid!\"\n\n validate-skills:\n name: Validate SKILL.md Files\n runs-on: ubuntu-latest\n\n steps:\n - name: Checkout repository\n uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1\n\n - name: Check SKILL.md frontmatter\n run: |\n echo \"Validating SKILL.md files...\"\n ERRORS=0\n\n for skill_file in $(find . -name \"SKILL.md\" -not -path \"./node_modules/*\"); do\n echo \"Checking: $skill_file\"\n\n # Check file starts with frontmatter\n if ! head -1 \"$skill_file\" | grep -q \"^---\"; then\n echo \"ERROR: $skill_file does not start with frontmatter (---)\"\n ERRORS=$((ERRORS + 1))\n continue\n fi\n\n # Extract frontmatter\n FRONTMATTER=$(sed -n '/^---$/,/^---$/p' \"$skill_file\" | sed '1d;$d')\n\n # Check for required fields\n if ! echo \"$FRONTMATTER\" | grep -q \"^name:\"; then\n echo \"ERROR: $skill_file missing 'name' in frontmatter\"\n ERRORS=$((ERRORS + 1))\n fi\n\n if ! echo \"$FRONTMATTER\" | grep -q \"^description:\"; then\n echo \"ERROR: $skill_file missing 'description' in frontmatter\"\n ERRORS=$((ERRORS + 1))\n fi\n done\n\n if [[ \"$ERRORS\" -gt 0 ]]; then\n echo \"Found $ERRORS error(s) in SKILL.md files\"\n exit 1\n fi\n\n echo \"All SKILL.md files are valid!\"\n\n validate-marketplace-references:\n name: Validate Marketplace References\n runs-on: ubuntu-latest\n\n steps:\n - name: Checkout repository\n uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1\n\n - name: Check marketplace plugin references\n run: |\n echo \"Validating marketplace.json plugin references...\"\n ERRORS=0\n\n MARKETPLACE=\".claude-plugin/marketplace.json\"\n\n if [[ ! -f \"$MARKETPLACE\" ]]; then\n echo \"ERROR: marketplace.json not found\"\n exit 1\n fi\n\n # Check each plugin source path exists\n for source in $(jq -r '.plugins[].source' \"$MARKETPLACE\"); do\n # Remove leading ./\n path=\"${source#./}\"\n\n if [[ ! -d \"$path\" ]]; then\n echo \"ERROR: Plugin path does not exist: $path\"\n ERRORS=$((ERRORS + 1))\n else\n echo \"OK: $path exists\"\n fi\n\n # Check plugin.json exists in that path\n if [[ ! -f \"$path/.claude-plugin/plugin.json\" ]]; then\n echo \"ERROR: plugin.json not found in $path/.claude-plugin/\"\n ERRORS=$((ERRORS + 1))\n else\n echo \"OK: $path/.claude-plugin/plugin.json exists\"\n fi\n\n # Check skills directory exists\n if [[ ! -d \"$path/skills\" ]]; then\n echo \"ERROR: skills/ directory not found in $path\"\n ERRORS=$((ERRORS + 1))\n else\n echo \"OK: $path/skills/ exists\"\n fi\n done\n\n if [[ \"$ERRORS\" -gt 0 ]]; then\n echo \"Found $ERRORS error(s) in marketplace references\"\n exit 1\n fi\n\n echo \"All marketplace references are valid!\"\n"
},
{
"path": "AGENTS.md",
"content": "# Agent Instructions\n\nThis repository contains agent skills and Claude Code plugins for HashiCorp products, including Terraform and Packer for infrastructure-as-code development.\n\n## Repository Structure\n\n```\nagent-skills/\nāāā terraform/\nā āāā code-generation/\nā ā āāā .claude-plugin/plugin.json\nā ā āāā skills/\nā ā āāā azure-verified-modules/\nā ā āāā terraform-style-guide/\nā ā āāā terraform-test/\nā ā āāā terraform-search-import/\nā āāā module-generation/\nā ā āāā .claude-plugin/plugin.json\nā ā āāā skills/\nā ā āāā refactor-module/\nā ā āāā terraform-stacks/\nā āāā provider-development/\nā āāā .claude-plugin/plugin.json\nā āāā skills/\nā āāā new-terraform-provider/\nā āāā run-acceptance-tests/\nā āāā provider-actions/\nā āāā provider-resources/\nāāā packer/\nā āāā builders/\nā ā āāā .claude-plugin/plugin.json\nā ā āāā skills/\nā ā āāā aws-ami-builder/\nā ā āāā azure-image-builder/\nā ā āāā windows-builder/\nā āāā hcp/\nā āāā .claude-plugin/plugin.json\nā āāā skills/\nā āāā push-to-registry/\nāāā .claude-plugin/marketplace.json\nāāā README.md\nāāā AGENTS.md\n```\n\n## Installation Methods\n\n### Method 1: Claude Code Plugin Installation\n\nInstall plugins using Claude Code CLI. First add the marketplace, then install plugins:\n\n```bash\n# Add the agent-skills marketplace\nclaude plugin marketplace add hashicorp/agent-skills\n\n# Install plugins\nclaude plugin install terraform-code-generation@hashicorp\nclaude plugin install terraform-module-generation@hashicorp\nclaude plugin install terraform-provider-development@hashicorp\nclaude plugin install packer-builders@hashicorp\nclaude plugin install packer-hcp@hashicorp\n```\n\nOr use the interactive interface within Claude Code:\n```\n/plugin\n```\n\nThis opens a tabbed interface where you can:\n- **Discover**: Browse available plugins from all marketplaces\n- **Installed**: View and manage installed plugins\n- **Marketplaces**: Add, remove, or update marketplaces\n\nAdditional plugin management commands:\n```bash\n# Disable a plugin\nclaude plugin disable terraform-code-generation@hashicorp\n\n# Re-enable a plugin\nclaude plugin enable terraform-code-generation@hashicorp\n\n# Uninstall a plugin\nclaude plugin uninstall terraform-code-generation@hashicorp\n\n# Update a plugin\nclaude plugin update terraform-code-generation@hashicorp\n```\n\nInstallation scopes (use `--scope` flag):\n- `user` (default): Available across all projects\n- `project`: Shared with team via `.claude/settings.json`\n- `local`: Project-specific, gitignored\n\n### Method 2: Individual Skill Installation\n\nInstall individual skills using `npx skills add`:\n\n```bash\n# List all available skills\nnpx skills add hashicorp/agent-skills\n\n# Code generation skills\nnpx skills add hashicorp/agent-skills/terraform/code-generation/skills/terraform-style-guide\nnpx skills add hashicorp/agent-skills/terraform/code-generation/skills/terraform-test\nnpx skills add hashicorp/agent-skills/terraform/code-generation/skills/azure-verified-modules\nnpx skills add hashicorp/agent-skills/terraform/code-generation/skills/terraform-search-import\n\n# Module generation skills\nnpx skills add hashicorp/agent-skills/terraform/module-generation/skills/refactor-module\nnpx skills add hashicorp/agent-skills/terraform/module-generation/skills/terraform-stacks\n\n# Provider development skills\nnpx skills add hashicorp/agent-skills/terraform/provider-development/skills/new-terraform-provider\nnpx skills add hashicorp/agent-skills/terraform/provider-development/skills/run-acceptance-tests\nnpx skills add hashicorp/agent-skills/terraform/provider-development/skills/provider-actions\nnpx skills add hashicorp/agent-skills/terraform/provider-development/skills/provider-resources\n\n# Packer builder skills\nnpx skills add hashicorp/agent-skills/packer/builders/skills/aws-ami-builder\nnpx skills add hashicorp/agent-skills/packer/builders/skills/azure-image-builder\nnpx skills add hashicorp/agent-skills/packer/builders/skills/windows-builder\n\n# Packer HCP skills\nnpx skills add hashicorp/agent-skills/packer/hcp/skills/push-to-registry\n```\n\nSkills are installed to `~/.claude/skills/` or project `.claude/skills/` directory.\n\n### Method 3: Manual Installation\n\nCopy skills directly to your Claude Code configuration:\n\n```bash\n# Clone the repository\ngit clone https://github.com/hashicorp/agent-skills.git\n\n# Copy a plugin to Claude Code plugins directory\ncp -r agent-skills/terraform/code-generation ~/.claude/plugins/\n\n# Or copy individual skills\ncp -r agent-skills/terraform/code-generation/skills/terraform-style-guide ~/.claude/skills/\n```\n\n## Plugin Contents\n\n### terraform-code-generation\n\nSkills for generating and validating Terraform HCL code:\n\n| Skill | Description |\n|-------|-------------|\n| `terraform-style-guide` | Generate Terraform HCL code following HashiCorp style conventions and best practices |\n| `terraform-test` | Writing and running `.tftest.hcl` test files |\n| `azure-verified-modules` | Azure Verified Modules (AVM) requirements and certification |\n| `terraform-search-import` | Discover existing resources with Terraform Search and bulk import into state |\n\n### terraform-module-generation\n\nSkills for creating and refactoring Terraform modules:\n\n| Skill | Description |\n|-------|-------------|\n| `refactor-module` | Transform monolithic configs into reusable modules |\n| `terraform-stacks` | Multi-region/environment orchestration with Terraform Stacks |\n\n### terraform-provider-development\n\nSkills for developing Terraform providers:\n\n| Skill | Description |\n|-------|-------------|\n| `new-terraform-provider` | Scaffold a new Terraform provider |\n| `run-acceptance-tests` | Run and debug provider acceptance tests |\n| `provider-actions` | Implement provider actions (lifecycle operations) |\n| `provider-resources` | Implement resources and data sources |\n\n### packer-builders\n\nSkills for building images on AWS, Azure, and Windows:\n\n| Skill | Description |\n|-------|-------------|\n| `aws-ami-builder` | Build Amazon Machine Images (AMIs) with amazon-ebs builder |\n| `azure-image-builder` | Build Azure managed images and Azure Compute Gallery images |\n| `windows-builder` | Platform-agnostic Windows image patterns with WinRM and PowerShell |\n\n### packer-hcp\n\nSkills for HCP Packer registry integration:\n\n| Skill | Description |\n|-------|-------------|\n| `push-to-registry` | Configure hcp_packer_registry to push build metadata to HCP Packer |\n\n## Skill Format\n\nEach skill directory contains:\n- `SKILL.md` - Main skill definition with YAML frontmatter (`name`, `description`)\n- Optional `assets/`, `references/`, or `resources/` directories\n\n### SKILL.md Frontmatter\n\n```yaml\n---\nname: skill-name\ndescription: Brief description of when to use this skill.\n---\n```\n\n## When to Use Each Plugin\n\n### terraform-code-generation\nUse when:\n- Writing new Terraform configurations\n- Reviewing Terraform code for style compliance\n- Creating test files for Terraform modules\n- Generating HCL for specific providers\n\n### terraform-module-generation\nUse when:\n- Refactoring existing Terraform code into modules\n- Working with Terraform Stacks\n- Designing module interfaces and outputs\n- Managing multi-environment deployments\n\n### terraform-provider-development\nUse when:\n- Creating a new Terraform provider\n- Adding resources or data sources to an existing provider\n- Implementing provider actions\n- Running or debugging acceptance tests\n\n### packer-builders\nUse when:\n- Building AWS AMIs with amazon-ebs builder\n- Creating Azure managed images or Azure Compute Gallery images\n- Building Windows images (AWS, Azure, VMware, etc.)\n- Setting up WinRM and PowerShell provisioners\n- Troubleshooting Windows-specific image build issues\n\n### packer-hcp\nUse when:\n- Integrating Packer builds with HCP Packer registry\n- Tracking image metadata and versions\n- Setting up hcp_packer_registry block\n- Configuring CI/CD to push to HCP Packer\n- Querying HCP Packer images in Terraform\n\n## MCP Server Configuration\n\nAll Terraform plugins include MCP server configuration for the Terraform MCP Server:\n\n```json\n{\n \"mcpServers\": {\n \"terraform\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"-i\", \"--rm\", \"-e\", \"TFE_TOKEN\", \"-e\", \"TFE_ADDRESS\", \"hashicorp/terraform-mcp-server\"],\n \"env\": {\n \"TFE_TOKEN\": \"${TFE_TOKEN}\",\n \"TFE_ADDRESS\": \"${TFE_ADDRESS}\"\n }\n }\n }\n}\n```\n\nSet environment variables for HCP Terraform integration:\n- `TFE_TOKEN` - HCP Terraform API token\n- `TFE_ADDRESS` - HCP Terraform address (optional, defaults to app.terraform.io)\n\n## References\n\n- [Terraform Documentation](https://developer.hashicorp.com/terraform)\n- [Terraform Plugin Framework](https://developer.hashicorp.com/terraform/plugin/framework)\n- [Terraform MCP Server](https://github.com/hashicorp/terraform-mcp-server)\n- [Packer Documentation](https://developer.hashicorp.com/packer)\n- [HCP Packer](https://developer.hashicorp.com/hcp/docs/packer)\n- [Packer HCL2 Configuration](https://developer.hashicorp.com/packer/guides/hcl)\n- [Claude Code Plugins](https://docs.anthropic.com/claude-code/plugins)\n"
},
{
"path": "CHANGELOG.md",
"content": "# Changelog\n\nAll notable changes to the HashiCorp Agent Skills.\n\n## Unreleased\n\n### Added\n- `terraform-search-import` skill for discovering existing resources with Terraform Search and bulk import\n\n## 0.1.0\n\n### Added\n- 3 Claude Code plugins with 9 total skills\n- `terraform-code-generation`: terraform-style-guide, terraform-test, azure-verified-modules\n- `terraform-module-generation`: refactor-module, terraform-stacks\n- `terraform-provider-development`: new-terraform-provider, run-acceptance-tests, provider-actions, provider-resources\n- Marketplace manifest for Claude Code plugin installation\n- Support for `npx add-skill` installation\n"
},
{
"path": "CODEOWNERS",
"content": "# Default owner\n* @hashicorp/team-proj-mcp-servers\n"
},
{
"path": "LICENSE",
"content": "Mozilla Public License Version 2.0\n==================================\n\n1. Definitions\n--------------\n\n1.1. \"Contributor\"\n means each individual or legal entity that creates, contributes to\n the creation of, or owns Covered Software.\n\n1.2. \"Contributor Version\"\n means the combination of the Contributions of others (if any) used\n by a Contributor and that particular Contributor's Contribution.\n\n1.3. \"Contribution\"\n means Covered Software of a particular Contributor.\n\n1.4. \"Covered Software\"\n means Source Code Form to which the initial Contributor has attached\n the notice in Exhibit A, the Executable Form of such Source Code\n Form, and Modifications of such Source Code Form, in each case\n including portions thereof.\n\n1.5. \"Incompatible With Secondary Licenses\"\n means\n\n (a) that the initial Contributor has attached the notice described\n in Exhibit B to the Covered Software; or\n\n (b) that the Covered Software was made available under the terms of\n version 1.1 or earlier of the License, but not also under the\n terms of a Secondary License.\n\n1.6. \"Executable Form\"\n means any form of the work other than Source Code Form.\n\n1.7. \"Larger Work\"\n means a work that combines Covered Software with other material, in\n a separate file or files, that is not Covered Software.\n\n1.8. \"License\"\n means this document.\n\n1.9. \"Licensable\"\n means having the right to grant, to the maximum extent possible,\n whether at the time of the initial grant or subsequently, any and\n all of the rights conveyed by this License.\n\n1.10. \"Modifications\"\n means any of the following:\n\n (a) any file in Source Code Form that results from an addition to,\n deletion from, or modification of the contents of Covered\n Software; or\n\n (b) any new file in Source Code Form that contains any Covered\n Software.\n\n1.11. \"Patent Claims\" of a Contributor\n means any patent claim(s), including without limitation, method,\n process, and apparatus claims, in any patent Licensable by such\n Contributor that would be infringed, but for the grant of the\n License, by the making, using, selling, offering for sale, having\n made, import, or transfer of either its Contributions or its\n Contributor Version.\n\n1.12. \"Secondary License\"\n means either the GNU General Public License, Version 2.0, the GNU\n Lesser General Public License, Version 2.1, the GNU Affero General\n Public License, Version 3.0, or any later versions of those\n licenses.\n\n1.13. \"Source Code Form\"\n means the form of the work preferred for making modifications.\n\n1.14. \"You\" (or \"Your\")\n means an individual or a legal entity exercising rights under this\n License. For legal entities, \"You\" includes any entity that\n controls, is controlled by, or is under common control with You. For\n purposes of this definition, \"control\" means (a) the power, direct\n or indirect, to cause the direction or management of such entity,\n whether by contract or otherwise, or (b) ownership of more than\n fifty percent (50%) of the outstanding shares or beneficial\n ownership of such entity.\n\n2. License Grants and Conditions\n--------------------------------\n\n2.1. Grants\n\nEach Contributor hereby grants You a world-wide, royalty-free,\nnon-exclusive license:\n\n(a) under intellectual property rights (other than patent or trademark)\n Licensable by such Contributor to use, reproduce, make available,\n modify, display, perform, distribute, and otherwise exploit its\n Contributions, either on an unmodified basis, with Modifications, or\n as part of a Larger Work; and\n\n(b) under Patent Claims of such Contributor to make, use, sell, offer\n for sale, have made, import, and otherwise transfer either its\n Contributions or its Contributor Version.\n\n2.2. Effective Date\n\nThe licenses granted in Section 2.1 with respect to any Contribution\nbecome effective for each Contribution on the date the Contributor first\ndistributes such Contribution.\n\n2.3. Limitations on Grant Scope\n\nThe licenses granted in this Section 2 are the only rights granted under\nthis License. No additional rights or licenses will be implied from the\ndistribution or licensing of Covered Software under this License.\nNotwithstanding Section 2.1(b) above, no patent license is granted by a\nContributor:\n\n(a) for any code that a Contributor has removed from Covered Software;\n or\n\n(b) for infringements caused by: (i) Your and any other third party's\n modifications of Covered Software, or (ii) the combination of its\n Contributions with other software (except as part of its Contributor\n Version); or\n\n(c) under Patent Claims infringed by Covered Software in the absence of\n its Contributions.\n\nThis License does not grant any rights in the trademarks, service marks,\nor logos of any Contributor (except as may be necessary to comply with\nthe notice requirements in Section 3.4).\n\n2.4. Subsequent Licenses\n\nNo Contributor makes additional grants as a result of Your choice to\ndistribute the Covered Software under a subsequent version of this\nLicense (see Section 10.2) or under the terms of a Secondary License (if\npermitted under the terms of Section 3.3).\n\n2.5. Representation\n\nEach Contributor represents that the Contributor believes its\nContributions are its original creation(s) or it has sufficient rights\nto grant the rights to its Contributions conveyed by this License.\n\n2.6. Fair Use\n\nThis License is not intended to limit any rights You have under\napplicable copyright doctrines of fair use, fair dealing, or other\nequivalents.\n\n2.7. Conditions\n\nSections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted\nin Section 2.1.\n\n3. Responsibilities\n-------------------\n\n3.1. Distribution of Source Form\n\nAll distribution of Covered Software in Source Code Form, including any\nModifications that You create or to which You contribute, must be under\nthe terms of this License. You must inform recipients that the Source\nCode Form of the Covered Software is governed by the terms of this\nLicense, and how they can obtain a copy of this License. You may not\nattempt to alter or restrict the recipients' rights in the Source Code\nForm.\n\n3.2. Distribution of Executable Form\n\nIf You distribute Covered Software in Executable Form then:\n\n(a) such Covered Software must also be made available in Source Code\n Form, as described in Section 3.1, and You must inform recipients of\n the Executable Form how they can obtain a copy of such Source Code\n Form by reasonable means in a timely manner, at a charge no more\n than the cost of distribution to the recipient; and\n\n(b) You may distribute such Executable Form under the terms of this\n License, or sublicense it under different terms, provided that the\n license for the Executable Form does not attempt to limit or alter\n the recipients' rights in the Source Code Form under this License.\n\n3.3. Distribution of a Larger Work\n\nYou may create and distribute a Larger Work under terms of Your choice,\nprovided that You also comply with the requirements of this License for\nthe Covered Software. If the Larger Work is a combination of Covered\nSoftware with a work governed by one or more Secondary Licenses, and the\nCovered Software is not Incompatible With Secondary Licenses, this\nLicense permits You to additionally distribute such Covered Software\nunder the terms of such Secondary License(s), so that the recipient of\nthe Larger Work may, at their option, further distribute the Covered\nSoftware under the terms of either this License or such Secondary\nLicense(s).\n\n3.4. Notices\n\nYou may not remove or alter the substance of any license notices\n(including copyright notices, patent notices, disclaimers of warranty,\nor limitations of liability) contained within the Source Code Form of\nthe Covered Software, except that You may alter any license notices to\nthe extent required to remedy known factual inaccuracies.\n\n3.5. Application of Additional Terms\n\nYou may choose to offer, and to charge a fee for, warranty, support,\nindemnity or liability obligations to one or more recipients of Covered\nSoftware. However, You may do so only on Your own behalf, and not on\nbehalf of any Contributor. You must make it absolutely clear that any\nsuch warranty, support, indemnity, or liability obligation is offered by\nYou alone, and You hereby agree to indemnify every Contributor for any\nliability incurred by such Contributor as a result of warranty, support,\nindemnity or liability terms You offer. You may include additional\ndisclaimers of warranty and limitations of liability specific to any\njurisdiction.\n\n4. Inability to Comply Due to Statute or Regulation\n---------------------------------------------------\n\nIf it is impossible for You to comply with any of the terms of this\nLicense with respect to some or all of the Covered Software due to\nstatute, judicial order, or regulation then You must: (a) comply with\nthe terms of this License to the maximum extent possible; and (b)\ndescribe the limitations and the code they affect. Such description must\nbe placed in a text file included with all distributions of the Covered\nSoftware under this License. Except to the extent prohibited by statute\nor regulation, such description must be sufficiently detailed for a\nrecipient of ordinary skill to be able to understand it.\n\n5. Termination\n--------------\n\n5.1. The rights granted under this License will terminate automatically\nif You fail to comply with any of its terms. However, if You become\ncompliant, then the rights granted under this License from a particular\nContributor are reinstated (a) provisionally, unless and until such\nContributor explicitly and finally terminates Your grants, and (b) on an\nongoing basis, if such Contributor fails to notify You of the\nnon-compliance by some reasonable means prior to 60 days after You have\ncome back into compliance. Moreover, Your grants from a particular\nContributor are reinstated on an ongoing basis if such Contributor\nnotifies You of the non-compliance by some reasonable means, this is the\nfirst time You have received notice of non-compliance with this License\nfrom such Contributor, and You become compliant prior to 30 days after\nYour receipt of the notice.\n\n5.2. If You initiate litigation against any entity by asserting a patent\ninfringement claim (excluding declaratory judgment actions,\ncounter-claims, and cross-claims) alleging that a Contributor Version\ndirectly or indirectly infringes any patent, then the rights granted to\nYou by any and all Contributors for the Covered Software under Section\n2.1 of this License shall terminate.\n\n5.3. In the event of termination under Sections 5.1 or 5.2 above, all\nend user license agreements (excluding distributors and resellers) which\nhave been validly granted by You or Your distributors under this License\nprior to termination shall survive termination.\n\n************************************************************************\n* *\n* 6. Disclaimer of Warranty *\n* ------------------------- *\n* *\n* Covered Software is provided under this License on an \"as is\" *\n* basis, without warranty of any kind, either expressed, implied, or *\n* statutory, including, without limitation, warranties that the *\n* Covered Software is free of defects, merchantable, fit for a *\n* particular purpose or non-infringing. The entire risk as to the *\n* quality and performance of the Covered Software is with You. *\n* Should any Covered Software prove defective in any respect, You *\n* (not any Contributor) assume the cost of any necessary servicing, *\n* repair, or correction. This disclaimer of warranty constitutes an *\n* essential part of this License. No use of any Covered Software is *\n* authorized under this License except under this disclaimer. *\n* *\n************************************************************************\n\n************************************************************************\n* *\n* 7. Limitation of Liability *\n* -------------------------- *\n* *\n* Under no circumstances and under no legal theory, whether tort *\n* (including negligence), contract, or otherwise, shall any *\n* Contributor, or anyone who distributes Covered Software as *\n* permitted above, be liable to You for any direct, indirect, *\n* special, incidental, or consequential damages of any character *\n* including, without limitation, damages for lost profits, loss of *\n* goodwill, work stoppage, computer failure or malfunction, or any *\n* and all other commercial damages or losses, even if such party *\n* shall have been informed of the possibility of such damages. This *\n* limitation of liability shall not apply to liability for death or *\n* personal injury resulting from such party's negligence to the *\n* extent applicable law prohibits such limitation. Some *\n* jurisdictions do not allow the exclusion or limitation of *\n* incidental or consequential damages, so this exclusion and *\n* limitation may not apply to You. *\n* *\n************************************************************************\n\n8. Litigation\n-------------\n\nAny litigation relating to this License may be brought only in the\ncourts of a jurisdiction where the defendant maintains its principal\nplace of business and such litigation shall be governed by laws of that\njurisdiction, without reference to its conflict-of-law provisions.\nNothing in this Section shall prevent a party's ability to bring\ncross-claims or counter-claims.\n\n9. Miscellaneous\n----------------\n\nThis License represents the complete agreement concerning the subject\nmatter hereof. If any provision of this License is held to be\nunenforceable, such provision shall be reformed only to the extent\nnecessary to make it enforceable. Any law or regulation which provides\nthat the language of a contract shall be construed against the drafter\nshall not be used to construe this License against a Contributor.\n\n10. Versions of the License\n---------------------------\n\n10.1. New Versions\n\nMozilla Foundation is the license steward. Except as provided in Section\n10.3, no one other than the license steward has the right to modify or\npublish new versions of this License. Each version will be given a\ndistinguishing version number.\n\n10.2. Effect of New Versions\n\nYou may distribute the Covered Software under the terms of the version\nof the License under which You originally received the Covered Software,\nor under the terms of any subsequent version published by the license\nsteward.\n\n10.3. Modified Versions\n\nIf you create software not governed by this License, and you want to\ncreate a new license for such software, you may create and use a\nmodified version of this License if you rename the license and remove\nany references to the name of the license steward (except to note that\nsuch modified license differs from this License).\n\n10.4. Distributing Source Code Form that is Incompatible With Secondary\nLicenses\n\nIf You choose to distribute Source Code Form that is Incompatible With\nSecondary Licenses under the terms of this version of the License, the\nnotice described in Exhibit B of this License must be attached.\n\nExhibit A - Source Code Form License Notice\n-------------------------------------------\n\n This Source Code Form is subject to the terms of the Mozilla Public\n License, v. 2.0. If a copy of the MPL was not distributed with this\n file, You can obtain one at https://mozilla.org/MPL/2.0/.\n\nIf it is not possible or desirable to put the notice in a particular\nfile, then You may include the notice in a location (such as a LICENSE\nfile in a relevant directory) where a recipient would be likely to look\nfor such a notice.\n\nYou may add additional accurate notices of copyright ownership.\n\nExhibit B - \"Incompatible With Secondary Licenses\" Notice\n---------------------------------------------------------\n\n This Source Code Form is \"Incompatible With Secondary Licenses\", as\n defined by the Mozilla Public License, v. 2.0.\n"
},
{
"path": "README.md",
"content": "# HashiCorp Agent Skills\n\nA collection of Agent skills and Claude Code plugins for HashiCorp products.\n\n| Product | Use cases |\n|:--------|:----------|\n| [Terraform](./terraform/) | Write HCL code, build modules, develop providers, and run tests |\n| [Packer](./packer/) | Build machine images on AWS, Azure, and Windows; integrate with HCP Packer registry |\n\n> **Legal Note:** Your use of a third party MCP Client/LLM is subject solely to the terms of use for such MCP/LLM, and IBM is not responsible for the performance of such third party tools. IBM expressly disclaims any and all warranties and liability for third party MCP Clients/LLMs, and may not be able to provide support to resolve issues which are caused by the third party tools.\n\n## Installation\n\n### Individual Skills\n\nInstall Agent Skills in GitHub Copilot, Claude Code, Opencode, Cursor, and more:\n\n```bash\n# List all skills\nnpx skills add hashicorp/agent-skills\n\n# Install a specific skill\nnpx skills add hashicorp/agent-skills/terraform/code-generation/skills/terraform-style-guide\n```\n\n### Claude Code Plugin\n\nFirst, add the marketplace, then install plugins:\n\n```bash\n# Add the HashiCorp marketplace\nclaude plugin marketplace add hashicorp/agent-skills\n\n# Install plugins\nclaude plugin install terraform-code-generation@hashicorp\nclaude plugin install terraform-module-generation@hashicorp\nclaude plugin install terraform-provider-development@hashicorp\nclaude plugin install packer-builders@hashicorp\nclaude plugin install packer-hcp@hashicorp\n```\n\nOr use the interactive interface:\n```bash\n/plugin\n```\n\n## Structure\n\n```\nagent-skills/\nāāā .claude-plugin/\nā āāā marketplace.json\nāāā terraform/ # Terraform skills\nāāā packer/ # Packer skills\nāāā / # Future products (Vault, Consul, etc.)\nāāā README.md\n```\n\nEach product folder contains plugins, and each plugin contains skills:\n\n```\n/\nāāā /\n āāā .claude-plugin/plugin.json\n āāā skills/\n āāā /\n āāā SKILL.md\n```\n\n## License\n\nMPL-2.0\n"
},
{
"path": "packer/README.md",
"content": "# Packer Skills\n\nAgent skills for building machine images with Packer and HCP Packer.\n\n## Plugins\n\n### packer-builders\n\nSkills for building images on AWS, Azure, and Windows.\n\n| Skill | Description |\n|-------|-------------|\n| aws-ami-builder | Build Amazon Machine Images (AMIs) with amazon-ebs builder |\n| azure-image-builder | Build Azure managed images and Azure Compute Gallery images |\n| windows-builder | Platform-agnostic Windows image patterns with WinRM and PowerShell |\n\n### packer-hcp\n\nSkills for HCP Packer registry integration.\n\n| Skill | Description |\n|-------|-------------|\n| push-to-registry | Configure hcp_packer_registry to push build metadata to HCP Packer |\n\n## Installation\n\n### Claude Code Plugin\n\n```bash\nclaude plugin marketplace add hashicorp/agent-skills\n\nclaude plugin install packer-builders@hashicorp\nclaude plugin install packer-hcp@hashicorp\n```\n\n### Individual Skills\n\n```bash\n# Builders\nnpx skills add hashicorp/agent-skills/packer/builders/skills/aws-ami-builder\nnpx skills add hashicorp/agent-skills/packer/builders/skills/azure-image-builder\nnpx skills add hashicorp/agent-skills/packer/builders/skills/windows-builder\n\n# HCP Packer\nnpx skills add hashicorp/agent-skills/packer/hcp/skills/push-to-registry\n```\n\n## Structure\n\n```\npacker/\nāāā builders/\nā āāā .claude-plugin/plugin.json\nā āāā skills/\nā āāā aws-ami-builder/\nā āāā azure-image-builder/\nā āāā windows-builder/\nāāā hcp/\n āāā .claude-plugin/plugin.json\n āāā skills/\n āāā push-to-registry/\n```\n\n## References\n\n- [Packer Documentation](https://developer.hashicorp.com/packer)\n- [HCP Packer](https://developer.hashicorp.com/hcp/docs/packer)\n- [Amazon EBS Builder](https://developer.hashicorp.com/packer/integrations/hashicorp/amazon/latest/components/builder/ebs)\n- [Azure ARM Builder](https://developer.hashicorp.com/packer/integrations/hashicorp/azure/latest/components/builder/arm)\n"
},
{
"path": "packer/builders/.claude-plugin/plugin.json",
"content": "{\n \"name\": \"packer-builders\",\n \"version\": \"1.0.0\",\n \"description\": \"Packer builder skills for AWS, Azure, and Windows image creation.\",\n \"author\": {\n \"name\": \"HashiCorp\",\n \"url\": \"https://github.com/hashicorp\"\n },\n \"homepage\": \"https://developer.hashicorp.com/packer\",\n \"repository\": \"https://github.com/hashicorp/agent-skills\",\n \"license\": \"MPL-2.0\",\n \"keywords\": [\"packer\", \"aws\", \"azure\", \"windows\", \"ami\", \"image\", \"builder\"]\n}\n"
},
{
"path": "packer/builders/skills/aws-ami-builder/SKILL.md",
"content": "---\nname: aws-ami-builder\ndescription: Build Amazon Machine Images (AMIs) with Packer using the amazon-ebs builder. Use when creating custom AMIs for EC2 instances.\n---\n\n# AWS AMI Builder\n\nBuild Amazon Machine Images (AMIs) using Packer's `amazon-ebs` builder.\n\n**Reference:** [Amazon EBS Builder](https://developer.hashicorp.com/packer/integrations/hashicorp/amazon/latest/components/builder/ebs)\n\n> **Note:** Building AMIs incurs AWS costs (EC2 instances, EBS storage, data transfer). Builds typically take 10-30 minutes depending on provisioning complexity.\n\n## Basic AMI Template\n\n```hcl\npacker {\n required_plugins {\n amazon = {\n source = \"github.com/hashicorp/amazon\"\n version = \"~> 1.3\"\n }\n }\n}\n\nvariable \"region\" {\n type = string\n default = \"us-west-2\"\n}\n\nlocals {\n timestamp = regex_replace(timestamp(), \"[- TZ:]\", \"\")\n}\n\nsource \"amazon-ebs\" \"ubuntu\" {\n region = var.region\n instance_type = \"t3.micro\"\n\n source_ami_filter {\n filters = {\n name = \"ubuntu/images/*ubuntu-jammy-22.04-amd64-server-*\"\n root-device-type = \"ebs\"\n virtualization-type = \"hvm\"\n }\n most_recent = true\n owners = [\"099720109477\"] # Canonical\n }\n\n ssh_username = \"ubuntu\"\n ami_name = \"my-app-${local.timestamp}\"\n\n tags = {\n Name = \"my-app\"\n BuildDate = local.timestamp\n }\n}\n\nbuild {\n sources = [\"source.amazon-ebs.ubuntu\"]\n\n provisioner \"shell\" {\n inline = [\n \"sudo apt-get update\",\n \"sudo apt-get upgrade -y\",\n ]\n }\n}\n```\n\n## Common Source AMI Filters\n\n### Ubuntu 22.04 LTS\n```hcl\nsource_ami_filter {\n filters = {\n name = \"ubuntu/images/*ubuntu-jammy-22.04-amd64-server-*\"\n root-device-type = \"ebs\"\n virtualization-type = \"hvm\"\n }\n most_recent = true\n owners = [\"099720109477\"] # Canonical\n}\n```\n\n### Amazon Linux 2023\n```hcl\nsource_ami_filter {\n filters = {\n name = \"al2023-ami-*-x86_64\"\n root-device-type = \"ebs\"\n virtualization-type = \"hvm\"\n }\n most_recent = true\n owners = [\"amazon\"]\n}\n```\n\n## Multi-Region AMI\n\n```hcl\nsource \"amazon-ebs\" \"ubuntu\" {\n region = \"us-west-2\"\n instance_type = \"t3.micro\"\n\n source_ami_filter {\n filters = {\n name = \"ubuntu/images/*ubuntu-jammy-22.04-amd64-server-*\"\n }\n most_recent = true\n owners = [\"099720109477\"]\n }\n\n ssh_username = \"ubuntu\"\n ami_name = \"my-app-${local.timestamp}\"\n\n # Copy to additional regions\n ami_regions = [\"us-east-1\", \"us-east-2\", \"eu-west-1\"]\n}\n```\n\n## Authentication\n\nPacker uses AWS credential resolution:\n\n1. Environment variables: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`\n2. AWS credentials file: `~/.aws/credentials`\n3. IAM instance profile (when running on EC2)\n\n```bash\nexport AWS_ACCESS_KEY_ID=\"your-access-key\"\nexport AWS_SECRET_ACCESS_KEY=\"your-secret-key\"\nexport AWS_REGION=\"us-west-2\"\n\npacker build .\n```\n\n## Build Commands\n\n```bash\n# Initialize plugins\npacker init .\n\n# Validate template\npacker validate .\n\n# Build AMI\npacker build .\n\n# Build with variables\npacker build -var \"region=us-east-1\" .\n```\n\n## Common Issues\n\n**SSH Timeout**\n- Ensure security group allows SSH (port 22)\n- Verify subnet has internet access\n\n**AMI Already Exists**\n- AMI names must be unique\n- Use timestamp in name: `my-app-${local.timestamp}`\n\n**Volume Size Too Small**\n- Check source AMI's volume size\n- Set `launch_block_device_mappings.volume_size` accordingly\n\n## References\n\n- [Amazon EBS Builder](https://developer.hashicorp.com/packer/integrations/hashicorp/amazon/latest/components/builder/ebs)\n- [AWS AMI Documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html)\n"
},
{
"path": "packer/builders/skills/azure-image-builder/SKILL.md",
"content": "---\nname: azure-image-builder\ndescription: Build Azure managed images and Azure Compute Gallery images with Packer. Use when creating custom images for Azure VMs.\n---\n\n# Azure Image Builder\n\nBuild Azure managed images and Azure Compute Gallery images using Packer's `azure-arm` builder.\n\n**Reference:** [Azure ARM Builder](https://developer.hashicorp.com/packer/integrations/hashicorp/azure/latest/components/builder/arm)\n\n> **Note:** Building Azure images incurs costs (compute, storage, data transfer). Builds typically take 15-45 minutes depending on provisioning and OS.\n\n## Basic Managed Image\n\n```hcl\npacker {\n required_plugins {\n azure = {\n source = \"github.com/hashicorp/azure\"\n version = \"~> 2.0\"\n }\n }\n}\n\nvariable \"client_id\" {\n type = string\n sensitive = true\n}\n\nvariable \"client_secret\" {\n type = string\n sensitive = true\n}\n\nvariable \"subscription_id\" {\n type = string\n}\n\nvariable \"tenant_id\" {\n type = string\n}\n\nvariable \"resource_group\" {\n type = string\n default = \"packer-images-rg\"\n}\n\nlocals {\n timestamp = regex_replace(timestamp(), \"[- TZ:]\", \"\")\n}\n\nsource \"azure-arm\" \"ubuntu\" {\n client_id = var.client_id\n client_secret = var.client_secret\n subscription_id = var.subscription_id\n tenant_id = var.tenant_id\n\n managed_image_resource_group_name = var.resource_group\n managed_image_name = \"my-app-${local.timestamp}\"\n\n os_type = \"Linux\"\n image_publisher = \"Canonical\"\n image_offer = \"0001-com-ubuntu-server-jammy\"\n image_sku = \"22_04-lts-gen2\"\n\n location = \"East US\"\n vm_size = \"Standard_B2s\"\n\n azure_tags = {\n Name = \"my-app\"\n BuildDate = local.timestamp\n }\n}\n\nbuild {\n sources = [\"source.azure-arm.ubuntu\"]\n\n provisioner \"shell\" {\n inline = [\n \"sudo apt-get update\",\n \"sudo apt-get upgrade -y\",\n ]\n }\n}\n```\n\n## Azure Compute Gallery\n\n```hcl\nsource \"azure-arm\" \"ubuntu\" {\n client_id = var.client_id\n client_secret = var.client_secret\n subscription_id = var.subscription_id\n tenant_id = var.tenant_id\n\n os_type = \"Linux\"\n image_publisher = \"Canonical\"\n image_offer = \"0001-com-ubuntu-server-jammy\"\n image_sku = \"22_04-lts-gen2\"\n\n location = \"East US\"\n vm_size = \"Standard_B2s\"\n\n shared_image_gallery_destination {\n resource_group = \"gallery-rg\"\n gallery_name = \"myImageGallery\"\n image_name = \"ubuntu-webapp\"\n image_version = \"1.0.${formatdate(\"YYYYMMDD\", timestamp())}\"\n replication_regions = [\"East US\", \"West US 2\"]\n storage_account_type = \"Standard_LRS\"\n }\n}\n```\n\n## Authentication\n\n### Service Principal\n```bash\n# Create service principal\naz ad sp create-for-rbac \\\n --name \"packer-sp\" \\\n --role Contributor \\\n --scopes /subscriptions/\n\n# Set environment variables\nexport ARM_CLIENT_ID=\"\"\nexport ARM_CLIENT_SECRET=\"\"\nexport ARM_SUBSCRIPTION_ID=\"\"\nexport ARM_TENANT_ID=\"\"\n```\n\n### Managed Identity\n```hcl\nsource \"azure-arm\" \"ubuntu\" {\n use_azure_cli_auth = true\n subscription_id = var.subscription_id\n # ... rest of configuration\n}\n```\n\n## Build Commands\n\n```bash\n# Set authentication\nexport ARM_CLIENT_ID=\"your-client-id\"\nexport ARM_CLIENT_SECRET=\"your-client-secret\"\nexport ARM_SUBSCRIPTION_ID=\"your-subscription-id\"\nexport ARM_TENANT_ID=\"your-tenant-id\"\n\n# Initialize plugins\npacker init .\n\n# Validate template\npacker validate .\n\n# Build image\npacker build .\n```\n\n## Common Issues\n\n**Authentication Failed**\n- Verify service principal credentials\n- Ensure Contributor role on resource group\n- Check subscription and tenant IDs\n\n**Compute Gallery Version Exists**\n- Image versions are immutable\n- Use unique version numbers with date/build number\n- Cannot overwrite existing versions\n\n**Timeout During Provisioning**\n- Check network connectivity from build VM\n- Verify NSG rules allow required traffic\n- Increase timeout if needed\n\n## References\n\n- [Azure ARM Builder](https://developer.hashicorp.com/packer/integrations/hashicorp/azure/latest/components/builder/arm)\n- [Azure Compute Gallery](https://learn.microsoft.com/en-us/azure/virtual-machines/azure-compute-gallery)\n"
},
{
"path": "packer/builders/skills/windows-builder/SKILL.md",
"content": "---\nname: windows-builder\ndescription: Build Windows images with Packer using WinRM communicator and PowerShell provisioners. Use when creating Windows AMIs, Azure images, or VMware templates.\n---\n\n# Windows Builder\n\nPlatform-agnostic patterns for building Windows images with Packer.\n\n**Reference:** [Windows Builders](https://developer.hashicorp.com/packer/guides/windows)\n\n> **Note:** Windows builds incur significant costs and time. Expect 45-120 minutes per build due to Windows Updates. Failed builds may leave resources running - always verify cleanup.\n\n## WinRM Communicator Setup\n\nWindows requires WinRM for Packer communication.\n\n### AWS Example\n\n```hcl\nsource \"amazon-ebs\" \"windows\" {\n region = \"us-west-2\"\n instance_type = \"t3.medium\"\n\n source_ami_filter {\n filters = {\n name = \"Windows_Server-2022-English-Full-Base-*\"\n }\n most_recent = true\n owners = [\"amazon\"]\n }\n\n ami_name = \"windows-server-2022-${local.timestamp}\"\n\n communicator = \"winrm\"\n winrm_username = \"Administrator\"\n winrm_use_ssl = true\n winrm_insecure = true\n winrm_timeout = \"15m\"\n\n user_data_file = \"scripts/setup-winrm.ps1\"\n}\n```\n\n### WinRM Setup Script (scripts/setup-winrm.ps1)\n\n```powershell\n\n# Configure WinRM\nwinrm quickconfig -q\nwinrm set winrm/config '@{MaxTimeoutms=\"1800000\"}'\nwinrm set winrm/config/service '@{AllowUnencrypted=\"true\"}'\nwinrm set winrm/config/service/auth '@{Basic=\"true\"}'\n\n# Configure firewall\nnetsh advfirewall firewall add rule name=\"WinRM 5985\" protocol=TCP dir=in localport=5985 action=allow\nnetsh advfirewall firewall add rule name=\"WinRM 5986\" protocol=TCP dir=in localport=5986 action=allow\n\n# Restart WinRM\nnet stop winrm\nnet start winrm\n\n```\n\n### Azure Example\n\n```hcl\nsource \"azure-arm\" \"windows\" {\n client_id = var.client_id\n client_secret = var.client_secret\n subscription_id = var.subscription_id\n tenant_id = var.tenant_id\n\n managed_image_resource_group_name = \"images-rg\"\n managed_image_name = \"windows-${local.timestamp}\"\n\n os_type = \"Windows\"\n image_publisher = \"MicrosoftWindowsServer\"\n image_offer = \"WindowsServer\"\n image_sku = \"2022-datacenter-g2\"\n\n location = \"East US\"\n vm_size = \"Standard_D2s_v3\"\n\n # Azure auto-configures WinRM\n communicator = \"winrm\"\n winrm_use_ssl = true\n winrm_insecure = true\n winrm_timeout = \"15m\"\n winrm_username = \"packer\"\n}\n```\n\n## PowerShell Provisioners\n\n### Install Software\n\n```hcl\nbuild {\n sources = [\"source.amazon-ebs.windows\"]\n\n # Install Chocolatey\n provisioner \"powershell\" {\n inline = [\n \"Set-ExecutionPolicy Bypass -Scope Process -Force\",\n \"iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))\"\n ]\n }\n\n # Install applications\n provisioner \"powershell\" {\n inline = [\n \"choco install -y googlechrome\",\n \"choco install -y 7zip\",\n ]\n }\n\n # Install IIS\n provisioner \"powershell\" {\n inline = [\n \"Install-WindowsFeature -Name Web-Server -IncludeManagementTools\"\n ]\n }\n}\n```\n\n### Windows Updates\n\n```hcl\nprovisioner \"powershell\" {\n inline = [\n \"Install-PackageProvider -Name NuGet -Force\",\n \"Install-Module -Name PSWindowsUpdate -Force\",\n \"Import-Module PSWindowsUpdate\",\n \"Get-WindowsUpdate -Install -AcceptAll -AutoReboot\",\n ]\n timeout = \"2h\"\n}\n\n# Wait for reboots\nprovisioner \"windows-restart\" {\n restart_timeout = \"30m\"\n}\n```\n\n## Cleanup\n\n```hcl\nprovisioner \"powershell\" {\n inline = [\n \"# Clear temp files\",\n \"Remove-Item -Path 'C:\\\\Windows\\\\Temp\\\\*' -Recurse -Force -ErrorAction SilentlyContinue\",\n \"# Clear Windows Update cache\",\n \"Stop-Service -Name wuauserv -Force\",\n \"Remove-Item -Path 'C:\\\\Windows\\\\SoftwareDistribution\\\\*' -Recurse -Force -ErrorAction SilentlyContinue\",\n \"Start-Service -Name wuauserv\",\n ]\n}\n```\n\n## Common Issues\n\n**WinRM Timeout**\n- Increase `winrm_timeout` to 15m or more\n- Verify security group allows ports 5985/5986\n- Check user data script completed successfully\n\n**PowerShell Execution Policy**\n```hcl\nprovisioner \"powershell\" {\n inline = [\n \"Set-ExecutionPolicy Bypass -Scope Process -Force\",\n \"# Your commands here\",\n ]\n}\n```\n\n**Long Build Times**\n- Windows Updates can take 1-2 hours\n- Use pre-patched base images when available\n- Set provisioner `timeout = \"2h\"`\n\n## References\n\n- [Packer Windows Builders](https://developer.hashicorp.com/packer/guides/windows)\n- [WinRM Communicator](https://developer.hashicorp.com/packer/docs/communicators/winrm)\n- [PowerShell Provisioner](https://developer.hashicorp.com/packer/docs/provisioners/powershell)\n"
},
{
"path": "packer/hcp/.claude-plugin/plugin.json",
"content": "{\n \"name\": \"packer-hcp\",\n \"version\": \"1.0.0\",\n \"description\": \"HCP Packer registry integration for tracking and managing image metadata.\",\n \"author\": {\n \"name\": \"HashiCorp\",\n \"url\": \"https://github.com/hashicorp\"\n },\n \"homepage\": \"https://developer.hashicorp.com/hcp/docs/packer\",\n \"repository\": \"https://github.com/hashicorp/agent-skills\",\n \"license\": \"MPL-2.0\",\n \"keywords\": [\"packer\", \"hcp-packer\", \"registry\", \"metadata\", \"image-tracking\"]\n}\n"
},
{
"path": "packer/hcp/skills/push-to-registry/SKILL.md",
"content": "---\nname: push-to-registry\ndescription: Push Packer build metadata to HCP Packer registry for tracking and managing image lifecycle. Use when integrating Packer builds with HCP Packer for version control and governance.\n---\n\n# Push to HCP Packer Registry\n\nConfigure Packer templates to push build metadata to HCP Packer registry.\n\n**Reference:** [HCP Packer Registry](https://developer.hashicorp.com/hcp/docs/packer)\n\n> **Note:** HCP Packer is free for basic use. Builds push metadata only (not actual images), adding minimal overhead (<1 minute).\n\n## Basic Registry Configuration\n\n```hcl\npacker {\n required_version = \">= 1.7.7\"\n}\n\nvariable \"image_name\" {\n type = string\n default = \"web-server\"\n}\n\nlocals {\n timestamp = regex_replace(timestamp(), \"[- TZ:]\", \"\")\n}\n\nsource \"amazon-ebs\" \"ubuntu\" {\n region = \"us-west-2\"\n instance_type = \"t3.micro\"\n\n source_ami_filter {\n filters = {\n name = \"ubuntu/images/*ubuntu-jammy-22.04-amd64-server-*\"\n }\n most_recent = true\n owners = [\"099720109477\"]\n }\n\n ssh_username = \"ubuntu\"\n ami_name = \"${var.image_name}-${local.timestamp}\"\n}\n\nbuild {\n sources = [\"source.amazon-ebs.ubuntu\"]\n\n hcp_packer_registry {\n bucket_name = var.image_name\n description = \"Ubuntu 22.04 base image for web servers\"\n\n bucket_labels = {\n \"os\" = \"ubuntu\"\n \"team\" = \"platform\"\n }\n\n build_labels = {\n \"build-time\" = local.timestamp\n }\n }\n\n provisioner \"shell\" {\n inline = [\n \"sudo apt-get update\",\n \"sudo apt-get upgrade -y\",\n ]\n }\n}\n```\n\n## Authentication\n\nSet environment variables before building:\n\n```bash\nexport HCP_CLIENT_ID=\"your-service-principal-client-id\"\nexport HCP_CLIENT_SECRET=\"your-service-principal-secret\"\nexport HCP_ORGANIZATION_ID=\"your-org-id\"\nexport HCP_PROJECT_ID=\"your-project-id\"\n\npacker build .\n```\n\n### Create HCP Service Principal\n\n1. Navigate to HCP ā Access Control (IAM)\n2. Create Service Principal\n3. Grant \"Contributor\" role on project\n4. Generate client secret\n5. Save client ID and secret\n\n## Registry Configuration Options\n\n### bucket_name (required)\nThe image identifier. Must stay consistent across builds!\n\n```hcl\nbucket_name = \"web-server\" # Keep this constant\n```\n\n### bucket_labels (optional)\nMetadata at bucket level. Updates with each build.\n\n```hcl\nbucket_labels = {\n \"os\" = \"ubuntu\"\n \"team\" = \"platform\"\n \"component\" = \"web\"\n}\n```\n\n### build_labels (optional)\nMetadata for each iteration. Immutable after build completes.\n\n```hcl\nbuild_labels = {\n \"build-time\" = local.timestamp\n \"git-commit\" = var.git_commit\n}\n```\n\n## CI/CD Integration\n\n### GitHub Actions\n\n```yaml\nname: Build and Push to HCP Packer\n\non:\n push:\n branches: [main]\n\nenv:\n HCP_CLIENT_ID: ${{ secrets.HCP_CLIENT_ID }}\n HCP_CLIENT_SECRET: ${{ secrets.HCP_CLIENT_SECRET }}\n HCP_ORGANIZATION_ID: ${{ secrets.HCP_ORGANIZATION_ID }}\n HCP_PROJECT_ID: ${{ secrets.HCP_PROJECT_ID }}\n\njobs:\n build:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: hashicorp/setup-packer@main\n\n - name: Build and push\n run: |\n packer init .\n packer build \\\n -var \"git_commit=${{ github.sha }}\" \\\n .\n```\n\n## Querying in Terraform\n\n```hcl\ndata \"hcp_packer_artifact\" \"ubuntu\" {\n bucket_name = \"web-server\"\n channel_name = \"production\"\n platform = \"aws\"\n region = \"us-west-2\"\n}\n\nresource \"aws_instance\" \"web\" {\n ami = data.hcp_packer_artifact.ubuntu.external_identifier\n instance_type = \"t3.micro\"\n\n tags = {\n PackerBucket = data.hcp_packer_artifact.ubuntu.bucket_name\n }\n}\n```\n\n## Common Issues\n\n**Authentication Failed**\n- Verify HCP_CLIENT_ID and HCP_CLIENT_SECRET\n- Ensure service principal has Contributor role\n- Check organization and project IDs\n\n**Bucket Name Mismatch**\n- Keep `bucket_name` consistent across builds\n- Don't include timestamps in bucket_name\n- Creates new bucket if name changes\n\n**Build Fails**\n- Packer fails immediately if can't push metadata\n- Prevents drift between artifacts and registry\n- Check network connectivity to HCP API\n\n## Best Practices\n\n- **Consistent bucket names** - Never change for same image type\n- **Meaningful labels** - Use for versions, teams, compliance\n- **CI/CD automation** - Automate builds and registry pushes\n- **Immutable build labels** - Put changing data (git SHA, date) in build_labels\n\n## References\n\n- [HCP Packer Documentation](https://developer.hashicorp.com/hcp/docs/packer)\n- [hcp_packer_registry Block](https://developer.hashicorp.com/packer/docs/templates/hcl_templates/blocks/build/hcp_packer_registry)\n- [HCP Terraform Provider](https://registry.terraform.io/providers/hashicorp/hcp/latest/docs/data-sources/packer_artifact)\n"
},
{
"path": "scripts/validate-structure.sh",
"content": "#!/bin/bash\n# Copyright IBM Corp. 2025, 2026\n# SPDX-License-Identifier: MPL-2.0\n\n#\n# Validates the agent-skills repository structure\n# Ensures all plugins and skills follow the expected format\n#\n\nset -e\n\nREPO_ROOT=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")/..\" && pwd)\"\nERRORS=0\n\n# Colors for output\nRED='\\033[0;31m'\nGREEN='\\033[0;32m'\nYELLOW='\\033[1;33m'\nNC='\\033[0m' # No Color\n\nlog_error() {\n echo -e \"${RED}ERROR:${NC} $1\"\n ERRORS=$((ERRORS + 1))\n}\n\nlog_success() {\n echo -e \"${GREEN}OK:${NC} $1\"\n}\n\nlog_info() {\n echo -e \"${YELLOW}INFO:${NC} $1\"\n}\n\n# Check if jq is available\nif ! command -v jq &> /dev/null; then\n echo \"jq is required but not installed. Please install jq.\"\n exit 1\nfi\n\necho \"==========================================\"\necho \"Validating agent-skills repository structure\"\necho \"==========================================\"\necho \"\"\n\n# ---------------------------------------------\n# 1. Validate marketplace.json\n# ---------------------------------------------\necho \"1. Checking marketplace.json...\"\n\nMARKETPLACE_FILE=\"$REPO_ROOT/.claude-plugin/marketplace.json\"\n\nif [[ ! -f \"$MARKETPLACE_FILE\" ]]; then\n log_error \"marketplace.json not found at $MARKETPLACE_FILE\"\nelse\n # Check if valid JSON\n if ! jq empty \"$MARKETPLACE_FILE\" 2>/dev/null; then\n log_error \"marketplace.json is not valid JSON\"\n else\n log_success \"marketplace.json is valid JSON\"\n\n # Check required fields\n NAME=$(jq -r '.name // empty' \"$MARKETPLACE_FILE\")\n if [[ -z \"$NAME\" ]]; then\n log_error \"marketplace.json missing 'name' field\"\n else\n log_success \"marketplace.json has name: $NAME\"\n fi\n\n OWNER=$(jq -r '.owner.name // empty' \"$MARKETPLACE_FILE\")\n if [[ -z \"$OWNER\" ]]; then\n log_error \"marketplace.json missing 'owner.name' field\"\n else\n log_success \"marketplace.json has owner: $OWNER\"\n fi\n\n # Check plugins array exists\n PLUGINS_COUNT=$(jq '.plugins | length' \"$MARKETPLACE_FILE\")\n if [[ \"$PLUGINS_COUNT\" -eq 0 ]]; then\n log_error \"marketplace.json has no plugins defined\"\n else\n log_success \"marketplace.json has $PLUGINS_COUNT plugin(s) defined\"\n fi\n fi\nfi\n\necho \"\"\n\n# ---------------------------------------------\n# 2. Validate each plugin referenced in marketplace\n# ---------------------------------------------\necho \"2. Checking plugins referenced in marketplace.json...\"\n\nif [[ -f \"$MARKETPLACE_FILE\" ]]; then\n PLUGIN_SOURCES=$(jq -r '.plugins[].source' \"$MARKETPLACE_FILE\" 2>/dev/null)\n\n for SOURCE in $PLUGIN_SOURCES; do\n # Remove leading ./ if present\n SOURCE_PATH=\"${SOURCE#./}\"\n PLUGIN_DIR=\"$REPO_ROOT/$SOURCE_PATH\"\n PLUGIN_JSON=\"$PLUGIN_DIR/.claude-plugin/plugin.json\"\n\n echo \"\"\n log_info \"Checking plugin: $SOURCE_PATH\"\n\n # Check plugin directory exists\n if [[ ! -d \"$PLUGIN_DIR\" ]]; then\n log_error \"Plugin directory not found: $PLUGIN_DIR\"\n continue\n else\n log_success \"Plugin directory exists\"\n fi\n\n # Check plugin.json exists\n if [[ ! -f \"$PLUGIN_JSON\" ]]; then\n log_error \"plugin.json not found: $PLUGIN_JSON\"\n continue\n else\n log_success \"plugin.json exists\"\n fi\n\n # Validate plugin.json\n if ! jq empty \"$PLUGIN_JSON\" 2>/dev/null; then\n log_error \"plugin.json is not valid JSON: $PLUGIN_JSON\"\n continue\n else\n log_success \"plugin.json is valid JSON\"\n fi\n\n # Check required fields in plugin.json\n PLUGIN_NAME=$(jq -r '.name // empty' \"$PLUGIN_JSON\")\n if [[ -z \"$PLUGIN_NAME\" ]]; then\n log_error \"plugin.json missing 'name' field\"\n else\n log_success \"plugin.json has name: $PLUGIN_NAME\"\n fi\n\n PLUGIN_VERSION=$(jq -r '.version // empty' \"$PLUGIN_JSON\")\n if [[ -z \"$PLUGIN_VERSION\" ]]; then\n log_error \"plugin.json missing 'version' field\"\n else\n log_success \"plugin.json has version: $PLUGIN_VERSION\"\n fi\n\n PLUGIN_DESC=$(jq -r '.description // empty' \"$PLUGIN_JSON\")\n if [[ -z \"$PLUGIN_DESC\" ]]; then\n log_error \"plugin.json missing 'description' field\"\n else\n log_success \"plugin.json has description\"\n fi\n\n # Check skills directory exists\n SKILLS_DIR=\"$PLUGIN_DIR/skills\"\n if [[ ! -d \"$SKILLS_DIR\" ]]; then\n log_error \"skills/ directory not found in plugin: $PLUGIN_DIR\"\n continue\n else\n log_success \"skills/ directory exists\"\n fi\n\n # Validate each skill\n SKILL_COUNT=0\n for SKILL_DIR in \"$SKILLS_DIR\"/*/; do\n if [[ -d \"$SKILL_DIR\" ]]; then\n SKILL_NAME=$(basename \"$SKILL_DIR\")\n SKILL_MD=\"$SKILL_DIR/SKILL.md\"\n\n if [[ ! -f \"$SKILL_MD\" ]]; then\n log_error \"SKILL.md not found for skill: $SKILL_NAME\"\n else\n # Check SKILL.md has frontmatter\n if ! head -1 \"$SKILL_MD\" | grep -q \"^---\"; then\n log_error \"SKILL.md missing frontmatter (---) for skill: $SKILL_NAME\"\n else\n # Extract and validate frontmatter\n FRONTMATTER=$(sed -n '/^---$/,/^---$/p' \"$SKILL_MD\" | sed '1d;$d')\n\n # Check for name field\n if ! echo \"$FRONTMATTER\" | grep -q \"^name:\"; then\n log_error \"SKILL.md missing 'name' in frontmatter for skill: $SKILL_NAME\"\n fi\n\n # Check for description field\n if ! echo \"$FRONTMATTER\" | grep -q \"^description:\"; then\n log_error \"SKILL.md missing 'description' in frontmatter for skill: $SKILL_NAME\"\n fi\n\n if echo \"$FRONTMATTER\" | grep -q \"^name:\" && echo \"$FRONTMATTER\" | grep -q \"^description:\"; then\n log_success \"SKILL.md valid for skill: $SKILL_NAME\"\n fi\n fi\n fi\n SKILL_COUNT=$((SKILL_COUNT + 1))\n fi\n done\n\n if [[ \"$SKILL_COUNT\" -eq 0 ]]; then\n log_error \"No skills found in $SKILLS_DIR\"\n else\n log_success \"Found $SKILL_COUNT skill(s) in plugin\"\n fi\n done\nfi\n\necho \"\"\n\n# ---------------------------------------------\n# 3. Check for orphaned plugins (not in marketplace)\n# ---------------------------------------------\necho \"3. Checking for orphaned plugins...\"\n\n# Find all plugin.json files\nFOUND_PLUGINS=$(find \"$REPO_ROOT\" -path \"*/.claude-plugin/plugin.json\" -not -path \"$REPO_ROOT/.claude-plugin/*\" 2>/dev/null)\n\nfor PLUGIN_JSON in $FOUND_PLUGINS; do\n PLUGIN_DIR=$(dirname \"$(dirname \"$PLUGIN_JSON\")\")\n RELATIVE_PATH=\"${PLUGIN_DIR#$REPO_ROOT/}\"\n\n # Check if this plugin is referenced in marketplace.json\n if [[ -f \"$MARKETPLACE_FILE\" ]]; then\n if ! jq -r '.plugins[].source' \"$MARKETPLACE_FILE\" | grep -q \"$RELATIVE_PATH\"; then\n log_error \"Orphaned plugin not in marketplace.json: $RELATIVE_PATH\"\n fi\n fi\ndone\n\nlog_success \"Orphan check complete\"\n\necho \"\"\n\n# ---------------------------------------------\n# 4. Validate product folder structure\n# ---------------------------------------------\necho \"4. Checking product folder structure...\"\n\n# Get all top-level directories that could be products (excluding hidden and special)\nfor DIR in \"$REPO_ROOT\"/*/; do\n DIR_NAME=$(basename \"$DIR\")\n\n # Skip special directories\n if [[ \"$DIR_NAME\" == \"scripts\" ]] || [[ \"$DIR_NAME\" == \"node_modules\" ]] || [[ \"$DIR_NAME\" =~ ^\\. ]]; then\n continue\n fi\n\n # Check if this is a product folder (contains plugin subdirectories)\n HAS_PLUGINS=false\n for SUBDIR in \"$DIR\"/*/; do\n if [[ -d \"$SUBDIR/.claude-plugin\" ]]; then\n HAS_PLUGINS=true\n break\n fi\n done\n\n if [[ \"$HAS_PLUGINS\" == true ]]; then\n log_success \"Valid product folder: $DIR_NAME\"\n fi\ndone\n\necho \"\"\necho \"==========================================\"\necho \"Validation complete\"\necho \"==========================================\"\n\nif [[ \"$ERRORS\" -gt 0 ]]; then\n echo -e \"${RED}Found $ERRORS error(s)${NC}\"\n exit 1\nelse\n echo -e \"${GREEN}All checks passed!${NC}\"\n exit 0\nfi\n"
},
{
"path": "terraform/README.md",
"content": "# Terraform Skills\n\nAgent skills for Terraform infrastructure-as-code development.\n\n## Plugins\n\n### terraform-code-generation\n\nSkills for generating and validating Terraform HCL code.\n\n| Skill | Description |\n|-------|-------------|\n| terraform-style-guide | Generate Terraform HCL code following HashiCorp style conventions |\n| terraform-test | Writing and running `.tftest.hcl` test files |\n| azure-verified-modules | Azure Verified Modules (AVM) requirements and certification |\n| terraform-search-import | Discover existing resources with Terraform Search and bulk import |\n\n### terraform-module-generation\n\nSkills for creating and refactoring Terraform modules.\n\n| Skill | Description |\n|-------|-------------|\n| refactor-module | Transform monolithic configs into reusable modules |\n| terraform-stacks | Multi-region/environment orchestration with Terraform Stacks |\n\n### terraform-provider-development\n\nSkills for developing Terraform providers.\n\n| Skill | Description |\n|-------|-------------|\n| new-terraform-provider | Scaffold a new Terraform provider |\n| run-acceptance-tests | Run and debug provider acceptance tests |\n| provider-actions | Implement provider actions (lifecycle operations) |\n| provider-resources | Implement resources and data sources |\n| provider-test-patterns | Acceptance test patterns for terraform-plugin-testing |\n\n## Installation\n\n### Claude Code Plugin\n\n```bash\nclaude plugin marketplace add hashicorp/agent-skills\n\nclaude plugin install terraform-code-generation@hashicorp\nclaude plugin install terraform-module-generation@hashicorp\nclaude plugin install terraform-provider-development@hashicorp\n```\n\n### Individual Skills\n\n```bash\n# Code generation\nnpx skills add hashicorp/agent-skills/terraform/code-generation/skills/terraform-style-guide\nnpx skills add hashicorp/agent-skills/terraform/code-generation/skills/terraform-test\nnpx skills add hashicorp/agent-skills/terraform/code-generation/skills/azure-verified-modules\nnpx skills add hashicorp/agent-skills/terraform/code-generation/skills/terraform-search-import\n\n# Module generation\nnpx skills add hashicorp/agent-skills/terraform/module-generation/skills/refactor-module\nnpx skills add hashicorp/agent-skills/terraform/module-generation/skills/terraform-stacks\n\n# Provider development\nnpx skills add hashicorp/agent-skills/terraform/provider-development/skills/new-terraform-provider\nnpx skills add hashicorp/agent-skills/terraform/provider-development/skills/run-acceptance-tests\nnpx skills add hashicorp/agent-skills/terraform/provider-development/skills/provider-actions\nnpx skills add hashicorp/agent-skills/terraform/provider-development/skills/provider-resources\nnpx skills add hashicorp/agent-skills/terraform/provider-development/skills/provider-test-patterns\n```\n\n## MCP Server\n\nRelevant Terraform plugins include the `terraform-mcp-server` which provides access to Terraform Cloud/Enterprise APIs. Set the following environment variables:\n\n```bash\nexport TFE_TOKEN=\"your-terraform-cloud-token\"\nexport TFE_ADDRESS=\"https://app.terraform.io\" # or your TFE instance\n```\n\n## Structure\n\n```\nterraform/\nāāā code-generation/\nā āāā .claude-plugin/plugin.json\nā āāā skills/\nā āāā terraform-style-guide/\nā āāā terraform-test/\nā āāā azure-verified-modules/\nā āāā terraform-search-import/\nāāā module-generation/\nā āāā .claude-plugin/plugin.json\nā āāā skills/\nā āāā terraform-stacks/\nā āāā refactor-module/\nāāā provider-development/\n āāā .claude-plugin/plugin.json\n āāā skills/\n āāā new-terraform-provider/\n āāā provider-actions/\n āāā provider-resources/\n āāā run-acceptance-tests/\n āāā provider-test-patterns/\n```\n\n## References\n\n- [Terraform Documentation](https://developer.hashicorp.com/terraform)\n- [Terraform Plugin Framework](https://developer.hashicorp.com/terraform/plugin/framework)\n- [Terraform MCP Server](https://github.com/hashicorp/terraform-mcp-server)\n"
},
{
"path": "terraform/code-generation/.claude-plugin/plugin.json",
"content": "{\n \"name\": \"terraform-code-generation\",\n \"version\": \"1.0.0\",\n \"description\": \"Terraform code generation skills for Claude Code, including HCL generation, style guides, and testing.\",\n \"author\": {\n \"name\": \"HashiCorp\",\n \"url\": \"https://github.com/hashicorp\"\n },\n \"homepage\": \"https://developer.hashicorp.com/terraform/language\",\n \"repository\": \"https://github.com/hashicorp/agent-skills\",\n \"license\": \"MPL-2.0\",\n \"keywords\": [\"terraform\", \"hcl\", \"infrastructure\", \"iac\", \"testing\", \"style-guide\", \"search\", \"import\", \"discovery\"],\n \"mcpServers\": {\n \"terraform\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"-i\",\n \"--rm\",\n \"-e\", \"TFE_TOKEN\",\n \"-e\", \"TFE_ADDRESS\",\n \"hashicorp/terraform-mcp-server\"\n ],\n \"env\": {\n \"TFE_TOKEN\": \"${TFE_TOKEN}\",\n \"TFE_ADDRESS\": \"${TFE_ADDRESS}\"\n }\n }\n }\n}\n"
},
{
"path": "terraform/code-generation/skills/azure-verified-modules/SKILL.md",
"content": "---\nname: azure-verified-modules\ndescription: Azure Verified Modules (AVM) requirements and best practices for developing certified Azure Terraform modules. Use when creating or reviewing Azure modules that need AVM certification.\n---\n\n# Azure Verified Modules (AVM) Requirements\n\nThis guide covers the mandatory requirements for Azure Verified Modules certification. These requirements ensure consistency, quality, and maintainability across Azure Terraform modules.\n\n**References:**\n- [Azure Verified Modules](https://azure.github.io/Azure-Verified-Modules/)\n- [AVM Terraform Requirements](https://azure.github.io/Azure-Verified-Modules/specs/terraform/)\n\n## Table of Contents\n\n- [Module Cross-Referencing](#module-cross-referencing)\n- [Azure Provider Requirements](#azure-provider-requirements)\n- [Code Style Standards](#code-style-standards)\n- [Variable Requirements](#variable-requirements)\n- [Output Requirements](#output-requirements)\n- [Local Values Standards](#local-values-standards)\n- [Terraform Configuration Requirements](#terraform-configuration-requirements)\n- [Testing Requirements](#testing-requirements)\n- [Documentation Requirements](#documentation-requirements)\n- [Breaking Changes & Feature Management](#breaking-changes--feature-management)\n- [Contribution Standards](#contribution-standards)\n- [Compliance Checklist](#compliance-checklist)\n\n---\n\n## Module Cross-Referencing\n\n**Severity:** MUST | **Requirement:** TFFR1\n\nWhen building Resource or Pattern modules, module owners **MAY** cross-reference other modules. However:\n\n- Modules **MUST** be referenced using HashiCorp Terraform registry reference to a pinned version\n - Example: `source = \"Azure/xxx/azurerm\"` with `version = \"1.2.3\"`\n- Modules **MUST NOT** use git references (e.g., `git::https://xxx.yyy/xxx.git` or `github.com/xxx/yyy`)\n- Modules **MUST NOT** contain references to non-AVM modules\n\n---\n\n## Azure Provider Requirements\n\n**Severity:** MUST | **Requirement:** TFFR3\n\nAuthors **MUST** only use the following Azure providers:\n\n| Provider | Min Version | Max Version |\n|----------|-------------|-------------|\n| azapi | >= 2.0 | < 3.0 |\n| azurerm | >= 4.0 | < 5.0 |\n\n**Requirements:**\n\n- Authors **MAY** select either Azurerm, Azapi, or both providers\n- **MUST** use `required_providers` block to enforce provider versions\n- **SHOULD** use pessimistic version constraint operator (`~>`)\n\n**Example:**\n\n```hcl\nterraform {\n required_providers {\n azurerm = {\n source = \"hashicorp/azurerm\"\n version = \"~> 4.0\"\n }\n azapi = {\n source = \"Azure/azapi\"\n version = \"~> 2.0\"\n }\n }\n}\n```\n\n---\n\n## Code Style Standards\n\n### Lower snake_casing\n\n**Severity:** MUST | **Requirement:** TFNFR4\n\n**MUST** use lower snake_casing for:\n\n- Locals\n- Variables\n- Outputs\n- Resources (symbolic names)\n- Modules (symbolic names)\n\nExample: `snake_casing_example`\n\n### Resource & Data Source Ordering\n\n**Severity:** SHOULD | **Requirement:** TFNFR6\n\n- Resources that are depended on **SHOULD** come first\n- Resources with dependencies **SHOULD** be defined close to each other\n\n### Count & for_each Usage\n\n**Severity:** MUST | **Requirement:** TFNFR7\n\n- Use `count` for conditional resource creation\n- **MUST** use `map(xxx)` or `set(xxx)` as resource's `for_each` collection\n- The map's key or set's element **MUST** be static literals\n\n**Example:**\n\n```hcl\nresource \"azurerm_subnet\" \"pair\" {\n for_each = var.subnet_map # map(string)\n name = \"${each.value}-pair\"\n resource_group_name = azurerm_resource_group.example.name\n virtual_network_name = azurerm_virtual_network.example.name\n address_prefixes = [\"10.0.1.0/24\"]\n}\n```\n\n### Resource & Data Block Internal Ordering\n\n**Severity:** SHOULD | **Requirement:** TFNFR8\n\n**Order within resource/data blocks:**\n\n1. **Meta-arguments (top)**:\n - `provider`\n - `count`\n - `for_each`\n\n2. **Arguments/blocks (middle, alphabetical)**:\n - Required arguments\n - Optional arguments\n - Required nested blocks\n - Optional nested blocks\n\n3. **Meta-arguments (bottom)**:\n - `depends_on`\n - `lifecycle` (with sub-order: `create_before_destroy`, `ignore_changes`, `prevent_destroy`)\n\nSeparate sections with blank lines.\n\n### Module Block Ordering\n\n**Severity:** SHOULD | **Requirement:** TFNFR9\n\n**Order within module blocks:**\n\n1. **Top meta-arguments**:\n - `source`\n - `version`\n - `count`\n - `for_each`\n\n2. **Arguments (alphabetical)**:\n - Required arguments\n - Optional arguments\n\n3. **Bottom meta-arguments**:\n - `depends_on`\n - `providers`\n\n### Lifecycle ignore_changes Syntax\n\n**Severity:** MUST | **Requirement:** TFNFR10\n\nThe `ignore_changes` attribute **MUST NOT** be enclosed in double quotes.\n\n**Good:**\n\n```hcl\nlifecycle {\n ignore_changes = [tags]\n}\n```\n\n**Bad:**\n\n```hcl\nlifecycle {\n ignore_changes = [\"tags\"]\n}\n```\n\n### Null Comparison for Conditional Creation\n\n**Severity:** SHOULD | **Requirement:** TFNFR11\n\nFor parameters requiring conditional resource creation, wrap with `object` type to avoid \"known after apply\" issues during plan stage.\n\n**Recommended:**\n\n```hcl\nvariable \"security_group\" {\n type = object({\n id = string\n })\n default = null\n}\n```\n\n### Dynamic Blocks for Optional Nested Objects\n\n**Severity:** MUST | **Requirement:** TFNFR12\n\nNested blocks under conditions **MUST** use this pattern:\n\n```hcl\ndynamic \"identity\" {\n for_each = ? [] : []\n\n content {\n # block content\n }\n}\n```\n\n### Default Values with coalesce/try\n\n**Severity:** SHOULD | **Requirement:** TFNFR13\n\n**Good:**\n\n```hcl\ncoalesce(var.new_network_security_group_name, \"${var.subnet_name}-nsg\")\n```\n\n**Bad:**\n\n```hcl\nvar.new_network_security_group_name == null ? \"${var.subnet_name}-nsg\" : var.new_network_security_group_name\n```\n\n### Provider Declarations in Modules\n\n**Severity:** MUST | **Requirement:** TFNFR27\n\n- `provider` **MUST NOT** be declared in modules (except for `configuration_aliases`)\n- `provider` blocks in modules **MUST** only use `alias`\n- Provider configurations **SHOULD** be passed in by module users\n\n---\n\n## Variable Requirements\n\n### Not Allowed Variables\n\n**Severity:** MUST | **Requirement:** TFNFR14\n\nModule owners **MUST NOT** add variables like `enabled` or `module_depends_on` to control entire module operation. Boolean feature toggles for specific resources are acceptable.\n\n### Variable Definition Order\n\n**Severity:** SHOULD | **Requirement:** TFNFR15\n\nVariables **SHOULD** follow this order:\n\n1. All required fields (alphabetical)\n2. All optional fields (alphabetical)\n\n### Variable Naming Rules\n\n**Severity:** SHOULD | **Requirement:** TFNFR16\n\n- Follow [HashiCorp's naming rules](https://www.terraform.io/docs/extend/best-practices/naming.html)\n- Feature switches **SHOULD** use positive statements: `xxx_enabled` instead of `xxx_disabled`\n\n### Variables with Descriptions\n\n**Severity:** SHOULD | **Requirement:** TFNFR17\n\n- `description` **SHOULD** precisely describe the parameter's purpose and expected data type\n- Target audience is module users, not developers\n- For `object` types, use HEREDOC format\n\n### Variables with Types\n\n**Severity:** MUST | **Requirement:** TFNFR18\n\n- `type` **MUST** be defined for every variable\n- `type` **SHOULD** be as precise as possible\n- `any` **MAY** only be used with adequate reasons\n- Use `bool` instead of `string`/`number` for true/false values\n- Use concrete `object` instead of `map(any)`\n\n### Sensitive Data Variables\n\n**Severity:** SHOULD | **Requirement:** TFNFR19\n\nIf a variable's type is `object` and contains sensitive fields, the entire variable **SHOULD** be `sensitive = true`, or extract sensitive fields into separate variables.\n\n### Non-Nullable Defaults for Collections\n\n**Severity:** SHOULD | **Requirement:** TFNFR20\n\nNullable **SHOULD** be set to `false` for collection values (sets, maps, lists) when using them in loops. For scalar values, null may have semantic meaning.\n\n### Discourage Nullability by Default\n\n**Severity:** MUST | **Requirement:** TFNFR21\n\n`nullable = true` **MUST** be avoided unless there's a specific semantic need for null values.\n\n### Avoid sensitive = false\n\n**Severity:** MUST | **Requirement:** TFNFR22\n\n`sensitive = false` **MUST** be avoided (this is the default).\n\n### Sensitive Default Value Conditions\n\n**Severity:** MUST | **Requirement:** TFNFR23\n\nA default value **MUST NOT** be set for sensitive inputs (e.g., default passwords).\n\n### Handling Deprecated Variables\n\n**Severity:** MUST | **Requirement:** TFNFR24\n\n- Move deprecated variables to `deprecated_variables.tf`\n- Annotate with `DEPRECATED` at the beginning of description\n- Declare the replacement's name\n- Clean up during major version releases\n\n---\n\n## Output Requirements\n\n### Additional Terraform Outputs\n\n**Severity:** SHOULD | **Requirement:** TFFR2\n\nAuthors **SHOULD NOT** output entire resource objects as these may contain sensitive data and the schema can change with API or provider versions.\n\n**Best Practices:**\n\n- Output *computed* attributes of resources as discrete outputs (anti-corruption layer pattern)\n- **SHOULD NOT** output values that are already inputs (except `name`)\n- Use `sensitive = true` for sensitive attributes\n- For resources deployed with `for_each`, output computed attributes in a map structure\n\n**Examples:**\n\n```hcl\n# Single resource computed attribute\noutput \"foo\" {\n description = \"MyResource foo attribute\"\n value = azurerm_resource_myresource.foo\n}\n\n# for_each resources\noutput \"childresource_foos\" {\n description = \"MyResource children's foo attributes\"\n value = {\n for key, value in azurerm_resource_mychildresource : key => value.foo\n }\n}\n\n# Sensitive output\noutput \"bar\" {\n description = \"MyResource bar attribute\"\n value = azurerm_resource_myresource.bar\n sensitive = true\n}\n```\n\n### Sensitive Data Outputs\n\n**Severity:** MUST | **Requirement:** TFNFR29\n\nOutputs containing confidential data **MUST** be declared with `sensitive = true`.\n\n### Handling Deprecated Outputs\n\n**Severity:** MUST | **Requirement:** TFNFR30\n\n- Move deprecated outputs to `deprecated_outputs.tf`\n- Define new outputs in `outputs.tf`\n- Clean up during major version releases\n\n---\n\n## Local Values Standards\n\n### locals.tf Organization\n\n**Severity:** MAY | **Requirement:** TFNFR31\n\n- `locals.tf` **SHOULD** only contain `locals` blocks\n- **MAY** declare `locals` blocks next to resources for advanced scenarios\n\n### Alphabetical Local Arrangement\n\n**Severity:** MUST | **Requirement:** TFNFR32\n\nExpressions in `locals` blocks **MUST** be arranged alphabetically.\n\n### Precise Local Types\n\n**Severity:** SHOULD | **Requirement:** TFNFR33\n\nUse precise types (e.g., `number` for age, not `string`).\n\n---\n\n## Terraform Configuration Requirements\n\n### Terraform Version Requirements\n\n**Severity:** MUST | **Requirement:** TFNFR25\n\n**`terraform.tf` requirements:**\n\n- **MUST** contain only one `terraform` block\n- First line **MUST** define `required_version`\n- **MUST** include minimum version constraint\n- **MUST** include maximum major version constraint\n- **SHOULD** use `~> #.#` or `>= #.#.#, < #.#.#` format\n\n**Example:**\n\n```hcl\nterraform {\n required_version = \"~> 1.6\"\n required_providers {\n azurerm = {\n source = \"hashicorp/azurerm\"\n version = \"~> 4.0\"\n }\n }\n}\n```\n\n### Providers in required_providers\n\n**Severity:** MUST | **Requirement:** TFNFR26\n\n- `terraform` block **MUST** contain `required_providers` block\n- Each provider **MUST** specify `source` and `version`\n- Providers **SHOULD** be sorted alphabetically\n- Only include directly required providers\n- `source` **MUST** be in format `namespace/name`\n- `version` **MUST** include minimum and maximum major version constraints\n- **SHOULD** use `~> #.#` or `>= #.#.#, < #.#.#` format\n\n---\n\n## Testing Requirements\n\n### Test Tooling\n\n**Severity:** MUST | **Requirement:** TFNFR5\n\n**Required testing tools for AVM:**\n\n- Terraform (`terraform validate/fmt/test`)\n- terrafmt\n- Checkov\n- tflint (with azurerm ruleset)\n- Go (optional for custom tests)\n\n### Test Provider Configuration\n\n**Severity:** SHOULD | **Requirement:** TFNFR36\n\nFor robust testing, `prevent_deletion_if_contains_resources` **SHOULD** be explicitly set to `false` in test provider configurations.\n\n---\n\n## Documentation Requirements\n\n### Module Documentation Generation\n\n**Severity:** MUST | **Requirement:** TFNFR2\n\n- Documentation **MUST** be automatically generated via [Terraform Docs](https://github.com/terraform-docs/terraform-docs)\n- A `.terraform-docs.yml` file **MUST** be present in the module root\n\n---\n\n## Breaking Changes & Feature Management\n\n### Using Feature Toggles\n\n**Severity:** MUST | **Requirement:** TFNFR34\n\nNew resources added in minor/patch versions **MUST** have a toggle variable to avoid creation by default:\n\n```hcl\nvariable \"create_route_table\" {\n type = bool\n default = false\n nullable = false\n}\n\nresource \"azurerm_route_table\" \"this\" {\n count = var.create_route_table ? 1 : 0\n # ...\n}\n```\n\n### Reviewing Potential Breaking Changes\n\n**Severity:** MUST | **Requirement:** TFNFR35\n\n**Breaking changes requiring caution:**\n\n**Resource blocks:**\n\n1. Adding new resource without conditional creation\n2. Adding arguments with non-default values\n3. Adding nested blocks without `dynamic`\n4. Renaming resources without `moved` blocks\n5. Changing `count` to `for_each` or vice versa\n\n**Variable/Output blocks:**\n\n1. Deleting/renaming variables\n2. Changing variable `type`\n3. Changing variable `default` values\n4. Changing `nullable` to false\n5. Changing `sensitive` from false to true\n6. Adding variables without `default`\n7. Deleting outputs\n8. Changing output `value`\n9. Changing output `sensitive` value\n\n---\n\n## Contribution Standards\n\n### GitHub Repository Branch Protection\n\n**Severity:** MUST | **Requirement:** TFNFR3\n\nModule owners **MUST** set branch protection policies on the default branch (typically `main`):\n\n1. Require Pull Request before merging\n2. Require approval of most recent reviewable push\n3. Dismiss stale PR approvals when new commits are pushed\n4. Require linear history\n5. Prevent force pushes\n6. Not allow deletions\n7. Require CODEOWNERS review\n8. No bypassing settings allowed\n9. Enforce for administrators\n\n---\n\n## Compliance Checklist\n\nUse this checklist when developing or reviewing Azure Verified Modules:\n\n### Module Structure\n- [ ] Module cross-references use registry sources with pinned versions\n- [ ] Azure providers (azurerm/azapi) versions meet AVM requirements\n- [ ] `.terraform-docs.yml` present in module root\n- [ ] CODEOWNERS file present\n\n### Code Style\n- [ ] All names use lower snake_casing\n- [ ] Resources ordered with dependencies first\n- [ ] `for_each` uses `map()` or `set()` with static keys\n- [ ] Resource/data/module blocks follow proper internal ordering\n- [ ] `ignore_changes` not quoted\n- [ ] Dynamic blocks used for conditional nested objects\n- [ ] `coalesce()` or `try()` used for default values\n\n### Variables\n- [ ] No `enabled` or `module_depends_on` variables\n- [ ] Variables ordered: required (alphabetical) then optional (alphabetical)\n- [ ] All variables have precise types (avoid `any`)\n- [ ] All variables have descriptions\n- [ ] Collections have `nullable = false`\n- [ ] No `sensitive = false` declarations\n- [ ] No default values for sensitive inputs\n- [ ] Deprecated variables moved to `deprecated_variables.tf`\n\n### Outputs\n- [ ] Outputs use anti-corruption layer pattern (discrete attributes)\n- [ ] Sensitive outputs marked `sensitive = true`\n- [ ] Deprecated outputs moved to `deprecated_outputs.tf`\n\n### Terraform Configuration\n- [ ] `terraform.tf` has version constraints (`~>` format)\n- [ ] `required_providers` block present with all providers\n- [ ] No `provider` declarations in module (except aliases)\n- [ ] Locals arranged alphabetically\n\n### Testing & Quality\n- [ ] Required testing tools configured\n- [ ] New resources have feature toggles\n- [ ] Breaking changes reviewed and documented\n\n---\n\n## Summary Statistics\n\n- **Functional Requirements:** 3\n- **Non-Functional Requirements:** 34\n- **Total Requirements:** 37\n\n### By Severity\n- **MUST:** 21 requirements\n- **SHOULD:** 14 requirements\n- **MAY:** 2 requirements\n\n---\n\n*Based on: Azure Verified Modules - Terraform Requirements*\n"
},
{
"path": "terraform/code-generation/skills/terraform-search-import/SKILL.md",
"content": "---\nname: terraform-search-import\ndescription: Discover existing cloud resources using Terraform Search queries and bulk import them into Terraform management. Use when bringing unmanaged infrastructure under Terraform control, auditing cloud resources, or migrating to IaC.\nmetadata:\n copyright: Copyright IBM Corp. 2026\n version: \"0.1.0\"\ncompatibility: Requires Terraform >= 1.14 and providers with list resource support (always use latest provider version)\n---\n\n# Terraform Search and Bulk Import\n\nDiscover existing cloud resources using declarative queries and generate configuration for bulk import into Terraform state.\n\n**References:**\n- [Terraform Search - list block](https://developer.hashicorp.com/terraform/language/block/tfquery/list)\n- [Bulk Import](https://developer.hashicorp.com/terraform/language/import/bulk)\n\n## When to Use\n\n- Bringing unmanaged resources under Terraform control\n- Auditing existing cloud infrastructure\n- Migrating from manual provisioning to IaC\n- Discovering resources across multiple regions/accounts\n\n## IMPORTANT: Check Provider Support First\n\n**BEFORE starting, you MUST verify the target resource type is supported:**\n\n```bash\n# Check what list resources are available\n./scripts/list_resources.sh aws # Specific provider\n./scripts/list_resources.sh # All configured providers\n```\n\n## Decision Tree\n\n1. **Identify target resource type** (e.g., aws_s3_bucket, aws_instance)\n2. **Check if supported**: Run `./scripts/list_resources.sh `\n3. **Choose workflow**:\n - ** If supported**: Check for terraform version available.\n - ** If terraform version is above 1.14.0** Use Terraform Search workflow (below)\n - ** If not supported or terraform version is below 1.14.0 **: Use Manual Discovery workflow (see [references/MANUAL-IMPORT.md](references/MANUAL-IMPORT.md))\n \n **Note**: The list of supported resources is rapidly expanding. Always verify current support before using manual import.\n\n## Prerequisites\n\nBefore writing queries, verify the provider supports list resources for your target resource type.\n\n### Discover Available List Resources\n\nRun the helper script to extract supported list resources from your provider:\n\n```bash\n# From a directory with provider configuration (runs terraform init if needed)\n./scripts/list_resources.sh aws # Specific provider\n./scripts/list_resources.sh # All configured providers\n```\n\nOr manually query the provider schema:\n\n```bash\nterraform providers schema -json | jq '.provider_schemas | to_entries | map({key: (.key | split(\"/\")[-1]), value: (.value.list_resource_schemas // {} | keys)})'\n```\n\nTerraform Search requires an initialized working directory. Ensure you have a configuration with the required provider before running queries:\n\n```hcl\n# terraform.tf\nterraform {\n required_providers {\n aws = {\n source = \"hashicorp/aws\"\n version = \"~> 6.0\"\n }\n }\n}\n```\n\nRun `terraform init` to download the provider, then proceed with queries.\n\n## Terraform Search Workflow (Supported Resources Only)\n\n1. Create `.tfquery.hcl` files with `list` blocks defining search queries\n2. Run `terraform query` to discover matching resources\n3. Generate configuration with `-generate-config-out=`\n4. Review and refine generated `resource` and `import` blocks\n5. Run `terraform plan` and `terraform apply` to import\n\n## Query File Structure\n\nQuery files use `.tfquery.hcl` extension and support:\n- `provider` blocks for authentication\n- `list` blocks for resource discovery\n- `variable` and `locals` blocks for parameterization\n\n```hcl\n# discovery.tfquery.hcl\nprovider \"aws\" {\n region = \"us-west-2\"\n}\n\nlist \"aws_instance\" \"all\" {\n provider = aws\n}\n```\n\n## List Block Syntax\n\n```hcl\nlist \"\" \"\" {\n provider = # Required\n\n # Optional: filter configuration (provider-specific)\n # The `config` block schema is provider-specific. Discover available options using `terraform providers schema -json | jq '.provider_schemas.\"registry.terraform.io/hashicorp/\".list_resource_schemas.\"\"'`\n\n config {\n filter {\n name = \"\"\n values = [\"\", \"\"]\n }\n region = \"\" # AWS-specific\n }\n # Optional: limit results\n limit = 100\n}\n```\n\n## Supported List Resources\n\nProvider support for list resources varies by version. **Always check what's available for your specific provider version using the discovery script.**\n\n## Query Examples\n\n### Basic Discovery\n\n```hcl\n# Find all EC2 instances in configured region\nlist \"aws_instance\" \"all\" {\n provider = aws\n}\n```\n\n### Filtered Discovery\n\n```hcl\n# Find instances by tag\nlist \"aws_instance\" \"production\" {\n provider = aws\n \n config {\n filter {\n name = \"tag:Environment\"\n values = [\"production\"]\n }\n }\n}\n\n# Find instances by type\nlist \"aws_instance\" \"large\" {\n provider = aws\n \n config {\n filter {\n name = \"instance-type\"\n values = [\"t3.large\", \"t3.xlarge\"]\n }\n }\n}\n```\n\n### Multi-Region Discovery\n\n```hcl\nprovider \"aws\" {\n region = \"us-west-2\"\n}\n\nlocals {\n regions = [\"us-west-2\", \"us-east-1\", \"eu-west-1\"]\n}\n\nlist \"aws_instance\" \"all_regions\" {\n for_each = toset(local.regions)\n provider = aws\n \n config {\n region = each.value\n }\n}\n```\n\n### Parameterized Queries\n\n```hcl\nvariable \"target_environment\" {\n type = string\n default = \"staging\"\n}\n\nlist \"aws_instance\" \"by_env\" {\n provider = aws\n \n config {\n filter {\n name = \"tag:Environment\"\n values = [var.target_environment]\n }\n }\n}\n```\n\n## Running Queries\n\n```bash\n# Execute queries and display results\nterraform query\n\n# Generate configuration file\nterraform query -generate-config-out=imported.tf\n\n# Pass variables\nterraform query -var='target_environment=production'\n```\n\n## Query Output Format\n\n```\nlist.aws_instance.all account_id=123456789012,id=i-0abc123,region=us-west-2 web-server\n```\n\nColumns: ``\n\n## Generated Configuration\n\nThe `-generate-config-out` flag creates:\n\n```hcl\n# __generated__ by Terraform\nresource \"aws_instance\" \"all_0\" {\n ami = \"ami-0c55b159cbfafe1f0\"\n instance_type = \"t2.micro\"\n # ... all attributes\n}\n\nimport {\n to = aws_instance.all_0\n provider = aws\n identity = {\n account_id = \"123456789012\"\n id = \"i-0abc123\"\n region = \"us-west-2\"\n }\n}\n```\n\n## Post-Generation Cleanup\n\nGenerated configuration includes all attributes. Clean up by:\n\n1. Remove computed/read-only attributes\n2. Replace hardcoded values with variables\n3. Add proper resource naming\n4. Organize into appropriate files\n\n```hcl\n# Before: generated\nresource \"aws_instance\" \"all_0\" {\n ami = \"ami-0c55b159cbfafe1f0\"\n instance_type = \"t2.micro\"\n arn = \"arn:aws:ec2:...\" # Remove - computed\n id = \"i-0abc123\" # Remove - computed\n # ... many more attributes\n}\n\n# After: cleaned\nresource \"aws_instance\" \"web_server\" {\n ami = var.ami_id\n instance_type = var.instance_type\n subnet_id = var.subnet_id\n \n tags = {\n Name = \"web-server\"\n Environment = var.environment\n }\n}\n```\n\n## Import by Identity\n\nGenerated imports use identity-based import (Terraform 1.12+):\n\n```hcl\nimport {\n to = aws_instance.web\n provider = aws\n identity = {\n account_id = \"123456789012\"\n id = \"i-0abc123\"\n region = \"us-west-2\"\n }\n}\n```\n\n## Best Practices\n\n### Query Design\n- Start broad, then add filters to narrow results\n- Use `limit` to prevent overwhelming output\n- Test queries before generating configuration\n\n### Configuration Management\n- Review all generated code before applying\n- Remove unnecessary default values\n- Use consistent naming conventions\n- Add proper variable abstraction\n\n## Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| \"No list resources found\" | Check provider version supports list resources |\n| Query returns empty | Verify region and filter values |\n| Generated config has errors | Remove computed attributes, fix deprecated arguments |\n| Import fails | Ensure resource not already in state |\n\n## Complete Example\n\n```hcl\n# main.tf - Initialize provider\nterraform {\n required_version = \">= 1.14\"\n required_providers {\n aws = {\n source = \"hashicorp/aws\"\n version = \"~> 6.0\" # Always use latest version\n }\n }\n}\n\n# discovery.tfquery.hcl - Define queries\nprovider \"aws\" {\n region = \"us-west-2\"\n}\n\nlist \"aws_instance\" \"team_instances\" {\n provider = aws\n \n config {\n filter {\n name = \"tag:Owner\"\n values = [\"platform\"]\n }\n filter {\n name = \"instance-state-name\"\n values = [\"running\"]\n }\n }\n \n limit = 50\n}\n```\n\n```bash\n# Execute workflow\nterraform init\nterraform query\nterraform query -generate-config-out=generated.tf\n# Review and clean generated.tf\nterraform plan\nterraform apply\n```\n"
},
{
"path": "terraform/code-generation/skills/terraform-search-import/references/MANUAL-IMPORT.md",
"content": "# Manual Terraform Import Reference\n\nUse this workflow when your target resource type isn't supported by Terraform Search.\n\n## 1. Discover Resources Using Provider CLI\n\nAWS CLI examples:\n\n```bash\n# RDS instances (not yet supported by Terraform Search)\naws rds describe-db-instances --query 'DBInstances[].DBInstanceIdentifier'\n\n# DynamoDB tables (not yet supported by Terraform Search)\naws dynamodb list-tables --query 'TableNames[]'\n\n# API Gateway REST APIs (not yet supported by Terraform Search)\naws apigateway get-rest-apis --query 'items[].id'\n\n# SNS topics (not yet supported by Terraform Search)\naws sns list-topics --query 'Topics[].TopicArn'\n```\n\n## 2. Create Resource Blocks Manually\n\n```hcl\n# Example for RDS instance\nresource \"aws_db_instance\" \"existing_db\" {\n identifier = \"my-existing-db\"\n # Add other required attributes\n}\n\n# Example for DynamoDB table\nresource \"aws_dynamodb_table\" \"existing_table\" {\n name = \"my-existing-table\"\n # Add other required attributes\n}\n\n# Example for SNS topic\nresource \"aws_sns_topic\" \"existing_topic\" {\n name = \"my-existing-topic\"\n}\n```\n\n## 3. Create Import Blocks (Config-Driven Import)\n\n```hcl\n# Example for RDS instance\nresource \"aws_db_instance\" \"existing_db\" {\n identifier = \"my-existing-db\"\n # Add other required attributes\n}\n\nimport {\n to = aws_db_instance.existing_db\n id = \"my-existing-db\"\n}\n\n# Example for DynamoDB table\nresource \"aws_dynamodb_table\" \"existing_table\" {\n name = \"my-existing-table\"\n # Add other required attributes\n}\n\nimport {\n to = aws_dynamodb_table.existing_table\n id = \"my-existing-table\"\n}\n```\n\n## 4. Run Import Plan\n\n```bash\n# Plan the import to see what will happen\nterraform plan\n\n# Apply to import the resources\nterraform apply\n```\n\n## Bulk Import Script Example\n\nFor multiple resources of the same type:\n\n```bash\n#!/bin/bash\n# bulk-import-dynamodb.sh\n\n# Get all table names\ntables=$(aws dynamodb list-tables --query 'TableNames[]' --output text)\n\n# Generate import configuration\ncat > dynamodb-imports.tf << 'EOF'\n# DynamoDB Table Resources and Imports\nEOF\n\nfor table in $tables; do\n # Create resource and import blocks\n cat >> dynamodb-imports.tf << EOF\nresource \"aws_dynamodb_table\" \"table_${table//[-.]/_}\" {\n name = \"$table\"\n}\n\nimport {\n to = aws_dynamodb_table.table_${table//[-.]/_}\n id = \"$table\"\n}\n\nEOF\ndone\n\necho \"Generated dynamodb-imports.tf with import blocks\"\necho \"Run 'terraform plan' to review, then 'terraform apply' to import\"\n```\n"
},
{
"path": "terraform/code-generation/skills/terraform-search-import/scripts/list_resources.sh",
"content": "#!/bin/bash\n# Copyright IBM Corp. 2025, 2026\n# SPDX-License-Identifier: MPL-2.0\n\n# Extract list resources supported by Terraform providers\n# Usage: ./list_resources.sh [provider_name]\n# Requires: terraform, jq\n# Note: Run from an initialized Terraform directory (terraform init)\n\nset -e\n\nPROVIDER=$1\n\n# Ensure terraform is initialized\nif [ ! -d \".terraform\" ]; then\n echo \"Initializing Terraform...\" >&2\n terraform init -upgrade > /dev/null 2>&1\nfi\n\n# Get provider schema and extract list_resource_schemas\nif [ -n \"$PROVIDER\" ]; then\n # Specific provider\n provider_key=$(terraform providers schema -json 2>/dev/null | jq -r '.provider_schemas | keys[]' | grep \"/${PROVIDER}$\" || true)\n if [ -n \"$provider_key\" ]; then\n terraform providers schema -json 2>/dev/null | jq -r \\\n \"{\\\"$PROVIDER\\\": (.provider_schemas.\\\"${provider_key}\\\" | .list_resource_schemas // {} | keys | sort)}\"\n else\n echo \"{\\\"$PROVIDER\\\": []}\"\n fi\nelse\n # All providers\n terraform providers schema -json 2>/dev/null | jq -r '\n .provider_schemas\n | to_entries\n | map({key: (.key | split(\"/\")[-1]), value: (.value.list_resource_schemas // {} | keys | sort)})\n | from_entries\n '\nfi\n"
},
{
"path": "terraform/code-generation/skills/terraform-style-guide/SECURITY.md",
"content": "---\nname: terraform-style-guide-security\ndescription: Generate Terraform HCL code following HashiCorp's security practices\n---\n\n# Terraform Style Guide - Security\n\nWhen generating code, apply security hardening:\n\n- Enable encryption at rest by default\n- Configure private networking where applicable\n- Apply principle of least privilege for security groups\n- Enable logging and monitoring\n- Never hardcode credentials or secrets\n- Mark sensitive outputs with `sensitive = true`\n- Use `ephemeral` resources and write-only attributes\n for sensitive data when possible\n\n## Example: Secure S3 Bucket\n\n```hcl\nresource \"aws_s3_bucket\" \"data\" {\n bucket = \"${var.project}-${var.environment}-data\"\n tags = local.common_tags\n}\n\nresource \"aws_s3_bucket_versioning\" \"data\" {\n bucket = aws_s3_bucket.data.id\n\n versioning_configuration {\n status = \"Enabled\"\n }\n}\n\nresource \"aws_s3_bucket_server_side_encryption_configuration\" \"data\" {\n bucket = aws_s3_bucket.data.id\n\n rule {\n apply_server_side_encryption_by_default {\n sse_algorithm = \"aws:kms\"\n kms_master_key_id = aws_kms_key.s3.arn\n }\n }\n}\n\nresource \"aws_s3_bucket_public_access_block\" \"data\" {\n bucket = aws_s3_bucket.data.id\n\n block_public_acls = true\n block_public_policy = true\n ignore_public_acls = true\n restrict_public_buckets = true\n}\n```\n\n## Ephemeral resources\n\nEphemeral resources prevent sensitive data being stored in state.\nFor more information on ephemeral resources, see the\n[Terraform documentation](https://developer.hashicorp.com/terraform/language/block/ephemeral).\n\nBefore you generate code for an ephemeral resource, check that the Terraform\nversion is greater than or equal to 1.11.0.\n\nThen, follow this priority order for managing sensitive attributes:\n\n1. **First priority: Native secrets manager integration**\n If a resource has the ability to automatically manage a sensitive attribute by\n storing it in a secrets manager (e.g., AWS Secrets Manager, Azure Key Vault),\n use that configuration. This is the preferred approach.\n\n ```hcl\n # Bad\n resource \"aws_rds_cluster\" \"example\" {\n cluster_identifier = \"example\"\n database_name = \"test\"\n master_username = \"test\"\n master_password = var.db_master_password\n }\n\n # Good, managed by AWS Secrets Manager by default\n resource \"aws_rds_cluster\" \"test\" {\n cluster_identifier = \"example\"\n database_name = \"test\"\n manage_master_user_password = true\n master_username = \"test\"\n }\n ```\n\n2. **Second priority: Write-only attributes with ephemeral resources**\n If a resource has a write-only attribute but no native secrets manager integration,\n use an `ephemeral` resource for the sensitive data and pass that to the write-only\n attribute. Default the write-only version to 1.\n\n ```hcl\n # Bad\n resource \"random_password\" \"password\" {\n length = 16\n special = true\n override_special = \"!#$%&*()-_=+[]{}<>:?\"\n }\n \n resource \"vault_kv_secret_v2\" \"example\" {\n mount = vault_mount.kvv2.path\n name = \"secret\"\n \n data_json = jsonencode(\n {\n password = \"${random_password.password.result}\",\n }\n )\n }\n \n # Good\n ephemeral \"random_password\" \"password\" {\n length = 16\n special = true\n override_special = \"!#$%&*()-_=+[]{}<>:?\"\n }\n \n resource \"vault_kv_secret_v2\" \"example\" {\n mount = vault_mount.kvv2.path\n name = \"secret\"\n \n data_json_wo = jsonencode(\n {\n password = \"${ephemeral.random_password.password.result}\",\n }\n )\n data_json_wo_version = 1\n }\n ```\n\n If you need to retrieve a secret from a secrets manager to pass\n to a resource, use the `ephemeral` version of the resource to\n retrieve the secret and pass it to another resource.\n \n ```hcl\n # Good\n ephemeral \"vault_kv_secret_v2\" \"db_secret\" {\n mount = vault_mount.kvv2.path\n mount_id = vault_mount.kvv2.id\n name = vault_kv_secret_v2.db_root.name\n }\n \n resource \"vault_database_secret_backend_connection\" \"postgres\" {\n backend = vault_mount.db.path\n name = \"postrgres-db\"\n allowed_roles = [\"*\"]\n \n postgresql {\n connection_url = \"postgresql://{{username}}:{{password}}@localhost:5432/postgres\"\n password_authentication = \"\"\n username = \"postgres\"\n password_wo = tostring(ephemeral.vault_kv_secret_v2.db_secret.data.password)\n password_wo_version = 1\n }\n }\n ```\n\n3. **Last resort: Regular resources**\n Only use a regular resource that has sensitive data written to state if neither of the above\n options are available, resource does not offer a write-only attribute or ephemeral resource\n alternative, or the Terraform version is less than 1.11.0."
},
{
"path": "terraform/code-generation/skills/terraform-style-guide/SKILL.md",
"content": "---\nname: terraform-style-guide\ndescription: Generate Terraform HCL code following HashiCorp's official style conventions and best practices. Use when writing, reviewing, or generating Terraform configurations.\n---\n\n# Terraform Style Guide\n\nGenerate and maintain Terraform code following HashiCorp's official style conventions and best practices.\n\n**Reference:** [HashiCorp Terraform Style Guide](https://developer.hashicorp.com/terraform/language/style)\n\n## Code Generation Strategy\n\nWhen generating Terraform code:\n\n1. Start with provider configuration and version constraints\n2. Create data sources before dependent resources\n3. Build resources in dependency order\n4. Add outputs for key resource attributes\n5. Use variables for all configurable values\n\n## File Organization\n\n| File | Purpose |\n|------|---------|\n| `terraform.tf` | Terraform and provider version requirements |\n| `providers.tf` | Provider configurations |\n| `main.tf` | Primary resources and data sources |\n| `variables.tf` | Input variable declarations (alphabetical) |\n| `outputs.tf` | Output value declarations (alphabetical) |\n| `locals.tf` | Local value declarations |\n\n### Example Structure\n\n```hcl\n# terraform.tf\nterraform {\n required_version = \">= 1.14\"\n\n required_providers {\n aws = {\n source = \"hashicorp/aws\"\n version = \"~> 6.0\"\n }\n }\n}\n\n# variables.tf\nvariable \"environment\" {\n description = \"Target deployment environment\"\n type = string\n\n validation {\n condition = contains([\"dev\", \"staging\", \"prod\"], var.environment)\n error_message = \"Environment must be dev, staging, or prod.\"\n }\n}\n\n# locals.tf\nlocals {\n common_tags = {\n Environment = var.environment\n ManagedBy = \"Terraform\"\n }\n}\n\n# main.tf\nresource \"aws_vpc\" \"main\" {\n cidr_block = var.vpc_cidr\n enable_dns_hostnames = true\n\n tags = merge(local.common_tags, {\n Name = \"${var.project_name}-${var.environment}-vpc\"\n })\n}\n\n# outputs.tf\noutput \"vpc_id\" {\n description = \"ID of the created VPC\"\n value = aws_vpc.main.id\n}\n```\n\n## Code Formatting\n\n### Indentation and Alignment\n\n- Use **two spaces** per nesting level (no tabs)\n- Align equals signs for consecutive arguments\n\n```hcl\nresource \"aws_instance\" \"web\" {\n ami = \"ami-0c55b159cbfafe1f0\"\n instance_type = \"t2.micro\"\n subnet_id = \"subnet-12345678\"\n\n tags = {\n Name = \"web-server\"\n Environment = \"production\"\n }\n}\n```\n\n### Block Organization\n\nArguments precede blocks, with meta-arguments first:\n\n```hcl\nresource \"aws_instance\" \"example\" {\n # Meta-arguments\n count = 3\n\n # Arguments\n ami = \"ami-0c55b159cbfafe1f0\"\n instance_type = \"t2.micro\"\n\n # Blocks\n root_block_device {\n volume_size = 20\n }\n\n # Lifecycle last\n lifecycle {\n create_before_destroy = true\n }\n}\n```\n\n## Naming Conventions\n\n- Use **lowercase with underscores** for all names\n- Use **descriptive nouns** excluding the resource type\n- Be specific and meaningful\n- Resource names must be singular, not plural\n- Default to `main` for resources where a specific descriptive name is redundant or unavailable, provided only one instance exists\n\n```hcl\n# Bad\nresource \"aws_instance\" \"webAPI-aws-instance\" {}\nresource \"aws_instance\" \"web_apis\" {}\nvariable \"name\" {}\n\n# Good\nresource \"aws_instance\" \"web_api\" {}\nresource \"aws_vpc\" \"main\" {}\nvariable \"application_name\" {}\n```\n\n## Variables\n\nEvery variable must include `type` and `description`:\n\n```hcl\nvariable \"instance_type\" {\n description = \"EC2 instance type for the web server\"\n type = string\n default = \"t2.micro\"\n\n validation {\n condition = contains([\"t2.micro\", \"t2.small\", \"t2.medium\"], var.instance_type)\n error_message = \"Instance type must be t2.micro, t2.small, or t2.medium.\"\n }\n}\n\nvariable \"database_password\" {\n description = \"Password for the database admin user\"\n type = string\n sensitive = true\n}\n```\n\n## Outputs\n\nEvery output must include `description`:\n\n```hcl\noutput \"instance_id\" {\n description = \"ID of the EC2 instance\"\n value = aws_instance.web.id\n}\n\noutput \"database_password\" {\n description = \"Database administrator password\"\n value = aws_db_instance.main.password\n sensitive = true\n}\n```\n\n## Dynamic Resource Creation\n\n### Prefer for_each over count\n\n```hcl\n# Bad - count for multiple resources\nresource \"aws_instance\" \"web\" {\n count = var.instance_count\n tags = { Name = \"web-${count.index}\" }\n}\n\n# Good - for_each with named instances\nvariable \"instance_names\" {\n type = set(string)\n default = [\"web-1\", \"web-2\", \"web-3\"]\n}\n\nresource \"aws_instance\" \"web\" {\n for_each = var.instance_names\n tags = { Name = each.key }\n}\n```\n\n### count for Conditional Creation\n\n```hcl\nresource \"aws_cloudwatch_metric_alarm\" \"cpu\" {\n count = var.enable_monitoring ? 1 : 0\n\n alarm_name = \"high-cpu-usage\"\n threshold = 80\n}\n```\n\n## Security Best Practices\n\nRefer to SECURITY.md. It includes guidance on encrypting resources,\npreventing sensitive data in state, and secure configurations.\n\n## Version Pinning\n\n```hcl\nterraform {\n required_version = \">= 1.14\"\n\n required_providers {\n aws = {\n source = \"hashicorp/aws\"\n version = \"~> 6.0\"\n }\n }\n}\n```\n\nUse the latest major version of each provider and the latest minor version of\nTerraform, unless otherwise constrained by a dependency lock file or by other\nmodules used by the configuration.\n\n**Version constraint operators:**\n- `= 1.0.0` - Exact version\n- `>= 1.0.0` - Greater than or equal\n- `~> 1.0` - Allow rightmost component to increment\n- `>= 1.0, < 2.0` - Version range\n\n## Provider Configuration\n\n```hcl\nprovider \"aws\" {\n region = \"us-west-2\"\n\n default_tags {\n tags = {\n ManagedBy = \"Terraform\"\n Project = var.project_name\n }\n }\n}\n\n# Aliased provider for multi-region\nprovider \"aws\" {\n alias = \"east\"\n region = \"us-east-1\"\n}\n```\n\n## Version Control\n\n**Never commit:**\n- `terraform.tfstate`, `terraform.tfstate.backup`\n- `.terraform/` directory\n- `*.tfplan`\n- `.tfvars` files with sensitive data\n\n**Always commit:**\n- All `.tf` configuration files\n- `.terraform.lock.hcl` (dependency lock file)\n\n## Validation Tools\n\nRun before committing:\n\n```bash\nterraform fmt -recursive\nterraform validate\n```\n\nAdditional tools:\n- `tflint` - Linting and best practices\n- `checkov` / `tfsec` - Security scanning\n\n## Code Review Checklist\n\n- [ ] Code formatted with `terraform fmt`\n- [ ] Configuration validated with `terraform validate`\n- [ ] Files organized according to standard structure\n- [ ] All variables have type and description\n- [ ] All outputs have descriptions\n- [ ] Resource names use descriptive nouns with underscores\n- [ ] Version constraints pinned explicitly\n- [ ] Sensitive values marked with `sensitive = true`\n- [ ] No hardcoded credentials or secrets\n- [ ] Security best practices applied\n\n---\n\n*Based on: [HashiCorp Terraform Style Guide](https://developer.hashicorp.com/terraform/language/style)*\n"
},
{
"path": "terraform/code-generation/skills/terraform-test/SKILL.md",
"content": "---\nname: terraform-test\ndescription: Comprehensive guide for writing and running Terraform tests. Use when creating test files (.tftest.hcl), writing test scenarios with run blocks, validating infrastructure behavior with assertions, mocking providers and data sources, testing module outputs and resource configurations, or troubleshooting Terraform test syntax and execution.\nmetadata:\n copyright: Copyright IBM Corp. 2026\n version: \"0.0.2\"\n---\n\n# Terraform Test\n\nTerraform's built-in testing framework validates that configuration updates don't introduce breaking changes. Tests run against temporary resources, protecting existing infrastructure and state files.\n\n## Reference Files\n\n- `references/MOCK_PROVIDERS.md` ā Mock provider syntax, common defaults, when to use mocks (Terraform 1.7.0+ only ā skip if the user's version is below 1.7)\n- `references/CI_CD.md` ā GitHub Actions and GitLab CI pipeline examples\n- `references/EXAMPLES.md` ā Complete example test suite (unit, integration, and mock tests for a VPC module)\n\nRead the relevant reference file when the user asks about mocking, CI/CD integration, or wants a full example.\n\n## Core Concepts\n\n- **Test file** (`.tftest.hcl` / `.tftest.json`): Contains `run` blocks that validate your configuration\n- **Run block**: A single test scenario with optional variables, providers, and assertions\n- **Assert block**: Conditions that must be true for the test to pass\n- **Mock provider**: Simulates provider behavior without real infrastructure (Terraform 1.7.0+)\n- **Test modes**: `apply` (default, creates real resources) or `plan` (validates logic only)\n\n## File Structure\n\n```\nmy-module/\nāāā main.tf\nāāā variables.tf\nāāā outputs.tf\nāāā tests/\n āāā defaults_unit_test.tftest.hcl # plan mode ā fast, no resources\n āāā validation_unit_test.tftest.hcl # plan mode\n āāā full_stack_integration_test.tftest.hcl # apply mode ā creates real resources\n```\n\nUse `*_unit_test.tftest.hcl` for plan-mode tests and `*_integration_test.tftest.hcl` for apply-mode tests so they can be filtered separately in CI.\n\n## Test File Structure\n\n```hcl\n# Optional: test-wide settings\ntest {\n parallel = true # Enable parallel execution for all run blocks (default: false)\n}\n\n# Optional: file-level variables (highest precedence, override all other sources)\nvariables {\n aws_region = \"us-west-2\"\n instance_type = \"t2.micro\"\n}\n\n# Optional: provider configuration\nprovider \"aws\" {\n region = var.aws_region\n}\n\n# Required: at least one run block\nrun \"test_default_configuration\" {\n command = plan\n\n assert {\n condition = aws_instance.example.instance_type == \"t2.micro\"\n error_message = \"Instance type should be t2.micro by default\"\n }\n}\n```\n\n## Run Block\n\n```hcl\nrun \"test_name\" {\n command = plan # or apply (default)\n parallel = true # optional, since v1.9.0\n\n # Override file-level variables\n variables {\n instance_type = \"t3.large\"\n }\n\n # Reference a specific module\n module {\n source = \"./modules/vpc\" # local or registry only (not git/http)\n version = \"5.0.0\" # registry modules only\n }\n\n # Control state isolation\n state_key = \"shared_state\" # since v1.9.0\n\n # Plan behavior\n plan_options {\n mode = refresh-only # or normal (default)\n refresh = true\n replace = [aws_instance.example]\n target = [aws_instance.example]\n }\n\n # Assertions\n assert {\n condition = aws_instance.example.id != \"\"\n error_message = \"Instance should have a valid ID\"\n }\n\n # Expected failures (test passes if these fail)\n expect_failures = [\n var.instance_count\n ]\n}\n```\n\n## Common Test Patterns\n\n### Validate outputs\n\n```hcl\nrun \"test_outputs\" {\n command = plan\n\n assert {\n condition = output.vpc_id != null\n error_message = \"VPC ID output must be defined\"\n }\n\n assert {\n condition = can(regex(\"^vpc-\", output.vpc_id))\n error_message = \"VPC ID should start with 'vpc-'\"\n }\n}\n```\n\n### Conditional resources\n\n```hcl\nrun \"test_nat_gateway_disabled\" {\n command = plan\n\n variables {\n create_nat_gateway = false\n }\n\n assert {\n condition = length(aws_nat_gateway.main) == 0\n error_message = \"NAT gateway should not be created when disabled\"\n }\n}\n```\n\n### Resource counts\n\n```hcl\nrun \"test_resource_count\" {\n command = plan\n\n variables {\n instance_count = 3\n }\n\n assert {\n condition = length(aws_instance.workers) == 3\n error_message = \"Should create exactly 3 worker instances\"\n }\n}\n```\n\n### Tags\n\n```hcl\nrun \"test_resource_tags\" {\n command = plan\n\n variables {\n common_tags = {\n Environment = \"production\"\n ManagedBy = \"Terraform\"\n }\n }\n\n assert {\n condition = aws_instance.example.tags[\"Environment\"] == \"production\"\n error_message = \"Environment tag should be set correctly\"\n }\n\n assert {\n condition = aws_instance.example.tags[\"ManagedBy\"] == \"Terraform\"\n error_message = \"ManagedBy tag should be set correctly\"\n }\n}\n```\n\n### Data sources\n\n```hcl\nrun \"test_data_source_lookup\" {\n command = plan\n\n assert {\n condition = data.aws_ami.ubuntu.id != \"\"\n error_message = \"Should find a valid Ubuntu AMI\"\n }\n\n assert {\n condition = can(regex(\"^ami-\", data.aws_ami.ubuntu.id))\n error_message = \"AMI ID should be in correct format\"\n }\n}\n```\n\n### Validation rules\n\n```hcl\nrun \"test_invalid_environment\" {\n command = plan\n\n variables {\n environment = \"invalid\"\n }\n\n expect_failures = [\n var.environment\n ]\n}\n```\n\n### Sequential tests with dependencies\n\n```hcl\nrun \"setup_vpc\" {\n command = apply\n\n assert {\n condition = output.vpc_id != \"\"\n error_message = \"VPC should be created\"\n }\n}\n\nrun \"test_subnet_in_vpc\" {\n command = plan\n\n variables {\n vpc_id = run.setup_vpc.vpc_id\n }\n\n assert {\n condition = aws_subnet.example.vpc_id == run.setup_vpc.vpc_id\n error_message = \"Subnet should be in the VPC from setup_vpc\"\n }\n}\n```\n\n### Plan options (refresh-only, targeted)\n\n```hcl\nrun \"test_refresh_only\" {\n command = plan\n\n plan_options {\n mode = refresh-only\n }\n\n assert {\n condition = aws_instance.example.tags[\"Environment\"] == \"production\"\n error_message = \"Tags should be refreshed correctly\"\n }\n}\n\nrun \"test_specific_resource\" {\n command = plan\n\n plan_options {\n target = [aws_instance.example]\n }\n\n assert {\n condition = aws_instance.example.instance_type == \"t2.micro\"\n error_message = \"Targeted resource should be planned\"\n }\n}\n```\n\n### Parallel modules\n\n```hcl\nrun \"test_networking_module\" {\n command = plan\n parallel = true\n\n module {\n source = \"./modules/networking\"\n }\n\n assert {\n condition = output.vpc_id != \"\"\n error_message = \"VPC should be created\"\n }\n}\n\nrun \"test_compute_module\" {\n command = plan\n parallel = true\n\n module {\n source = \"./modules/compute\"\n }\n\n assert {\n condition = output.instance_id != \"\"\n error_message = \"Instance should be created\"\n }\n}\n```\n\n### State key sharing\n\n```hcl\nrun \"create_foundation\" {\n command = apply\n state_key = \"foundation\"\n\n assert {\n condition = aws_vpc.main.id != \"\"\n error_message = \"Foundation VPC should be created\"\n }\n}\n\nrun \"create_application\" {\n command = apply\n state_key = \"foundation\"\n\n variables {\n vpc_id = run.create_foundation.vpc_id\n }\n\n assert {\n condition = aws_instance.app.vpc_id == run.create_foundation.vpc_id\n error_message = \"Application should use foundation VPC\"\n }\n}\n```\n\n### Cleanup ordering (S3 objects before bucket)\n\n```hcl\nrun \"create_bucket\" {\n command = apply\n\n assert {\n condition = aws_s3_bucket.example.id != \"\"\n error_message = \"Bucket should be created\"\n }\n}\n\nrun \"add_objects\" {\n command = apply\n\n assert {\n condition = length(aws_s3_object.files) > 0\n error_message = \"Objects should be added\"\n }\n}\n\n# Cleanup destroys in reverse: objects first, then bucket\n```\n\n### Multiple aliased providers\n\n```hcl\nprovider \"aws\" {\n alias = \"primary\"\n region = \"us-west-2\"\n}\n\nprovider \"aws\" {\n alias = \"secondary\"\n region = \"us-east-1\"\n}\n\nrun \"test_with_specific_provider\" {\n command = plan\n\n providers = {\n aws = provider.aws.secondary\n }\n\n assert {\n condition = aws_instance.example.availability_zone == \"us-east-1a\"\n error_message = \"Instance should be in us-east-1 region\"\n }\n}\n```\n\n### Complex conditions\n\n```hcl\nassert {\n condition = alltrue([\n for subnet in aws_subnet.private :\n can(regex(\"^10\\\\.0\\\\.\", subnet.cidr_block))\n ])\n error_message = \"All private subnets should use 10.0.0.0/8 CIDR range\"\n}\n```\n\n## Cleanup\n\nResources are destroyed in **reverse run block order** after test completion. This matters for dependencies (e.g., S3 objects before bucket). Use `terraform test -no-cleanup` to skip cleanup for debugging.\n\n## Running Tests\n\n```bash\nterraform test # all tests\nterraform test tests/defaults.tftest.hcl # specific file\nterraform test -filter=test_vpc_configuration # by run block name\nterraform test -test-directory=integration-tests # custom directory\nterraform test -verbose # detailed output\nterraform test -no-cleanup # skip resource cleanup\n```\n\n## Best Practices\n\n1. **Naming**: `*_unit_test.tftest.hcl` for plan mode, `*_integration_test.tftest.hcl` for apply mode\n2. **Test naming**: Use descriptive run block names that explain the scenario being tested\n3. **Default to plan**: Use `command = plan` unless you need to test real resource behavior\n4. **Use mocks** for external dependencies ā faster and no credentials needed (see `references/MOCK_PROVIDERS.md`)\n5. **Error messages**: Make them specific enough to diagnose failures without running the test again\n6. **Negative tests**: Use `expect_failures` to verify validation rules reject bad inputs\n7. **Variable coverage**: Test different variable combinations to validate all code paths ā test variables have the highest precedence and override all other sources\n8. **Module sources**: Test files only support local paths and registry modules ā not git or HTTP URLs\n9. **Parallel execution**: Use `parallel = true` for independent tests with different state files\n10. **Cleanup**: Integration tests destroy resources in reverse run block order automatically; use `-no-cleanup` for debugging\n11. **CI/CD**: Run unit tests on every PR, integration tests on merge (see `references/CI_CD.md`)\n\n## Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| Assertion failures | Use `-verbose` to see actual vs expected values |\n| Missing credentials | Use mock providers for unit tests |\n| Unsupported module source | Convert git/HTTP sources to local modules |\n| Tests interfering | Use `state_key` or separate modules for isolation |\n| Slow tests | Use `command = plan` and mocks; run integration tests separately |\n\n## References\n\n- [Terraform Testing Documentation](https://developer.hashicorp.com/terraform/language/tests)\n- [Terraform Test Command](https://developer.hashicorp.com/terraform/cli/commands/test)\n- [Testing Best Practices](https://developer.hashicorp.com/terraform/language/tests/best-practices)\n"
},
{
"path": "terraform/code-generation/skills/terraform-test/references/CI_CD.md",
"content": "# CI/CD Integration\n\n## GitHub Actions\n\n```yaml\nname: Terraform Tests\n\non:\n pull_request:\n branches: [ main ]\n push:\n branches: [ main ]\n\njobs:\n unit-tests:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: hashicorp/setup-terraform@v3\n with:\n terraform_version: 1.9.0\n\n - run: terraform fmt -check -recursive\n - run: terraform init\n - run: terraform validate\n - name: Run unit tests (plan mode, no credentials needed)\n run: terraform test -filter=unit_test -verbose\n\n integration-tests:\n runs-on: ubuntu-latest\n needs: unit-tests\n if: github.ref == 'refs/heads/main'\n steps:\n - uses: actions/checkout@v4\n - uses: hashicorp/setup-terraform@v3\n with:\n terraform_version: 1.9.0\n\n - run: terraform init\n - name: Run integration tests\n run: terraform test -filter=integration_test -verbose\n env:\n AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}\n AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}\n```\n\n## GitLab CI\n\n```yaml\nstages:\n - validate\n - test\n\nterraform-unit-tests:\n image: hashicorp/terraform:1.9\n stage: validate\n before_script:\n - terraform init\n script:\n - terraform fmt -check -recursive\n - terraform validate\n - terraform test -filter=unit_test -verbose\n\nterraform-integration-tests:\n image: hashicorp/terraform:1.9\n stage: test\n before_script:\n - terraform init\n script:\n - terraform test -filter=integration_test -verbose\n only:\n - main\n```\n\n## Recommended CI Strategy\n\n- Run unit tests (plan mode + mock tests) on every PR ā fast, no credentials needed\n- Run integration tests only on merge to main or nightly ā requires cloud credentials\n- Use `-filter=unit_test` / `-filter=integration_test` to separate test types based on naming convention\n- Store cloud credentials as CI secrets, never in code\n"
},
{
"path": "terraform/code-generation/skills/terraform-test/references/EXAMPLES.md",
"content": "# Example Test Suite\n\nComplete example testing a VPC module with unit, integration, and mock tests.\n\n## Unit Tests (Plan Mode)\n\n```hcl\n# tests/vpc_module_unit_test.tftest.hcl\n\nvariables {\n environment = \"test\"\n aws_region = \"us-west-2\"\n}\n\nrun \"test_defaults\" {\n command = plan\n\n variables {\n vpc_cidr = \"10.0.0.0/16\"\n vpc_name = \"test-vpc\"\n }\n\n assert {\n condition = aws_vpc.main.cidr_block == \"10.0.0.0/16\"\n error_message = \"VPC CIDR should match input\"\n }\n\n assert {\n condition = aws_vpc.main.enable_dns_hostnames == true\n error_message = \"DNS hostnames should be enabled by default\"\n }\n\n assert {\n condition = aws_vpc.main.tags[\"Name\"] == \"test-vpc\"\n error_message = \"VPC name tag should match input\"\n }\n}\n\nrun \"test_subnets\" {\n command = plan\n\n variables {\n vpc_cidr = \"10.0.0.0/16\"\n vpc_name = \"test-vpc\"\n public_subnets = [\"10.0.1.0/24\", \"10.0.2.0/24\"]\n private_subnets = [\"10.0.10.0/24\", \"10.0.11.0/24\"]\n }\n\n assert {\n condition = length(aws_subnet.public) == 2\n error_message = \"Should create 2 public subnets\"\n }\n\n assert {\n condition = length(aws_subnet.private) == 2\n error_message = \"Should create 2 private subnets\"\n }\n\n assert {\n condition = alltrue([\n for subnet in aws_subnet.private :\n subnet.map_public_ip_on_launch == false\n ])\n error_message = \"Private subnets should not assign public IPs\"\n }\n}\n\nrun \"test_outputs\" {\n command = plan\n\n variables {\n vpc_cidr = \"10.0.0.0/16\"\n vpc_name = \"test-vpc\"\n }\n\n assert {\n condition = output.vpc_id != \"\"\n error_message = \"VPC ID output should not be empty\"\n }\n\n assert {\n condition = can(regex(\"^vpc-\", output.vpc_id))\n error_message = \"VPC ID should have correct format\"\n }\n\n assert {\n condition = output.vpc_cidr == \"10.0.0.0/16\"\n error_message = \"VPC CIDR output should match input\"\n }\n}\n\nrun \"test_invalid_cidr\" {\n command = plan\n\n variables {\n vpc_cidr = \"invalid\"\n vpc_name = \"test-vpc\"\n }\n\n expect_failures = [\n var.vpc_cidr\n ]\n}\n```\n\n## Integration Tests (Apply Mode)\n\n```hcl\n# tests/vpc_module_integration_test.tftest.hcl\n\nvariables {\n environment = \"integration-test\"\n aws_region = \"us-west-2\"\n}\n\nrun \"integration_test_vpc_creation\" {\n # command defaults to apply ā creates real AWS resources\n\n variables {\n vpc_cidr = \"10.100.0.0/16\"\n vpc_name = \"integration-test-vpc\"\n }\n\n assert {\n condition = aws_vpc.main.id != \"\"\n error_message = \"VPC should be created with valid ID\"\n }\n\n assert {\n condition = aws_vpc.main.state == \"available\"\n error_message = \"VPC should be in available state\"\n }\n}\n```\n\n## Mock Tests (Plan Mode, No Credentials)\n\n```hcl\n# tests/vpc_module_mock_test.tftest.hcl\n\nmock_provider \"aws\" {\n mock_resource \"aws_instance\" {\n defaults = {\n id = \"i-1234567890abcdef0\"\n instance_type = \"t2.micro\"\n ami = \"ami-12345678\"\n public_ip = \"203.0.113.1\"\n private_ip = \"10.0.1.100\"\n }\n }\n\n mock_resource \"aws_vpc\" {\n defaults = {\n id = \"vpc-12345678\"\n cidr_block = \"10.0.0.0/16\"\n enable_dns_hostnames = true\n enable_dns_support = true\n }\n }\n\n mock_resource \"aws_subnet\" {\n defaults = {\n id = \"subnet-12345678\"\n vpc_id = \"vpc-12345678\"\n cidr_block = \"10.0.1.0/24\"\n availability_zone = \"us-west-2a\"\n map_public_ip_on_launch = false\n }\n }\n\n mock_data \"aws_ami\" {\n defaults = {\n id = \"ami-0c55b159cbfafe1f0\"\n name = \"ubuntu-focal-20.04-amd64\"\n }\n }\n\n mock_data \"aws_availability_zones\" {\n defaults = {\n names = [\"us-west-2a\", \"us-west-2b\", \"us-west-2c\"]\n }\n }\n}\n\nrun \"test_instance_with_mocks\" {\n command = plan\n\n variables {\n instance_type = \"t2.micro\"\n ami_id = \"ami-12345678\"\n }\n\n assert {\n condition = aws_instance.example.instance_type == \"t2.micro\"\n error_message = \"Instance type should match input variable\"\n }\n\n assert {\n condition = aws_instance.example.id == \"i-1234567890abcdef0\"\n error_message = \"Mock should return consistent instance ID\"\n }\n}\n\nrun \"test_data_source_with_mocks\" {\n command = plan\n\n assert {\n condition = data.aws_ami.ubuntu.id == \"ami-0c55b159cbfafe1f0\"\n error_message = \"Mock data source should return predictable AMI ID\"\n }\n\n assert {\n condition = length(data.aws_availability_zones.available.names) == 3\n error_message = \"Should return 3 mocked availability zones\"\n }\n\n assert {\n condition = contains(data.aws_availability_zones.available.names, \"us-west-2a\")\n error_message = \"Should include us-west-2a in mocked zones\"\n }\n}\n\nrun \"test_outputs_with_mocks\" {\n command = plan\n\n assert {\n condition = output.vpc_id == \"vpc-12345678\"\n error_message = \"VPC ID output should match mocked value\"\n }\n\n assert {\n condition = can(regex(\"^vpc-\", output.vpc_id))\n error_message = \"VPC ID output should have correct format\"\n }\n}\n\nrun \"test_conditional_resources_with_mocks\" {\n command = plan\n\n variables {\n create_bastion = true\n create_nat_gateway = false\n }\n\n assert {\n condition = length(aws_instance.bastion) == 1\n error_message = \"Bastion should be created when enabled\"\n }\n\n assert {\n condition = length(aws_nat_gateway.nat) == 0\n error_message = \"NAT gateway should not be created when disabled\"\n }\n}\n\nrun \"test_tag_inheritance_with_mocks\" {\n command = plan\n\n variables {\n common_tags = {\n Environment = \"test\"\n ManagedBy = \"Terraform\"\n }\n }\n\n assert {\n condition = alltrue([\n for key in keys(var.common_tags) :\n contains(keys(aws_instance.example.tags), key)\n ])\n error_message = \"All common tags should be present on instance\"\n }\n}\n\nrun \"test_invalid_cidr_with_mocks\" {\n command = plan\n\n variables {\n vpc_cidr = \"invalid\"\n }\n\n expect_failures = [\n var.vpc_cidr\n ]\n}\n\nrun \"setup_vpc_with_mocks\" {\n command = plan\n\n variables {\n vpc_cidr = \"10.0.0.0/16\"\n vpc_name = \"test-vpc\"\n }\n\n assert {\n condition = aws_vpc.main.cidr_block == \"10.0.0.0/16\"\n error_message = \"VPC CIDR should match input\"\n }\n}\n\nrun \"test_subnet_references_vpc_with_mocks\" {\n command = plan\n\n variables {\n vpc_id = run.setup_vpc_with_mocks.vpc_id\n subnet_cidr = \"10.0.1.0/24\"\n }\n\n assert {\n condition = aws_subnet.example.vpc_id == run.setup_vpc_with_mocks.vpc_id\n error_message = \"Subnet should reference VPC from previous run\"\n }\n}\n```\n"
},
{
"path": "terraform/code-generation/skills/terraform-test/references/MOCK_PROVIDERS.md",
"content": "# Mock Providers\n\nMock providers simulate provider behavior without creating real infrastructure (Terraform 1.7.0+). Use them for fast, credential-free unit tests.\n\n## Basic Mock Provider\n\n```hcl\nmock_provider \"aws\" {\n mock_resource \"aws_instance\" {\n defaults = {\n id = \"i-1234567890abcdef0\"\n instance_type = \"t2.micro\"\n ami = \"ami-12345678\"\n public_ip = \"203.0.113.1\"\n private_ip = \"10.0.1.100\"\n }\n }\n\n mock_data \"aws_ami\" {\n defaults = {\n id = \"ami-0c55b159cbfafe1f0\"\n }\n }\n\n mock_data \"aws_availability_zones\" {\n defaults = {\n names = [\"us-west-2a\", \"us-west-2b\", \"us-west-2c\"]\n }\n }\n}\n\nrun \"test_with_mocks\" {\n command = plan # Mocks only work with plan mode\n\n assert {\n condition = aws_instance.example.id == \"i-1234567890abcdef0\"\n error_message = \"Mock instance ID should match\"\n }\n}\n```\n\n## Aliased Mock Provider\n\n```hcl\nmock_provider \"aws\" {\n alias = \"mocked\"\n\n mock_resource \"aws_s3_bucket\" {\n defaults = {\n id = \"test-bucket-12345\"\n arn = \"arn:aws:s3:::test-bucket-12345\"\n }\n }\n}\n\nrun \"test_with_aliased_mock\" {\n command = plan\n\n providers = {\n aws = provider.aws.mocked\n }\n\n assert {\n condition = aws_s3_bucket.example.id == \"test-bucket-12345\"\n error_message = \"Bucket ID should match mock\"\n }\n}\n```\n\n## Common Mock Defaults\n\n```hcl\nmock_provider \"aws\" {\n mock_resource \"aws_instance\" {\n defaults = {\n id = \"i-1234567890abcdef0\"\n arn = \"arn:aws:ec2:us-west-2:123456789012:instance/i-1234567890abcdef0\"\n instance_type = \"t2.micro\"\n ami = \"ami-12345678\"\n availability_zone = \"us-west-2a\"\n subnet_id = \"subnet-12345678\"\n vpc_security_group_ids = [\"sg-12345678\"]\n associate_public_ip_address = true\n public_ip = \"203.0.113.1\"\n private_ip = \"10.0.1.100\"\n tags = {}\n }\n }\n\n mock_resource \"aws_vpc\" {\n defaults = {\n id = \"vpc-12345678\"\n arn = \"arn:aws:ec2:us-west-2:123456789012:vpc/vpc-12345678\"\n cidr_block = \"10.0.0.0/16\"\n enable_dns_hostnames = true\n enable_dns_support = true\n instance_tenancy = \"default\"\n tags = {}\n }\n }\n\n mock_resource \"aws_subnet\" {\n defaults = {\n id = \"subnet-12345678\"\n arn = \"arn:aws:ec2:us-west-2:123456789012:subnet/subnet-12345678\"\n vpc_id = \"vpc-12345678\"\n cidr_block = \"10.0.1.0/24\"\n availability_zone = \"us-west-2a\"\n map_public_ip_on_launch = false\n tags = {}\n }\n }\n\n mock_resource \"aws_s3_bucket\" {\n defaults = {\n id = \"test-bucket-12345\"\n arn = \"arn:aws:s3:::test-bucket-12345\"\n bucket = \"test-bucket-12345\"\n bucket_domain_name = \"test-bucket-12345.s3.amazonaws.com\"\n region = \"us-west-2\"\n tags = {}\n }\n }\n\n mock_data \"aws_ami\" {\n defaults = {\n id = \"ami-0c55b159cbfafe1f0\"\n name = \"ubuntu/images/hvm-ssd/ubuntu-focal-20.04-amd64-server-20210430\"\n architecture = \"x86_64\"\n root_device_type = \"ebs\"\n virtualization_type = \"hvm\"\n }\n }\n\n mock_data \"aws_availability_zones\" {\n defaults = {\n names = [\"us-west-2a\", \"us-west-2b\", \"us-west-2c\"]\n zone_ids = [\"usw2-az1\", \"usw2-az2\", \"usw2-az3\"]\n }\n }\n\n mock_data \"aws_vpc\" {\n defaults = {\n id = \"vpc-12345678\"\n cidr_block = \"10.0.0.0/16\"\n enable_dns_hostnames = true\n enable_dns_support = true\n }\n }\n}\n```\n\n## When to Use Mocks\n\n**Good fit:**\n- Testing Terraform logic, conditionals, `for_each`/`count` expressions\n- Validating variable transformations and output calculations\n- Local development without cloud credentials\n- Fast CI/CD feedback loops\n\n**Not a good fit:**\n- Validating actual provider API behavior\n- Testing real resource creation side effects\n- End-to-end integration testing\n\n## Limitations\n\n- **Plan mode only** ā mocks don't work with `command = apply`\n- Mock defaults may not reflect real computed attribute values\n- Mocks need manual updates when provider schemas change\n- Can't test real resource dependencies or timing\n"
},
{
"path": "terraform/module-generation/.claude-plugin/plugin.json",
"content": "{\n \"name\": \"terraform-module-generation\",\n \"version\": \"1.0.0\",\n \"description\": \"Terraform module generation and refactoring skills for Claude Code, including module design and Terraform Stacks.\",\n \"author\": {\n \"name\": \"HashiCorp\",\n \"url\": \"https://github.com/hashicorp\"\n },\n \"homepage\": \"https://developer.hashicorp.com/terraform/language/modules\",\n \"repository\": \"https://github.com/hashicorp/agent-skills\",\n \"license\": \"MPL-2.0\",\n \"keywords\": [\"terraform\", \"modules\", \"infrastructure\", \"iac\", \"stacks\", \"refactoring\"],\n \"mcpServers\": {\n \"terraform\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"-i\",\n \"--rm\",\n \"-e\", \"TFE_TOKEN\",\n \"-e\", \"TFE_ADDRESS\",\n \"hashicorp/terraform-mcp-server\"\n ],\n \"env\": {\n \"TFE_TOKEN\": \"${TFE_TOKEN}\",\n \"TFE_ADDRESS\": \"${TFE_ADDRESS}\"\n }\n }\n }\n}\n"
},
{
"path": "terraform/module-generation/skills/refactor-module/SKILL.md",
"content": "---\nname: refactor-module\ndescription: Transform monolithic Terraform configurations into reusable, maintainable modules following HashiCorp's module design principles and community best practices.\nmetadata:\n copyright: Copyright IBM Corp. 2026\n version: \"0.0.1\"\n---\n\n# Skill: Refactor Module\n\n## Overview\nThis skill guides AI agents in transforming monolithic Terraform configurations into reusable, maintainable modules following HashiCorp's module design principles and community best practices.\n\n## Capability Statement\nThe agent will analyze existing Terraform code and systematically refactor it into well-structured modules with:\n- Clear interface contracts (variables and outputs)\n- Proper encapsulation and abstraction\n- Versioning and documentation\n- Testing frameworks\n- Migration path for existing state\n\n## Prerequisites\n- Existing Terraform configuration to refactor\n- Understanding of resource dependencies\n- Access to current state file (for migration planning)\n- Knowledge of module registry patterns\n\n## Input Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `source_directory` | string | Yes | Path to existing Terraform configuration |\n| `module_name` | string | Yes | Name for the new module |\n| `abstraction_level` | string | No | \"simple\", \"intermediate\", \"advanced\" (default: intermediate) |\n| `preserve_state` | boolean | Yes | Whether to maintain state compatibility |\n| `target_registry` | string | No | Target module registry (local, private, public) |\n\n## Execution Steps\n\n### 1. Analysis Phase\n```markdown\n**Identify Refactoring Candidates**\n- Group resources by logical function\n- Identify repeated patterns\n- Map resource dependencies\n- Detect configuration coupling\n- Analyze variable usage patterns\n\n**Complexity Assessment**\n- Count resource relationships\n- Measure variable propagation depth\n- Identify cross-resource references\n- Evaluate state migration complexity\n```\n\n### 2. Module Design\n\n#### Interface Design\n```hcl\n# Define clear input contract\nvariable \"network_config\" {\n description = \"Network configuration parameters\"\n type = object({\n cidr_block = string\n availability_zones = list(string)\n enable_nat = bool\n })\n \n validation {\n condition = can(cidrhost(var.network_config.cidr_block, 0))\n error_message = \"CIDR block must be valid IPv4 CIDR.\"\n }\n}\n\n# Define output contract\noutput \"vpc_id\" {\n description = \"ID of the created VPC\"\n value = aws_vpc.main.id\n}\n\noutput \"private_subnet_ids\" {\n description = \"List of private subnet IDs\"\n value = { for k, v in aws_subnet.private : k => v.id }\n}\n```\n\n#### Encapsulation Strategy\n```markdown\n**What to Include in Module:**\n- Tightly coupled resources (VPC + subnets)\n- Resources with shared lifecycle\n- Configuration with clear boundaries\n\n**What to Keep Separate:**\n- Cross-cutting concerns (monitoring, tagging)\n- Resources with different lifecycles\n- Provider-specific configurations\n```\n\n### 3. Code Transformation\n\n#### Before: Monolithic Configuration\n```hcl\n# main.tf (monolithic)\nresource \"aws_vpc\" \"main\" {\n cidr_block = \"10.0.0.0/16\"\n enable_dns_hostnames = true\n \n tags = {\n Name = \"production-vpc\"\n Environment = \"prod\"\n }\n}\n\nresource \"aws_subnet\" \"public_1\" {\n vpc_id = aws_vpc.main.id\n cidr_block = \"10.0.1.0/24\"\n availability_zone = \"us-east-1a\"\n \n tags = {\n Name = \"public-subnet-1\"\n Type = \"public\"\n }\n}\n\nresource \"aws_subnet\" \"public_2\" {\n vpc_id = aws_vpc.main.id\n cidr_block = \"10.0.2.0/24\"\n availability_zone = \"us-east-1b\"\n \n tags = {\n Name = \"public-subnet-2\"\n Type = \"public\"\n }\n}\n\nresource \"aws_internet_gateway\" \"main\" {\n vpc_id = aws_vpc.main.id\n \n tags = {\n Name = \"production-igw\"\n }\n}\n\n# ... more repetitive subnet and routing resources\n```\n\n#### After: Modular Structure\n```hcl\n# modules/vpc/main.tf\nlocals {\n subnet_count = length(var.availability_zones)\n}\n\nresource \"aws_vpc\" \"main\" {\n cidr_block = var.cidr_block\n enable_dns_hostnames = var.enable_dns_hostnames\n enable_dns_support = var.enable_dns_support\n \n tags = merge(\n var.tags,\n {\n Name = var.name\n }\n )\n}\n\nresource \"aws_subnet\" \"public\" {\n for_each = var.create_public_subnets ? toset(var.availability_zones) : []\n \n vpc_id = aws_vpc.main.id\n cidr_block = cidrsubnet(var.cidr_block, 8, index(var.availability_zones, each.value))\n availability_zone = each.value\n map_public_ip_on_launch = true\n \n tags = merge(\n var.tags,\n {\n Name = \"${var.name}-public-${each.value}\"\n Type = \"public\"\n }\n )\n}\n\nresource \"aws_internet_gateway\" \"main\" {\n count = var.create_public_subnets ? 1 : 0\n vpc_id = aws_vpc.main.id\n \n tags = merge(\n var.tags,\n {\n Name = \"${var.name}-igw\"\n }\n )\n}\n\n# modules/vpc/variables.tf\nvariable \"name\" {\n description = \"Name prefix for all resources\"\n type = string\n}\n\nvariable \"cidr_block\" {\n description = \"CIDR block for the VPC\"\n type = string\n \n validation {\n condition = can(cidrhost(var.cidr_block, 0))\n error_message = \"Must be a valid IPv4 CIDR block.\"\n }\n}\n\nvariable \"availability_zones\" {\n description = \"List of availability zones\"\n type = list(string)\n}\n\nvariable \"create_public_subnets\" {\n description = \"Whether to create public subnets\"\n type = bool\n default = true\n}\n\nvariable \"enable_dns_hostnames\" {\n description = \"Enable DNS hostnames in the VPC\"\n type = bool\n default = true\n}\n\nvariable \"enable_dns_support\" {\n description = \"Enable DNS support in the VPC\"\n type = bool\n default = true\n}\n\nvariable \"tags\" {\n description = \"Tags to apply to all resources\"\n type = map(string)\n default = {}\n}\n\n# modules/vpc/outputs.tf\noutput \"vpc_id\" {\n description = \"ID of the VPC\"\n value = aws_vpc.main.id\n}\n\noutput \"vpc_cidr_block\" {\n description = \"CIDR block of the VPC\"\n value = aws_vpc.main.cidr_block\n}\n\noutput \"public_subnet_ids\" {\n description = \"Map of availability zones to public subnet IDs\"\n value = { for k, v in aws_subnet.public : k => v.id }\n}\n\noutput \"internet_gateway_id\" {\n description = \"ID of the internet gateway\"\n value = try(aws_internet_gateway.main[0].id, null)\n}\n\n# Root configuration using module\nmodule \"vpc\" {\n source = \"./modules/vpc\"\n \n name = \"production\"\n cidr_block = \"10.0.0.0/16\"\n availability_zones = [\"us-east-1a\", \"us-east-1b\", \"us-east-1c\"]\n \n tags = {\n Environment = \"production\"\n ManagedBy = \"Terraform\"\n }\n}\n```\n\n### 4. State Migration\n\n#### Generate Migration Plan\n```hcl\n# migration.tf\n# Use moved blocks for state refactoring (Terraform 1.1+)\n\nmoved {\n from = aws_vpc.main\n to = module.vpc.aws_vpc.main\n}\n\nmoved {\n from = aws_subnet.public_1\n to = module.vpc.aws_subnet.public[\"us-east-1a\"]\n}\n\nmoved {\n from = aws_subnet.public_2\n to = module.vpc.aws_subnet.public[\"us-east-1b\"]\n}\n\nmoved {\n from = aws_internet_gateway.main\n to = module.vpc.aws_internet_gateway.main[0]\n}\n```\n\n#### Manual State Migration (Pre-1.1)\n```bash\n# Generate state migration commands\nterraform state mv aws_vpc.main module.vpc.aws_vpc.main\nterraform state mv aws_subnet.public_1 'module.vpc.aws_subnet.public[\"us-east-1a\"]'\nterraform state mv aws_subnet.public_2 'module.vpc.aws_subnet.public[\"us-east-1b\"]'\nterraform state mv aws_internet_gateway.main 'module.vpc.aws_internet_gateway.main[0]'\n```\n\n### 5. Module Documentation\n\n```markdown\n# VPC Module\n\n## Overview\nCreates a VPC with configurable public and private subnets across multiple availability zones.\n\n## Features\n- Multi-AZ subnet deployment\n- Optional NAT gateway configuration\n- VPC Flow Logs integration\n- Customizable CIDR allocation\n\n## Usage\n\n\\`\\`\\`hcl\nmodule \"vpc\" {\n source = \"./modules/vpc\"\n \n name = \"my-vpc\"\n cidr_block = \"10.0.0.0/16\"\n availability_zones = [\"us-east-1a\", \"us-east-1b\"]\n \n create_public_subnets = true\n create_private_subnets = true\n enable_nat_gateway = true\n \n tags = {\n Environment = \"production\"\n }\n}\n\\`\\`\\`\n\n## Requirements\n\n| Name | Version |\n|------|---------|\n| terraform | >= 1.5.0 |\n| aws | ~> 5.0 |\n\n## Inputs\n\n| Name | Description | Type | Default | Required |\n|------|-------------|------|---------|----------|\n| name | Name prefix for resources | `string` | n/a | yes |\n| cidr_block | VPC CIDR block | `string` | n/a | yes |\n| availability_zones | List of AZs | `list(string)` | n/a | yes |\n\n## Outputs\n\n| Name | Description |\n|------|-------------|\n| vpc_id | VPC identifier |\n| public_subnet_ids | Map of public subnet IDs |\n| private_subnet_ids | Map of private subnet IDs |\n\n## Examples\n\nSee [examples/](./examples/) directory for complete usage examples.\n```\n\n### 6. Testing\n\nUse skill terraform-test\n\n**Test File**: A `.tftest.hcl` or `.tftest.json` file containing test configuration and run blocks that validate your Terraform configuration.\n\n**Test Block**: Optional configuration block that defines test-wide settings (available since Terraform 1.6.0).\n\n**Run Block**: Defines a single test scenario with optional variables, provider configurations, and assertions. Each test file requires at least one run block.\n\n**Assert Block**: Contains conditions that must evaluate to true for the test to pass. Failed assertions cause the test to fail.\n\n**Mock Provider**: Simulates provider behavior without creating real infrastructure (available since Terraform 1.7.0).\n\n**Test Modes**: Tests run in apply mode (default, creates real infrastructure) or plan mode (validates logic without creating resources).\n\n#### File Structure\n\nTerraform test files use the `.tftest.hcl` or `.tftest.json` extension and are typically organized in a `tests/` directory. Use clear naming conventions to distinguish between unit tests (plan mode) and integration tests (apply mode):\n\n```\nmy-module/\nāāā main.tf\nāāā variables.tf\nāāā outputs.tf\nāāā tests/\n āāā unit_test.tftest.hcl # Unit test (plan mode)\n āāā integration_test.tftest.hcl # Integration test (apply mode - creates real resources)\n```\n\n## Refactoring Patterns\n\n### Pattern 1: Resource Grouping\nExtract related resources into cohesive modules:\n- Networking (VPC, Subnets, Route Tables)\n- Compute (ASG, Launch Templates, Load Balancers)\n- Data (RDS, ElastiCache, S3)\n\n### Pattern 2: Configuration Layering\n```hcl\n# Base module with defaults\nmodule \"vpc_base\" {\n source = \"./modules/vpc-base\"\n # Minimal required inputs\n}\n\n# Environment-specific wrapper\nmodule \"vpc_prod\" {\n source = \"./modules/vpc-production\"\n # Inherits from base, adds prod-specific config\n}\n```\n\n### Pattern 3: Composition\n```hcl\n# Small, focused modules\nmodule \"vpc\" {\n source = \"./modules/vpc\"\n}\n\nmodule \"security_groups\" {\n source = \"./modules/security-groups\"\n vpc_id = module.vpc.vpc_id\n}\n\nmodule \"application\" {\n source = \"./modules/application\"\n vpc_id = module.vpc.vpc_id\n subnet_ids = module.vpc.private_subnet_ids\n sg_ids = module.security_groups.app_sg_ids\n}\n```\n\n## Common Pitfalls\n\n### 1. Over-Abstraction\n```hcl\n# ā Don't create overly generic modules\nvariable \"resources\" {\n type = map(map(any)) # Too flexible, hard to validate\n}\n\n# ā Do use specific, typed interfaces\nvariable \"database_config\" {\n type = object({\n engine = string\n instance_class = string\n })\n}\n```\n\n### 2. Tight Coupling\n```hcl\n# ā Don't couple modules through direct references\n# module A\noutput \"instance_id\" { value = aws_instance.app.id }\n\n# module B (in same config)\nresource \"aws_eip\" \"app\" {\n instance = module.a.instance_id # Tight coupling\n}\n\n# ā Do pass dependencies through root module\nmodule \"compute\" {\n source = \"./modules/compute\"\n}\n\nresource \"aws_eip\" \"app\" {\n instance = module.compute.instance_id\n}\n```\n\n### 3. State Migration Errors\nAlways test migration in non-production first:\n```bash\n# Create plan to verify no changes after migration\nterraform plan -out=migration.tfplan\n\n# Review carefully\nterraform show migration.tfplan\n\n# Apply only if plan shows no changes\nterraform apply migration.tfplan\n```\n\n## Version Control Strategy\n\n```hcl\n# Use semantic versioning for modules\nmodule \"vpc\" {\n source = \"git::https://github.com/org/terraform-modules.git//vpc?ref=v1.2.0\"\n version = \"~> 1.2\"\n}\n\n# Pin to specific versions in production\n# Use version ranges in development\n```\n\n## Success Criteria\n\n- [ ] Module has single, well-defined responsibility\n- [ ] All variables have descriptions and types\n- [ ] Validation rules prevent invalid configurations\n- [ ] Outputs provide sufficient information for consumers\n- [ ] Documentation includes usage examples\n- [ ] Tests verify module behavior\n- [ ] State migration completed without resource recreation\n- [ ] No plan differences after refactoring\n\n## Related Skills\n- [Terraform code generation](https://raw.githubusercontent.com/hashicorp/agent-skills/refs/heads/main/terraform/code-generation/skills/terraform-style-guide/SKILL.md) - Style guide for the new Terraform Module\n- [Azure Verified Modules](https://raw.githubusercontent.com/hashicorp/agent-skills/refs/heads/main/terraform/code-generation/skills/azure-verified-modules/SKILL.md) - Recommended module specifications for Azure\n\n## Resources\n- [Terraform Module Development](https://developer.hashicorp.com/terraform/language/modules/develop)\n- [Module Best Practices](https://developer.hashicorp.com/terraform/cloud-docs/registry/design)\n\n## Revision History\n\n| Version | Date | Changes |\n|---------|------|---------|\n| 1.0.0 | 2025-11-07 | Initial skill definition |\n"
},
{
"path": "terraform/module-generation/skills/terraform-stacks/SKILL.md",
"content": "---\nname: terraform-stacks\ndescription: Comprehensive guide for working with HashiCorp Terraform Stacks. Use when creating, modifying, or validating Terraform Stack configurations (.tfcomponent.hcl, .tfdeploy.hcl files), working with stack components and deployments from local modules, public registry, or private registry sources, managing multi-region or multi-environment infrastructure, or troubleshooting Terraform Stacks syntax and structure.\nmetadata:\n copyright: Copyright IBM Corp. 2026\n version: \"0.0.1\"\n---\n\n# Terraform Stacks\n\nTerraform Stacks simplify infrastructure provisioning and management at scale by providing a configuration layer above traditional Terraform modules. Stacks enable declarative orchestration of multiple components across environments, regions, and cloud accounts.\n\n## Core Concepts\n\n**Stack**: A complete unit of infrastructure composed of components and deployments that can be managed together.\n\n**Component**: An abstraction around a Terraform module that defines infrastructure pieces. Each component specifies a source module, inputs, and providers.\n\n**Deployment**: An instance of all components in a stack with specific input values. Use deployments for different environments (dev/staging/prod), regions, or cloud accounts.\n\n**Stack Language**: A separate HCL-based language (not regular Terraform HCL) with distinct blocks and file extensions.\n\n## File Structure\n\nTerraform Stacks use specific file extensions:\n\n- **Component configuration**: `.tfcomponent.hcl`\n- **Deployment configuration**: `.tfdeploy.hcl`\n- **Provider lock file**: `.terraform.lock.hcl` (generated by CLI)\n\nAll configuration files must be at the root level of the Stack repository. HCP Terraform processes all files in dependency order.\n\n### Recommended File Organization\n\n```\nmy-stack/\nāāā .terraform-version # The required Terraform version for this Stack\nāāā variables.tfcomponent.hcl # Variable declarations\nāāā providers.tfcomponent.hcl # Provider configurations\nāāā components.tfcomponent.hcl # Component definitions\nāāā outputs.tfcomponent.hcl # Stack outputs\nāāā deployments.tfdeploy.hcl # Deployment definitions\nāāā .terraform.lock.hcl # Provider lock file (generated)\nāāā modules/ # Local modules (optional - only if using local modules)\n āāā s3/\n āāā compute/\n```\n\n**Note**: The `modules/` directory is only required when using local module sources. Components can reference modules from:\n- Local file paths: `./modules/vpc`\n- Public registry: `terraform-aws-modules/vpc/aws`\n- Private registry: `app.terraform.io//vpc/aws`\n- Git: `git::https://github.com/org/repo.git//path?ref=v1.0.0`\n\nHCP Terraform processes all `.tfcomponent.hcl` and `.tfdeploy.hcl` files in dependency order.\n\n## Required Terraform version (.terraform-version)\n\nUse Terraform v1.13.x or later to access the Stacks CLI plugin and to run\nterraform stacks CLI commands. Begin by adding a .terraform-version file to\nyour Stack's root directory to specify the Terraform version required for your\nStack. For example, the following file specifies Terraform v1.14.5:\n\n```\n1.14.5\n```\n\n## Component Configuration (.tfcomponent.hcl)\n\n### Variable Block\n\nDeclare input variables for the Stack configuration. Variables must define a `type` field and do not support the `validation` argument.\n\n```hcl\nvariable \"aws_region\" {\n type = string\n description = \"AWS region for deployments\"\n default = \"us-west-1\"\n}\n\nvariable \"identity_token\" {\n type = string\n description = \"OIDC identity token\"\n ephemeral = true # Does not persist to state file\n}\n\nvariable \"instance_count\" {\n type = number\n nullable = false\n}\n```\n\n**Important**: Use `ephemeral = true` for credentials and tokens (identity tokens, API keys, passwords) to prevent them from persisting in state files. Use `stable` for longer-lived values like license keys that need to persist across runs.\n\n### Required Providers Block\n\n```hcl\nrequired_providers {\n aws = {\n source = \"hashicorp/aws\"\n version = \"~> 6.0\"\n }\n random = {\n source = \"hashicorp/random\"\n version = \"~> 3.5.0\"\n }\n}\n```\n\n### Provider Block\n\nProvider blocks differ from traditional Terraform:\n\n1. Support `for_each` meta-argument\n2. Define aliases in the block header (not as an argument)\n3. Accept configuration through a `config` block\n\n**Single Provider Configuration:**\n\n```hcl\nprovider \"aws\" \"this\" {\n config {\n region = var.aws_region\n assume_role_with_web_identity {\n role_arn = var.role_arn\n web_identity_token = var.identity_token\n }\n }\n}\n```\n\n**Multiple Provider Configurations with for_each:**\n\n```hcl\nprovider \"aws\" \"configurations\" {\n for_each = var.regions\n\n config {\n region = each.value\n assume_role_with_web_identity {\n role_arn = var.role_arn\n web_identity_token = var.identity_token\n }\n }\n}\n```\n\n**Authentication Best Practice**: Use **workload identity** (OIDC) as the preferred authentication method for Stacks. This approach:\n- Avoids long-lived static credentials\n- Provides temporary, scoped credentials per deployment run\n- Integrates with cloud provider IAM (AWS IAM Roles, Azure Managed Identities, GCP Service Accounts)\n- Eliminates need for platform-managed environment variables\n\nConfigure workload identity using `identity_token` blocks and `assume_role_with_web_identity` in provider configuration. For detailed setup instructions for AWS, Azure, and GCP, see: https://developer.hashicorp.com/terraform/cloud-docs/dynamic-provider-credentials\n\n### Component Block\n\nEach Stack requires at least one component block. Add a component for each module to include in the Stack. Components reference modules from local paths, registries, or Git.\n\n```hcl\ncomponent \"vpc\" {\n source = \"app.terraform.io/my-org/vpc/aws\" # Local, registry, or Git URL\n version = \"2.1.0\" # For registry modules\n\n inputs = {\n cidr_block = var.vpc_cidr\n name_prefix = var.name_prefix\n }\n\n providers = {\n aws = provider.aws.this\n }\n}\n```\n\nSee `references/component-blocks.md` for examples of dependencies, for_each, public registry modules, Git sources, and more.\n\n**Key Points:**\n- Reference outputs: `component..