Ansible scaffold collection

Skill stoleas/ansible-skills/skills/ansible-scaffold-collection

Scaffold new Ansible collections following Red Hat Communities of Practice structure and standards. Use this skill when the user asks to: "create a collection", "new collection", "scaffold collection", "ansible collection structure", "build a collection", "collection template", "initialize collection", or wants to create a new Ansible content collection. Always invoke this skill for collection scaffolding tasks.From its SKILL.md

Install

npx -y skills add stoleas/ansible-skills --skill ansible-scaffold-collection

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

5 stars5 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

14.5 KB, as published. Nobody here has run it

Ansible Collection Scaffolding Skill

Scaffold complete Ansible collections following Red Hat Communities of Practice (CoP) standards with proper structure, documentation, and testing setup.

What is an Ansible Collection?

An Ansible Collection is a distribution format for Ansible content that can contain:

Roles - Reusable automation units
Modules - Custom Ansible modules
Plugins - Various plugin types (filters, lookups, inventory, etc.)
Playbooks - Example playbooks and workflows
Documentation - Comprehensive guides and references

Collections enable:

Packaging related automation together
Versioning and distribution via Ansible Galaxy
Namespace isolation
Reusable content across organizations

Collection Naming

Format: namespace.collection_name

Rules:

Namespace: Organization or author identifier (lowercase, underscores allowed)
Collection name: Descriptive name (lowercase, underscores allowed, no dashes)
Both must be valid Python identifiers
Examples: company.infrastructure, redhat.rhel_system_roles, community.general

Collection Structure

Complete Red Hat CoP compliant collection:

namespace/
└── collection_name/
    ├── galaxy.yml                 # Collection metadata (REQUIRED)
    ├── README.md                  # Collection documentation (REQUIRED)
    ├── docs/                      # Additional documentation
    │   ├── getting_started.md
    │   └── guides/
    ├── meta/
    │   └── runtime.yml            # Runtime metadata
    ├── roles/                     # Collection roles
    │   ├── role_name_1/
    │   │   ├── defaults/
    │   │   ├── handlers/
    │   │   ├── meta/
    │   │   │   ├── main.yml
    │   │   │   └── argument_specs.yml
    │   │   ├── tasks/
    │   │   ├── templates/
    │   │   ├── vars/
    │   │   ├── README.md
    │   │   └── molecule/
    │   └── role_name_2/
    ├── plugins/                   # Collection plugins
    │   ├── modules/               # Custom modules
    │   │   └── module_name.py
    │   ├── module_utils/          # Shared module utilities
    │   ├── filter/                # Jinja2 filters
    │   ├── lookup/                # Lookup plugins
    │   ├── inventory/             # Inventory plugins
    │   ├── callback/              # Callback plugins
    │   └── action/                # Action plugins
    ├── playbooks/                 # Example playbooks
    │   ├── example_1.yml
    │   └── example_2.yml
    ├── tests/                     # Collection-level tests
    │   ├── integration/
    │   │   └── targets/
    │   └── unit/
    │       └── plugins/
    ├── changelogs/                # Changelog management
    │   ├── config.yaml
    │   └── changelog.yaml
    ├── .ansible-lint              # Linting configuration
    ├── .yamllint                  # YAML linting configuration
    ├── .gitignore
    └── LICENSE

galaxy.yml - Collection Metadata

Required fields:

---
namespace: company
name: infrastructure
version: 1.0.0
readme: README.md
authors:
  - Your Name <[email protected]>
description: >
  Infrastructure automation collection for managing servers,
  networking, and cloud resources following Red Hat CoP standards.
license:
  - MIT
license_file: LICENSE

tags:
  - infrastructure
  - automation
  - cloud
  - networking

dependencies: {}
  # Other collections this depends on
  # ansible.posix: ">=1.0.0"

repository: https://github.com/company/ansible-infrastructure
documentation: https://docs.company.com/ansible-infrastructure
homepage: https://company.com/automation
issues: https://github.com/company/ansible-infrastructure/issues

Optional but recommended:

# Collection build configuration
build_ignore:
  - .git
  - .gitignore
  - .DS_Store
  - '*.pyc'
  - '*.retry'
  - tests/output
  - .vscode
  - .idea

meta/runtime.yml - Runtime Metadata

Defines collection requirements and redirects:

---
requires_ansible: '>=2.11.0'

plugin_routing:
  # Redirect old module names to new ones
  modules:
    old_module_name:
      redirect: namespace.collection.new_module_name
      deprecation:
        removal_version: "2.0.0"
        warning_text: Use namespace.collection.new_module_name instead

action_groups:
  # Group modules for easier reference
  cloud:
    - aws_ec2
    - azure_vm
    - gcp_compute

