ansible-designer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ansible-designer

AI-assisted Ansible authoring toolkit. Scaffolds, reviews, and updates Ansible projects with production-quality output following official ansible-core 2.15+ conventions.

AI辅助Ansible创作工具包，遵循ansible-core 2.15+官方规范生成生产级质量的内容，支持为Ansible项目生成脚手架、审查以及更新操作。

Available Commands

可用命令

Playbook Commands

Playbook命令

Command	Description
`/ansible-designer:new-playbook`	Create a new playbook (site, component, or AWX-ready)
`/ansible-designer:review-playbook`	Review an existing playbook — severity report, no file modification
`/ansible-designer:update-playbook`	Update a playbook — shows diff, requires confirmation

命令	说明
`/ansible-designer:new-playbook`	创建新的playbook（支持站点、组件或者AWX就绪类型）
`/ansible-designer:review-playbook`	审查现有playbook — 生成严重程度报告，不修改文件
`/ansible-designer:update-playbook`	更新playbook — 展示差异，需用户确认后执行

Role Commands

Role命令

Command	Description
`/ansible-designer:new-role`	Scaffold a complete role — asks about multi-OS support
`/ansible-designer:review-role`	Review a role — severity report, no file modification
`/ansible-designer:update-role`	Update a role — shows diff, requires confirmation

命令	说明
`/ansible-designer:new-role`	生成完整的role脚手架 — 可配置多操作系统支持
`/ansible-designer:review-role`	审查role — 生成严重程度报告，不修改文件
`/ansible-designer:update-role`	更新role — 展示差异，需用户确认后执行

Collection Commands

Collection命令

Command	Description
`/ansible-designer:new-collection`	Scaffold a new collection with galaxy.yml, plugins, roles structure
`/ansible-designer:review-collection`	Review a collection — severity report, no file modification
`/ansible-designer:update-collection`	Update a collection — shows diff, requires confirmation

命令	说明
`/ansible-designer:new-collection`	生成新的collection脚手架，包含galaxy.yml、插件、roles目录结构
`/ansible-designer:review-collection`	审查collection — 生成严重程度报告，不修改文件
`/ansible-designer:update-collection`	更新collection — 展示差异，需用户确认后执行

ansible.cfg Commands

ansible.cfg命令

Command	Description
`/ansible-designer:new-conf`	Generate an annotated ansible.cfg for dev, CI, or AWX
`/ansible-designer:review-conf`	Review an ansible.cfg — severity report, no file modification
`/ansible-designer:update-conf`	Update ansible.cfg — shows diff, requires confirmation

命令	说明
`/ansible-designer:new-conf`	生成带注释的ansible.cfg文件，适配开发、CI或者AWX环境
`/ansible-designer:review-conf`	审查ansible.cfg — 生成严重程度报告，不修改文件
`/ansible-designer:update-conf`	更新ansible.cfg — 展示差异，需用户确认后执行

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
```
for the complete mapping table.
no_log: true on secrets — Every task handling passwords, tokens, API keys, vault variables, or credentials must include
```
no_log: true
```
.
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, run
```
find <path> -type f | sort
```
and display the resulting file tree.
Suggest next step — End every command with a concrete suggestion: which command to run next, or what to validate.

所有子命令都严格遵守以下规则：

优先执行资源发现 — 命令启动时，按顺序读取：
```
CLAUDE.md
```
→
```
ansible.cfg
```
→
```
README.md
```
→ 扫描文件系统，构建内部上下文（包含roles、collections、路径、命名空间）。如果用户已经在行内提供了所有必需参数则跳过该步骤，详见
```
references/discovery.md
```
。
禁止静默覆盖 — 写入任何文件前，展示新增文件摘要或者修改内容的统一diff，等待用户明确确认（
```
yes
```
/
```
y
```
），确认后才执行写入操作。
强制使用FQCN — 所有模块引用都必须使用完全限定集合名，例如必须写
```
ansible.builtin.copy
```
，不能写
```
copy
```
；必须写
```
ansible.builtin.service
```
，不能写
```
service
```
。完整映射表详见
```
references/best_practices.md
```
。
敏感任务必须添加
no_log: true
— 所有处理密码、令牌、API密钥、vault变量或者凭证的任务都必须配置
```
no_log: true
```
。
所有任务必须配置标签 — 最少需要配置：组件名称 + 操作分类（
```
install
```
、
```
configure
```
、
```
service
```
、
```
validate
```
、
```
security
```
、
```
cleanup
```
），不允许存在无标签的任务。
审查命令永不修改文件 —
```
review-*
```
类命令仅生成结构化的严重程度报告（严重/警告/信息），不会写入、修改文件，也不会建议
```
sed
```
类修改命令，仅输出报告。
更新命令必须先展示diff —
```
update-*
```
类命令会先读取现有文件，计算变更内容，展示统一diff，等待用户明确确认后才会执行任何写入操作。
写入后展示文件树 — 任何写入操作完成后，执行
```
find <path> -type f | sort
```
命令并展示生成的文件树。
建议下一步操作 — 每个命令执行结束时都会给出具体的下一步操作建议，比如接下来要运行的命令，或者需要验证的内容。

Standard Operational Flow

标准操作流程

Every command follows this exact sequence:

所有命令都严格遵循以下执行顺序：

Step 1 — Discovery

步骤1 — 资源发现

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.

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]"

仅当用户在行内提供了所有必需参数时才跳过步骤1。

Step 2 — Parameter Collection

步骤2 — 参数收集

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).

如果用户已经提供了所有必需参数：直接进入步骤3。
否则：一次只提一个问题，结合资源发现的上下文给出智能默认值。
不要询问可以通过资源发现推断的内容（例如如果已经存在collection则不要询问命名空间）。

Step 3 — Pre-Write Confirmation

步骤3 — 写入前确认

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.

对于新增文件：展示将要创建的内容摘要（路径 + 简要说明）。
对于更新命令：展示统一diff（
```
--- 原文件
```
，
```
+++ 建议修改内容
```
）。
继续操作前必须等待用户明确确认（
```
yes
```
、
```
y
```
或者等效内容）。
如果用户拒绝修改：询问需要调整的内容，回到步骤2循环执行。

Step 4 — Execution

步骤4 — 执行

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.

使用bash命令写入或者修改文件。
遵守所有全局规则：FQCN、标签、no_log配置。
基于
```
references/
```
目录下对应的模板文件生成内容。

Step 5 — Final Output

步骤5 — 最终输出

Show file tree of all created/modified files.
Suggest: "Next step: [specific actionable suggestion]"

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/discovery.md`	所有命令 — 步骤1
`references/best_practices.md`	所有命令 — FQCN、标签、no_log、幂等性配置
`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`	所有命令 — 清单上下文

Installation

安装

bash

npx skills add 3A2DEV/ansible-designer -a claude-code

Requires Claude Code with

bash_tool

enabled.

bash

npx skills add 3A2DEV/ansible-designer -a claude-code

需要已启用

bash_tool

的Claude Code环境。