Claude Ansible Skills

ai-skills-ansible

A collection of Claude Code skills for Ansible automation development following Red Hat Communities of Practice (CoP) good practices.

Each ansible-* plugin directory also conforms to the Agent Plugins v1.0.0 specification (root plugin.json, flat skills/), so the same packages work in Agent Plugins clients as well as Claude Code. Skill content follows agentskills.io.

Skills

ansible-good-practices

Review Ansible code against Red Hat CoP automation good practices loaded from per-section AsciiDoc references.

• Section-selective loading — loads only the reference sections relevant to the files being reviewed
• Severity classification: ERROR, WARNING, INFO
• Diff-aware mode — review only changed files
• Category filtering — focus on specific rule categories
• ansible-lint integration with CoP rule cross-referencing
• Parallel review with subagents for large projects
• Auto-fix offer after reporting

ansible-new-role

Create a new Ansible role fully compliant with CoP rules.

• Interactive variable builder — asks what the role manages (packages, services, configs, users, firewall, storage) and generates realistic defaults, tasks, handlers, and templates
• Task componentization — splits complex roles into install.yml, configure.yml, service.yml with sub-task name prefixes
• Smart handler generation — creates real handlers (restart, reload, validate) based on role purpose
• Collection-aware — uses ansible-creator inside collections, manual creation otherwise
• Falls back to manual creation when ansible-creator is not installed

ansible-new-collection

Create a new Ansible content collection using ansible-creator, then customize for full CoP compliance.

• Plugin scaffolding — generates modules, filters, lookup, and action plugin skeletons with proper docstrings and FQCN examples
• Delegates role creation to the full ansible-new-role skill process
• CI/CD pipeline generation for GitHub Actions or GitLab CI (lint, test, build, publish)
• Changelog setup with antsibull-changelog
• Generates collection-level CLAUDE.md for future Claude Code sessions
• Falls back to manual creation when ansible-creator is not installed

ansible-new-ee

Create a new Ansible execution environment project using ansible-creator.

• Dependency introspection — auto-detects collections, roles, Python, and system deps from existing project files
• External dependency files — generates requirements.yml, requirements.txt, and bindep.txt for non-trivial EEs
• CI/CD pipeline generation for GitHub Actions or GitLab CI (build, test, push to registry)
• Falls back to manual creation when ansible-creator is not installed

ansible-docs

Answer Ansible questions and review code against official Ansible ecosystem documentation.

• Covers 6 doc sources: ansible-core, ansible-lint, ansible-navigator, ansible-builder, ansible-creator, molecule
• Q&A mode — search docs, answer grounded in official documentation with URL citations
• Code review mode — identify directives/modules in code, review against official docs
• Requires the ansible-know MCP server (v0.7.0+) — install with uvx ansible-know-mcp
• Complements ansible-good-practices (official docs vs CoP rules)

ansible-new-molecule

Scaffold molecule testing for an Ansible role or collection following the current molecule testing philosophy (Ansible-native everything).

• Modern molecule.yml — no driver/provisioner/verifier/platforms blocks (Ansible-native defaults)
• Self-contained create.yml/destroy.yml playbooks for Docker or Podman with systemd-aware container strategy
• Smart verify.yml generated from role archetype detection (service, package, config, etc.)
• Optional GitHub Actions CI workflow generation
• Collection support — nested scenarios, shared state, tox-ansible integration
• Can be called standalone or invoked by ansible-new-role/ansible-new-collection during scaffolding

ansible-zen

Display the Zen of Ansible and review code against its 20 principles.

• Display mode — prints the full Zen and explains a random principle with a practical example
• Review mode — evaluates Ansible code for simplicity, readability, and clarity
• Zen Score (1-10) rating with justification
• Principle-grouped findings with before/after code improvements
• Complements ansible-good-practices with philosophical guidance

ansible-pytest-migrate

Migrate off, remove, deprecate, or audit the pytest-ansible plugin in an Ansible collection repository.

• Establishes real plugin use first — dependencies, imports, plugin-only fixtures, --ansible-* options — before editing anything
• Distinguishes plugin use from ordinary Ansible variables, module mocks, and the unrelated pytest-ansible-units package
• Smallest-change migration — replaces functional options (e.g. --ansible-unit-inject-only) rather than deleting them outright
• Keeps plain pytest and ansible-test in place; only the plugin dependency is removed
• Validates with the repository's own test entry point and reports what was removed, changed, and run

Project Structure

Each top-level ansible-* directory is a standalone plugin with a portable Agent Plugins layout plus a Claude Code sidecar:

ansible-<name>/
├── plugin.json              # Agent Plugins v1.0.0 manifest
├── mcp.json                 # Optional Agent Plugins MCP config (open-spec clients)
├── .mcp.json                # Optional Claude Code MCP config (same servers, Claude's own format)
├── .claude-plugin/
│   └── plugin.json          # Claude Code plugin metadata
└── skills/
    └── ansible-<name>/
        └── SKILL.md          # agentskills.io skill definition