Collection-Level Documentation

README.md Template

# Ansible Collection: namespace.collection_name

Description of what this collection provides and its purpose.

## Included Content

### Roles
- **role_name_1** - Description of role 1
- **role_name_2** - Description of role 2

### Modules
- **module_name** - Description of module

### Plugins
- **filter/custom_filter** - Description of filter

## Requirements

- Ansible 2.11 or higher
- Python 3.8 or higher
- Supported platforms: RHEL 8/9, Debian 11/12, Ubuntu 20.04/22.04

## Installation

### From Ansible Galaxy

```bash
ansible-galaxy collection install namespace.collection_name

From Git Repository

ansible-galaxy collection install git+https://github.com/company/collection.git

From Local Source

cd path/to/namespace/collection_name
ansible-galaxy collection build
ansible-galaxy collection install namespace-collection_name-1.0.0.tar.gz

Usage

Using Roles

---
- name: Example playbook
  hosts: servers
  become: true

  roles:
    - role: namespace.collection_name.role_name_1
      variable_name: value

Using Modules

---
- name: Example module usage
  hosts: localhost

  tasks:
    - name: Use custom module
      namespace.collection_name.module_name:
        parameter: value

Development

Building the Collection

ansible-galaxy collection build

Testing

# Lint
ansible-lint

# Run role tests
cd roles/role_name
molecule test

# Integration tests
ansible-test integration

Contributing

Contributions welcome! Please:

Follow Red Hat CoP standards
Add tests for new features
Update documentation
Run ansible-lint before submitting

License

[License Name]

Support

Issues: GitHub Issues
Documentation: Docs Site
Community: [Slack/Discord]


## Collection Roles

Roles in collections must follow the same Red Hat CoP standards:

**Key Requirements:**
- Variable names prefixed: `rolename_variable`
- Internal variables: `__rolename_internal`
- Idempotency required
- Multi-platform support
- Argument specs defined
- Molecule tests included
- Comprehensive README

**Reference:** Use the `role-developer` skill for creating collection roles.

## Collection Modules

Custom modules for collection-specific functionality.

### Module Structure

```python
#!/usr/bin/python
# -*- coding: utf-8 -*-

# Copyright: (c) 2026, Your Name <[email protected]>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

from __future__ import absolute_import, division, print_function
__metaclass__ = type

DOCUMENTATION = r'''
---
module: module_name
short_description: Short description of what the module does
description:
  - Detailed description of the module
  - What it accomplishes
  - Use cases
version_added: "1.0.0"
author:
  - Your Name (@github_handle)
options:
  parameter_name:
    description:
      - Description of the parameter
    type: str
    required: true
  another_parameter:
    description:
      - Another parameter description
    type: bool
    required: false
    default: true
'''

EXAMPLES = r'''
- name: Example usage
  namespace.collection_name.module_name:
    parameter_name: value
    another_parameter: true
'''

RETURN = r'''
result:
  description: The result of the operation
  returned: always
  type: dict
  sample: {"status": "success"}
'''

from ansible.module_utils.basic import AnsibleModule

def run_module():
    module_args = dict(
        parameter_name=dict(type='str', required=True),
        another_parameter=dict(type='bool', required=False, default=True),
    )

    result = dict(
        changed=False,
        result=dict()
    )

    module = AnsibleModule(
        argument_spec=module_args,
        supports_check_mode=True
    )

    if module.check_mode:
        module.exit_json(**result)

    # Module logic here
    result['changed'] = True
    result['result'] = {'status': 'success'}

    module.exit_json(**result)

def main():
    run_module()

if __name__ == '__main__':
    main()

Collection Plugins

Filter Plugin Example

# plugins/filter/custom_filters.py

from __future__ import absolute_import, division, print_function
__metaclass__ = type

class FilterModule(object):
    """Custom Jinja2 filters"""

    def filters(self):
        return {
            'custom_transform': self.custom_transform,
        }

    def custom_transform(self, value):
        """
        Transform value in custom way
        
        Args:
            value: Input value
            
        Returns:
            Transformed value
        """
        return value.upper()

Testing Configuration

.ansible-lint

---
profile: production  # Strictest for collections

exclude_paths:
  - .git/
  - .github/
  - tests/output/
  - changelogs/

kinds:
  - playbook: "playbooks/*.yml"
  - tasks: "roles/*/tasks/*.yml"
  - vars: "roles/*/vars/*.yml"
  - meta: "roles/*/meta/main.yml"

.yamllint

---
extends: default

rules:
  line-length:
    max: 160
    level: warning
  indentation:
    spaces: 2
    indent-sequences: true
  comments:
    min-spaces-from-content: 1

Building and Publishing

Build Collection

