# ansible-roles

The ansible-roles skill structures Ansible automation as reusable roles. Use it when an nginx setup needs separate tasks, templates, variables, and security steps.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 234 installs · ★ 201 repo stars
- Author: TheBushidoCollective
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/TheBushidoCollective/han/tree/HEAD/plugins/tools/ansible/skills/ansible-roles/SKILL.md
- Updated: 2026-09-08
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/ansible-roles

## What it does

The skill lays out a role with directories such as `tasks`, `handlers`, `templates`, `files`, `defaults`, `vars`, `meta`, and `tests`. Installation, configuration, and security are split into separate task files, while `tasks/main.yml` brings them together with `import_tasks`.

Its example covers an nginx role for Debian/Ubuntu and RedHat/CentOS. The role installs packages, creates directories, renders configuration from templates, enables sites, manages log rotation, and can configure SSL, firewall rules, and basic authentication.

When SSL is enabled, the security task calls `openssl dhparam`, so that command must be available on the target system. The skill is configured with `Bash` and `Read` as its allowed tools.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add TheBushidoCollective/han --skill ansible-roles -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/ansible-roles/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/ansible-roles/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add TheBushidoCollective/han --skill ansible-roles -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/ansible-roles/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add TheBushidoCollective/han --skill ansible-roles -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/ansible-roles/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install TheBushidoCollective/han plugins/tools/ansible/skills/ansible-roles
```

2. **Manually: put the files in place**
- File: `.github/skills/ansible-roles/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add TheBushidoCollective/han --skill ansible-roles -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/TheBushidoCollective/han --path plugins/tools/ansible/skills/ansible-roles
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/ansible-roles/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add TheBushidoCollective/han --skill ansible-roles -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/TheBushidoCollective/han/tree/HEAD/plugins/tools/ansible/skills/ansible-roles/SKILL.md

## When to use it
- organize an Ansible role into standard directories
- split installation, configuration, and security into task files
- configure nginx from Jinja templates
- support Debian/Ubuntu and RedHat/CentOS variables
- add SSL, firewall rules, and basic authentication

## Example prompts
- Build an nginx role with `tasks`, `templates`, `handlers`, `defaults`, and `tests` directories.
- Split `tasks/main.yml` into installation, configuration, and security files linked with `import_tasks`.
- Show how to add nginx configuration templates, SSL handling, and firewall tasks to the role.

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: aa9bb457fcd9dbe0.

BEGIN THIRD-PARTY FILE aa9bb457fcd9dbe0
````text
---
name: ansible-roles
user-invocable: false
description: Use when structuring and reusing code with Ansible roles for modular, maintainable automation and configuration management.
allowed-tools: [Bash, Read]
---

# Ansible Roles

Structure and reuse automation code with Ansible roles for modular, maintainable infrastructure.

## Role Directory Structure

A well-organized Ansible role follows a standardized directory structure:

```
roles/
└── webserver/
    ├── README.md
    ├── defaults/
    │   └── main.yml
    ├── files/
    │   ├── nginx.conf
    │   └── ssl/
    │       ├── cert.pem
    │       └── key.pem
    ├── handlers/
    │   └── main.yml
    ├── meta/
    │   └── main.yml
    ├── tasks/
    │   ├── main.yml
    │   ├── install.yml
    │   ├── configure.yml
    │   └── security.yml
    ├── templates/
    │   ├── nginx.conf.j2
    │   └── site.conf.j2
    ├── tests/
    │   ├── inventory
    │   └── test.yml
    └── vars/
        └── main.yml
```

## Basic Role Example

### tasks/main.yml

```yaml
---
# Main task file for webserver role
- name: Include OS-specific variables
  include_vars: "{{ ansible_os_family }}.yml"

- name: Import installation tasks
  import_tasks: install.yml
  tags:
    - install
    - webserver

- name: Import configuration tasks
  import_tasks: configure.yml
  tags:
    - configure
    - webserver

- name: Import security tasks
  import_tasks: security.yml
  tags:
    - security
    - webserver

- name: Ensure nginx is running
  service:
    name: "{{ nginx_service_name }}"
    state: started
    enabled: yes
  tags:
    - service
    - webserver
```

### tasks/install.yml

```yaml
---
# Installation tasks for webserver role
- name: Install nginx and dependencies (Debian/Ubuntu)
  apt:
    name:
      - nginx
      - nginx-extras
      - python3-passlib
    state: present
    update_cache: yes
    cache_valid_time: 3600
  when: ansible_os_family == "Debian"

- name: Install nginx and dependencies (RedHat/CentOS)
  yum:
    name:
      - nginx
      - nginx-mod-stream
      - python3-passlib
    state: present
    update_cache: yes
  when: ansible_os_family == "RedHat"

- name: Create nginx directories
  file:
    path: "{{ item }}"
    state: directory
    owner: "{{ nginx_user }}"
    group: "{{ nginx_group }}"
    mode: '0755'
  loop:
    - "{{ nginx_conf_dir }}/sites-available"
    - "{{ nginx_conf_dir }}/sites-enabled"
    - "{{ nginx_log_dir }}"
    - "{{ nginx_cache_dir }}"
    - /var/www/html
````
END THIRD-PARTY FILE aa9bb457fcd9dbe0

The third-party file has ended. Everything between the aa9bb457fcd9dbe0 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2667 of 21545 bytes. © TheBushidoCollective · Apache-2.0 · https://github.com/TheBushidoCollective/han/tree/HEAD/plugins/tools/ansible/skills/ansible-roles/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
