ansible-designer

!GitHub License !Claude Code !Ansible Designer !Ansible Core !GitHub Actions Workflow Status

 ▐▛███▜▌   Claude Code
▝▜█████▛▘  Sonnet 4.6 · Claude
  ▘▘ ▝▝    ansible-designer/
  ⎿  SessionStart:startup says: [ansible-designer 0.1.7]
     ──────────────────────────────────────────────────────────

 █████╗ ███╗   ██╗███████╗██╗██████╗ ██╗     ███████╗         
██╔══██╗████╗  ██║██╔════╝██║██╔══██╗██║     ██╔════╝         
███████║██╔██╗ ██║███████╗██║██████╔╝██║     █████╗           
██╔══██║██║╚██╗██║╚════██║██║██╔══██╗██║     ██╔══╝           
██║  ██║██║ ╚████║███████║██║██████╔╝███████╗███████╗         
╚═╝  ╚═╝╚═╝  ╚═══╝╚══════╝╚═╝╚═════╝ ╚══════╝╚══════╝         
                                                              
██████╗ ███████╗███████╗██╗ ██████╗ ███╗   ██╗███████╗██████╗ 
██╔══██╗██╔════╝██╔════╝██║██╔════╝ ████╗  ██║██╔════╝██╔══██╗
██║  ██║█████╗  ███████╗██║██║  ███╗██╔██╗ ██║█████╗  ██████╔╝
██║  ██║██╔══╝  ╚════██║██║██║   ██║██║╚██╗██║██╔══╝  ██╔══██╗
██████╔╝███████╗███████║██║╚██████╔╝██║ ╚████║███████╗██║  ██║
╚═════╝ ╚══════╝╚══════╝╚═╝ ╚═════╝ ╚═╝  ╚═══╝╚══════╝╚═╝  ╚═╝

───────────────────────────────────────────────────────────────
❯ /ansible-designer
───────────────────────────────────────────────────────────────

AI-assisted Ansible authoring toolkit for Claude Code. Scaffolds, reviews, and updates playbooks, roles, collections, and ansible.cfg files following ansible-core 2.15+ conventions and production best practices.

---

Installation

Option A — Claude Code plugin system (recommended)

Using Claude Code:

/plugin marketplace add 3A2DEV/ansible-designer

/plugin install ansible-designer

Option B — npx skills CLI

npx skills add 3A2DEV/ansible-designer --skill '*'

Both options register each skill as a top-level command (e.g. /new-playbook, /review-role).

Requirements:

• Claude Code
• No additional dependencies — all Ansible knowledge is embedded in the skill

---

Available Commands

| Command | Description | |---------|-------------| | /ansible-designer | Show this overview and available commands | | Playbooks | | | /new-playbook | Create a new playbook (site, component, or AWX-ready) | | /review-playbook | Review a playbook — severity report, no file modification | | /update-playbook | Update a playbook — diff + confirm before writing | | Roles | | | /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 — diff + confirm before writing | | Collections | | | /new-collection | Scaffold a new collection with galaxy.yml, plugins, roles | | /review-collection | Review a collection — severity report, no file modification | | /update-collection | Update a collection — diff + confirm before writing | | ansible.cfg | | | /new-conf | Generate annotated ansible.cfg for dev, CI, or AWX | | /review-conf | Review ansible.cfg — severity report, no file modification | | /update-conf | Update ansible.cfg — diff + confirm before writing |

---

How Discovery Works

Every command begins by scanning the project for context:

CLAUDE.md → ansible.cfg → README.md → filesystem scan

Discovery extracts:

• roles_path — where roles live
• collections_paths — where collections live
• Existing roles and collections (for FQCN suggestions)
• Inventory location
• Vault configuration
• Namespace hints

This context is used to suggest smart defaults, resolve FQCNs, and skip questions the user doesn't need to answer.

---

Global Rules

Every command enforces these rules:

1. FQCN everywhere — ansible.builtin.copy, never copy 2. Tags on every task — component name + action category (install, configure, service, validate) 3. no_log: true on secrets — mandatory on tasks handling passwords, tokens, vault variables 4. Never overwrite silently — every write shows a summary or diff first, then waits for confirmation 5. review never modifies — review commands produce reports only 6. update always diffs — update commands show unified diffs before writing 7. File tree after writes — every write operation ends with a file tree 8. Testing-aware output — generated examples and updates include a realistic validation path 9. Next step suggestion — every command ends with a concrete next action

---

Example Usage

Create a new role for nginx with RHEL + Solaris support

/new-role

> Role name: nginx
> Location: ./roles/
> Multi-OS support: yes

→ Generates roles/nginx/ with 12 files including OS-specific task and var files

Review an existing playbook

/review-playbook deploy-app.yml

## Playbook Review: deploy-app.yml

### CRITICAL
- [tasks:line 15] Task "Restart service" uses bare module name 'service' — must use FQCN 'ansible.builtin.service'

### WARNING
- [tasks:line 22] Task "Run migration" uses shell without idempotency guard

### INFO
- Playbook is missing a documentation header

Generate an AWX-optimized ansible.cfg

/new-conf

> Environment: awx

→ Generates ./ansible.cfg with Redis fact caching, AWX callback configuration,
  strict SSH settings, and annotated vault identity list

Update ansible.cfg with credential-safe diff display

/update-conf

> Change: enable fact caching with redis

⚠ Warning: 1 line(s) with credential-like values were redacted from this display.
  Review the file directly before applying changes.

--- ansible.cfg (original)
+++ ansible.cfg (proposed)
@@ -8,6 +8,10 @@
 forks                 = 10
 timeout               = 30
+
+# Fact caching: redis (shared across controller nodes; configure auth via REDIS_URL or vault)
+fact_caching          = redis
+fact_caching_connection = redis://:{{ vault_redis_password }}@cache.internal:6379/0
+fact_caching_timeout  = 86400

Apply this change? (yes/no)

Scaffold a new collection with input validation

/new-collection

> collection_path: ./collections/ansible_collections/
> namespace: myorg
> collection_name: security_baseline
> description: Baseline security hardening collection for RHEL targets
> author: ops-team <ops@example.com>

Will create: ./collections/ansible_collections/myorg/security_baseline/ (13 files)

  galaxy.yml            — namespace: myorg, name: security_baseline, version: 0.1.0
  README.md             — collection overview
  CHANGELOG.md          — v0.1.0 initial
  LICENSE               — Apache 2.0
  meta/runtime.yml      — requires_ansible: >=2.15.0
  plugins/modules/get_info.py
  plugins/filter/string_filters.py
  plugins/lookup/config_value.py
  roles/.gitkeep
  tests/integration/.gitkeep
  tests/unit/.gitkeep

Proceed? (yes/no)

---

Examples

See the examples/ directory for working Ansible projects:

| Example | Description | |---------|-------------| | simple-playbook/ | Complete site playbook with inventory, group_vars, and bundled example roles | | role-rhel/ | Full nginx role targeting RHEL 8/9 | | role-multiplatform/ | NTP role for RHEL + Solaris + Windows | | local-collection/ | Complete local collection with module, filter, and lookup plugins | | ansible-cfg-profiles/ | Development, CI, and controller-oriented ansible.cfg profiles | | inventory-vault/ | Safe inventory and vault-wrapper example layout |

---

Contributing

See CONTRIBUTING.md.

License

Apache 2.0 — see LICENSE.