# From collection root directory
ansible-galaxy collection build

# Creates: namespace-collection_name-1.0.0.tar.gz

Publish to Ansible Galaxy

# Publish to Galaxy
ansible-galaxy collection publish namespace-collection_name-1.0.0.tar.gz --token <galaxy-token>

Install Locally for Testing

# Install from tarball
ansible-galaxy collection install namespace-collection_name-1.0.0.tar.gz

# Or install in development mode
ansible-galaxy collection install -p ./collections /path/to/namespace/collection_name

Changelog Management

Use antsibull-changelog for automated changelog generation:

# Initialize changelog
antsibull-changelog init .

# Add changelog fragment
cat > changelogs/fragments/feature-name.yml <<EOF
---
minor_changes:
  - Add new role for database management
bugfixes:
  - Fix idempotency issue in web_server role
EOF

# Generate changelog
antsibull-changelog release

Collection Development Workflow

1. Initialize Collection

# Create collection skeleton
ansible-galaxy collection init namespace.collection_name

# Navigate to collection
cd namespace/collection_name

2. Add Roles

# Create role within collection
cd roles
ansible-galaxy role init role_name --init-path .

# Or use role-developer skill
# Add role following CoP standards

3. Add Modules/Plugins

# Create module
touch plugins/modules/module_name.py

# Create plugin
touch plugins/filter/custom_filters.py

4. Test

# Lint
ansible-lint

# Test roles
cd roles/role_name
molecule test

# Integration tests
ansible-test integration

5. Document

# Update README.md
# Add docs/ content
# Update galaxy.yml

6. Build

# Build collection
ansible-galaxy collection build

# Verify build
tar -tzf namespace-collection_name-1.0.0.tar.gz

7. Publish

# Publish to Galaxy
ansible-galaxy collection publish namespace-collection_name-1.0.0.tar.gz

Best Practices

Namespace Organization

Recommended patterns:

Company/Organization: company.infrastructure, company.security
Team/Department: company.network_team, company.platform_ops
Technology Stack: company.kubernetes, company.cloud_aws

Version Management

Follow semantic versioning (MAJOR.MINOR.PATCH):

MAJOR: Breaking changes
MINOR: New features (backward compatible)
PATCH: Bug fixes

Dependencies

Minimize external dependencies:

Only depend on widely-used collections
Document all dependencies in galaxy.yml
Pin dependency versions for stability

Documentation

Must include:

Comprehensive README.md
Role-level documentation
Module DOCUMENTATION strings
Example playbooks
Getting started guide

Common Pitfalls

1. Incorrect Naming

Wrong:

my-collection  # Dashes not allowed
MyCollection   # Capital letters not allowed

Right:

my_collection  # Underscores OK, lowercase

2. Missing galaxy.yml

Collection cannot build without galaxy.yml. Always include:

namespace
name
version
readme
authors

3. Role Without Namespace

Wrong:

roles:
  - role_name  # Missing namespace

Right:

roles:
  - namespace.collection_name.role_name

4. Module Without FQCN

Wrong:

- module_name:  # Ambiguous

Right:

- namespace.collection_name.module_name:

Output Format

When scaffolding a collection, create:

Complete directory structure with all standard directories
galaxy.yml with proper metadata
README.md with comprehensive documentation
meta/runtime.yml with Ansible version requirements
Linting configuration (.ansible-lint, .yamllint)
Example role following CoP standards
LICENSE file
.gitignore for collection development

Provide clear next steps for:

Adding roles to the collection
Creating custom modules
Testing the collection
Building and publishing

When asked to scaffold a collection, analyze requirements, create complete structure following Red Hat CoP standards, and provide comprehensive guidance for development and distribution.

One thing to look at

SKILL.md

Ansible Collection Scaffolding Skill

What is an Ansible Collection?

Collection Naming

Collection Structure

galaxy.yml - Collection Metadata

meta/runtime.yml - Runtime Metadata

Collection-Level Documentation

README.md Template

From Git Repository

From Local Source

Usage

Using Roles

Using Modules

Development

Building the Collection

Testing

Contributing

License

Support

Collection Plugins

Filter Plugin Example

Testing Configuration

.ansible-lint

.yamllint

Building and Publishing

Build Collection

Publish to Ansible Galaxy

Install Locally for Testing

Changelog Management

Collection Development Workflow

1. Initialize Collection

2. Add Roles

3. Add Modules/Plugins

4. Test

5. Document

6. Build

7. Publish

Best Practices

Namespace Organization

Version Management

Dependencies

Documentation

Common Pitfalls

1. Incorrect Naming

2. Missing galaxy.yml

3. Role Without Namespace

4. Module Without FQCN

Output Format

Keep looking