• Root plugin.json is the Agent Plugins manifest ($schema, name, version, description, license, keywords).
• mcp.json declares ansible-know, pinned to an exact version (uvx ansible-know-mcp==<version>, not a bare package name, to avoid dependency confusion) for clients that implement the Agent Plugins open spec. .mcp.json declares the same pinned server in Claude Code's own format — Claude Code does not read the non-dotted mcp.json at a plugin's root, only .mcp.json; both ship side by side so each client finds its own. Omitted on ansible-zen and ansible-pytest-migrate.
• .claude-plugin/ stays for Claude Code marketplace install and does not replace root plugin.json.
• skills/ is flat: one level of <skill-name>/SKILL.md children, as Agent Plugins discovery requires.

The root .claude-plugin/marketplace.json indexes all plugins for Claude Code marketplace discovery.

Installation

Plugin install (recommended)

Register the marketplace and install skills as plugins:

/plugin marketplace add https://github.com/leogallego/ai-skills-ansible
/plugin install ansible-good-practices
/plugin install ansible-new-role
/plugin install ansible-new-collection
/plugin install ansible-new-ee
/plugin install ansible-new-molecule
/plugin install ansible-docs
/plugin install ansible-zen
/plugin install ansible-pytest-migrate

Manual install (symlinks)

Alternatively, clone and symlink individual skill directories. Each skill lives inside <plugin>/skills/<skill-name>/.

Project-level (single project):

git clone https://github.com/leogallego/ai-skills-ansible.git
cd ~/my-ansible-project
mkdir -p .claude/skills
ln -s ~/ai-skills-ansible/ansible-good-practices/skills/ansible-good-practices .claude/skills/ansible-good-practices

Profile-level (all projects):

mkdir -p ~/.claude/skills
ln -s ~/ai-skills-ansible/ansible-new-role/skills/ansible-new-role ~/.claude/skills/ansible-new-role

All skills at once at profile level:

mkdir -p ~/.claude/skills
for plugin in ~/ai-skills-ansible/ansible-*/; do
  skill=$(basename "$plugin")
  ln -s "$plugin/skills/$skill" ~/.claude/skills/"$skill"
done

Usage

Once installed, invoke skills in Claude Code with their slash command:

/ansible-good-practices
/ansible-new-role
/ansible-new-collection
/ansible-new-ee
/ansible-new-molecule
/ansible-docs
/ansible-zen
/ansible-pytest-migrate

Dependencies

• ansible-know MCP server — required by ansible-docs, optionally used by ansible-new-molecule and scaffold skills for module doc lookup (install with uvx ansible-know-mcp or claude mcp add ansible-know -- uvx ansible-know-mcp)
• ansible-creator — used by scaffold skills to generate base skeletons (optional — skills fall back to manual creation)
• ansible-lint — used by the review skill for cross-referencing (optional)
• molecule — used by ansible-new-molecule for testing scaffolding (optional — skill falls back to manual creation)
• CoP rules — skills load rules from bundled references/*.adoc files (per-section AsciiDoc from redhat-cop/automation-good-practices), with GitHub fetch as fallback and CLAUDE.md as last resort

Contributing

We welcome contributions from the community. This project follows the Red Hat Communities of Practice contributing guidelines.

Development workflow

1. Fork the repository
2. Create a branch for your work
3. Open a pull request following the guidelines below
4. Address reviewer feedback
5. A maintainer will merge once approved — do not merge your own PRs

Adding a new skill

1. Create a directory named ansible-<skill-name>/
2. Add root plugin.json (Agent Plugins v1.0.0) with $schema set to https://agent-plugins.org/schemas/1.0.0/plugin.schema.json. name must be lowercase alphanumeric plus hyphens/dots, max 64 characters.
3. Add .claude-plugin/plugin.json with name, version, and description
4. Add skills/<skill-name>/SKILL.md with frontmatter and prompt body
5. Add root mcp.json and root .mcp.json (same mcpServers content) when the skill requires or is improved by an MCP server at runtime. Pin the server to an exact version (ansible-know-mcp==<version>, not a bare package name) to avoid dependency confusion — check the current version on PyPI before pinning. Current skills declare ansible-know except ansible-zen and ansible-pytest-migrate. Claude Code only reads the dotted .mcp.json at a plugin's root, not mcp.json — ship both so Claude Code and Agent Plugins open-spec clients each find their own file. Agent Plugins has no disable flag in mcp.json; users turn servers off in the client (Claude Code /mcp or disabledMcpServers).
6. Follow the SKILL.md format:
   • Description must include what the skill does, when to use it, and trigger phrases users would say
   • Add argument-hint if the skill accepts arguments
   • Add disable-model-invocation: true for skills with side effects
   • Keep SKILL.md under 500 lines; move detailed docs to references/
7. Skills should reference CLAUDE.md rules rather than duplicating them
8. Run node scripts/gen-marketplace.js to regenerate the marketplace index
9. Commit the updated marketplace.json alongside your changes

Modifying existing skills

• Read the skill's SKILL.md before modifying — understand the full prompt
• After changes, run node scripts/gen-marketplace.js to update plugin metadata
• Squash commits whenever possible

Best practices

• Write clear, descriptive PR titles and summaries
• Do not commit directly to the main branch
• Review existing skills to prevent duplication
• Test your skill by invoking it with /skill-name in Claude Code
• Use snake_case with hyphens for directory names (matching ansible-*)

Reporting issues

Open an issue on GitHub for:

• Bug reports — describe the skill, the input, and the unexpected behavior
• Feature requests — describe the use case and the expected outcome
• Rule updates — if Red Hat CoP good practices change upstream

License

GPL-3.0-or-later