ansible-generator

What this skill does

# Ansible Generator

## Trigger Phrases

Use this skill when the request is to generate or scaffold Ansible content, for example:

- "Create a playbook to deploy nginx with TLS."
- "Generate an Ansible role for PostgreSQL backups."
- "Write inventory files for prod and staging."
- "Build reusable Ansible tasks for user provisioning."
- "Initialize an Ansible project with ansible.cfg and requirements.yml."
- "Give me a quick Ansible snippet to install Docker."

Do not use this skill as the primary workflow when the request is validation/debug-only (syntax errors, lint failures, Molecule/test failures). Use `ansible-validator` for those cases.

## Deterministic Execution Flow

Run these stages in order. Do not skip a stage unless the `Validation Exceptions Matrix` explicitly allows it.

### Stage 0: Classify Request Mode

Determine one mode first:

| Mode | Typical user intent | Deliverable |
| --- | --- | --- |
| `full-generation` | "create/build/generate" a full playbook/role/inventory/project file set | Complete file(s), production-ready |
| `snippet-only` | "quick snippet/example" without full file context | Focused task/play snippet |
| `docs-only` | explanation, pattern comparison, or conceptual guidance only | Explanatory content, optional examples |

### Stage 1: Collect Minimum Inputs

If details are missing, ask briefly. If the user does not provide them, proceed with safe defaults and state assumptions.

| Resource type | Required inputs | Safe defaults if missing |
| --- | --- | --- |
| Playbook | target hosts, privilege (`become`), OS family, objective | `hosts: all`, `become: false`, OS-agnostic modules |
| Role | role name, primary service/package, supported OS | role name from task domain, Debian + RedHat vars |
| Tasks file | operation scope, required vars, execution context | standalone reusable tasks with documented vars |
| Inventory | environments, host groups, hostnames/IPs | `production`/`staging` groups with placeholders |
| Project config | collections/roles dependencies, lint policy | minimal `ansible.cfg`, `requirements.yml`, `.ansible-lint` |

### Stage 2: Reference Extraction Checklist

Before drafting content, extract the following from local references/templates.

#### Required references

- `references/best-practices.md`
  - Extract: FQCN requirements, idempotency rules, naming, security expectations.
- `references/module-patterns.md`
  - Extract: correct module/parameter patterns for the exact task type.

#### Required templates by output type

- Playbook: `assets/templates/playbook/basic_playbook.yml`
- Role: `assets/templates/role/` (including `meta/argument_specs.yml` and `molecule/default/` for test scaffolding)
- Inventory (INI): `assets/templates/inventory/hosts`
- Inventory (YAML): `assets/templates/inventory/hosts.yml`
- Project config: `assets/templates/project/ansible.cfg`, `assets/templates/project/requirements.yml`, `assets/templates/project/.ansible-lint`

#### Extraction checks

- Identify every `[PLACEHOLDER]` that must be replaced.
- Decide module selection priority (`ansible.builtin.*` first).
- Capture at least one OS-appropriate package pattern when OS-specific behavior is needed.
- Capture required prerequisites (collections, binaries, target assumptions).

### Stage 3: Generate

Apply these generation standards:

1. Use FQCN module names (`ansible.builtin.*` first choice).
2. Keep tasks idempotent (`state`, `creates/removes`, `changed_when` when needed).
3. Use descriptive verb-first task names.
4. Use `true`/`false` booleans (not `yes`/`no`).
5. Add `no_log: true` for sensitive values.
6. Replace all placeholders before presenting output.
7. Prefer `ansible.builtin.dnf` for RHEL 8+/CentOS 8+ (legacy `yum` only for older systems).

### Stage 4: Validate (Default) or Apply Exception (Fallback)

Use the matrix below to keep validation deterministic and non-blocking.

## Validation Exceptions Matrix

| Scenario | Default behavior | Allowed fallback | What to report |
| --- | --- | --- | --- |
| `full-generation` | Run `ansible-validator` after generation and after each fix pass | If validator/tools are unavailable, run manual static checks (YAML shape, placeholder scan, FQCN/idempotency/security review) and provide exact deferred validation commands | Explicitly list which checks ran, which were skipped, and why |
| `snippet-only` | Skip full validator by default; do inline sanity checks | Run full validator only if user asks or snippet is promoted to full file | State that validation was limited because output is snippet-only |
| `docs-only` | No runtime validation | None needed | State that no executable artifact was generated |
| Offline environment (no web/docs access) | Continue with local references and templates | Skip external doc lookups; prefer builtin-module implementations; provide notes for later external verification | State offline constraint and impacted checks/lookups |

## Resource Generation Guidance

### Playbooks

- Use `assets/templates/playbook/basic_playbook.yml` as structure.
- Include: header comments, `pre_tasks`/`tasks`/`post_tasks` as needed, handlers, tags.
- Add health checks when service deployment/configuration is involved.

### Roles

- Build from `assets/templates/role/` structure.
- Keep defaults in `defaults/main.yml`; keep higher-priority role vars in `vars/main.yml`.
- Include OS-specific vars (`vars/Debian.yml`, `vars/RedHat.yml`) when relevant.
- Add `meta/argument_specs.yml` for variable validation.
- Include `molecule/default/` scaffold (from `assets/templates/role/molecule/`) for production-ready roles.

### Task Files

- Keep scope narrow and reusable.
- Document required input variables in comments.
- Use conditionals for environment/OS-sensitive operations.

### Inventory

- Build logical host groups and optional group hierarchies.
- Use variable layering intentionally: `group_vars/all.yml` -> group -> host.
- Default to INI format (`hosts`) for simple topologies; use YAML format (`hosts.yml`) when the user requests it or when the hierarchy is complex.

### Project Configuration

- Provide baseline `ansible.cfg`, `requirements.yml`, and `.ansible-lint`.
- Keep defaults practical and editable.

## Custom Modules and Collections

When the request depends on non-builtin modules/collections:

1. Identify collection + module and required version sensitivity.
2. Check local `references/module-patterns.md` first.
3. If still unresolved and network/tools are available, query Context7:
   - `mcp__context7__resolve-library-id`
   - `mcp__context7__query-docs`
4. If Context7 is unavailable, use official Ansible docs / Ansible Galaxy pages.
5. If external lookup is unavailable, provide a builtin fallback approach and state the limitation.

Always include collection installation guidance when collection modules are used.

## Canonical Example Flows

### Flow A: Full Generation (Playbook)

User prompt: "Create a playbook to deploy nginx with TLS on Ubuntu and RHEL."

1. Classify as `full-generation`.
2. Gather/confirm required inputs (hosts, cert paths, become, service name).
3. Extract required references (`best-practices.md`, `module-patterns.md`) and playbook template.
4. Generate complete playbook with OS conditionals (`apt`/`dnf`), handlers, validation for config templates.
5. Run `ansible-validator`.
6. Fix issues and rerun until checks pass (or apply matrix fallback if tooling unavailable).
7. Present output with validation summary, usage command, and prerequisites.

### Flow B: Quick Snippet (Task Block)

User prompt: "Give me a snippet to create a user and SSH key."

1. Classify as `snippet-only`.
2. Extract minimal module patterns for `ansible.builtin.user` and `ansible.builtin.authorized_key`.
3. Generate concise snippet with FQCN, idempotency, and variable placeholders.
4. Perform inline sanity checks (YAML shape, FQCN, obvious idempotency/security).
5. Present snippet and note that full validator run was skipped due to snippet-only mode.

## Output Requi