| name | ansible-designer |
| description | AI-assisted Ansible authoring toolkit for Claude Code. Scaffolds, reviews, and updates playbooks, roles, collections, and ansible.cfg files following production best practices. Sub-commands: new-playbook, review-playbook, update-playbook, new-role, review-role, update-role, new-collection, review-collection, update-collection, new-conf, review-conf, update-conf. Runs discovery (CLAUDE.md to ansible.cfg to README to filesystem) at the start of every command. |
ansible-designer
AI-assisted Ansible authoring toolkit. Scaffolds, reviews, and updates Ansible projects with production-quality output following official ansible-core 2.15+ conventions.
Available Commands
All commands are top-level regardless of install path.
Playbook Commands
| Command | Description |
|---|
/new-playbook | Create a new playbook (site, component, or AWX-ready) |
/review-playbook | Review an existing playbook — severity report, no file modification |
/update-playbook | Update a playbook — shows diff, requires confirmation |
Role Commands
| Command | Description |
|---|
/new-role | Scaffold a complete role — asks about multi-OS support |
/review-role | Review a role — severity report, no file modification |
/update-role | Update a role — shows diff, requires confirmation |
Collection Commands
| Command | Description |
|---|
/new-collection | Scaffold a new collection with galaxy.yml, plugins, roles structure |
/review-collection | Review a collection — severity report, no file modification |
/update-collection | Update a collection — shows diff, requires confirmation |
ansible.cfg Commands
| Command | Description |
|---|
/new-conf | Generate an annotated ansible.cfg for dev, CI, or AWX |
/review-conf | Review an ansible.cfg — severity report, no file modification |
/update-conf | Update ansible.cfg — shows diff, requires confirmation |
Global Rules
Every sub-command enforces these rules without exception:
-
Discovery first — At command start, read in order: CLAUDE.md → ansible.cfg → README.md → filesystem scan. Build internal context (roles, collections, paths, namespace). Skip if user already provided all required parameters inline. See references/discovery.md.
-
Never overwrite silently — Before writing any file, show a summary (new files) or unified diff (modifications). Wait for explicit user confirmation (yes / y). Only write after confirmation.
-
FQCN mandatory — Every module reference uses the Fully Qualified Collection Name. ansible.builtin.copy, never copy. ansible.builtin.service, never service. See references/best_practices.md.
-
no_log: true on secrets — Every task handling passwords, tokens, API keys, vault variables, or credentials must include no_log: true. See references/security_vault.md.
-
Tags on every task — Minimum: component name + action category (install, configure, service, validate, security, cleanup). No task may be untagged.
-
review never modifies — review-* commands produce a structured severity report (CRITICAL / WARNING / INFO) only. They never write, modify, or suggest sed commands. Report only.
-
update always diffs — update-* commands read the existing file, compute the change, show a unified diff, and wait for explicit confirmation before writing a single byte.
-
Show file tree after writes — After any write operation, list all created or modified files and display the resulting file tree.
-
Testing-aware output — New or updated examples must include a realistic validation path. See references/testing.md.
-
Suggest next step — End every command with a concrete suggestion: which command to run next, or what to validate.
Standard Operational Flow
Every command follows this exact sequence:
Step 1 — Discovery
Read: CLAUDE.md → ansible.cfg → README.md → filesystem scan
Build: internal context (roles_path, collections_path, existing roles, collections, inventory)
Report: "Discovery complete: [summary of what was found]"
Skip Step 1 only if the user provided all required parameters inline.
Step 2 — Parameter Collection
- If the user already provided all required parameters: proceed to Step 3.
- Otherwise: ask one question at a time, using discovery context for smart defaults.
- Never ask for something that can be inferred from discovery (e.g., don't ask for namespace if a collection already exists).
Step 3 — Pre-Write Confirmation
- For new files: show a summary of what will be created (paths + brief description).
- For update commands: show a unified diff (
--- original, +++ proposed).
- Wait for explicit user confirmation (
yes, y, or equivalent) before proceeding.
- If user says no: ask what to change and loop back to Step 2.
Step 4 — Execution
- Write or modify files using bash commands.
- Follow all global rules: FQCN, tags, no_log.
- Use templates from the appropriate
references/ file as the base.
Step 5 — Final Output
Show file tree of all created/modified files.
Suggest: "Next step: [specific actionable suggestion]"
Reference Files
| File | Used by |
|---|
references/discovery.md | All commands — Step 1 |
references/best_practices.md | All commands — FQCN, tags, no_log, idempotency |
references/playbook.md | new-playbook, review-playbook, update-playbook |
references/role.md | new-role, review-role, update-role |
references/collection.md | new-collection, review-collection, update-collection |
references/ansible_cfg.md | new-conf, review-conf, update-conf |
references/inventory.md | All commands — inventory context |
references/testing.md | All commands — validation and example test guidance |
references/security_vault.md | All commands — secret handling and vault-safe patterns |
references/plugins.md | Collection commands — module/filter/lookup guidance |
Installation
Install via the Claude Code marketplace from 3A2DEV/ansible-designer. This preserves the ansible-designer: namespace prefix for all sub-commands.
Requires Claude Code.
