Refactor references, examples and skill istructions

[NomakCooper]

SUMMARY

This PR refactor references, examples and skill istructions.

Refreshed existing reference files

• best_practices.md

  • Reworked around practical authoring rules: FQCN usage, idempotency, task tags, handlers, validation, and variable placement.
  • Added clearer guidance for role, playbook, and collection review.

• discovery.md

  • Simplified and clarified the discovery process.
  • Expanded discovery expectations for roles, collections, playbooks, inventories, examples, and validation hints.

• playbook.md

  • Replaced large generic templates with a clearer baseline structure.
  • Added guidance for site playbooks, component playbooks, controller-ready playbooks, validation tasks, and error handling.

• role.md

  • Clarified role structure, defaults vs vars usage, handler expectations, smoke-test expectations, and optional meta/argument_specs.yml.
  • Updated multi-platform guidance toward a first_found-style variable loading pattern.

• collection.md

  • Simplified the recommended collection structure.
  • Focused on galaxy.yml, meta/runtime.yml, plugin expectations, collection roles, and collection testing expectations.

• inventory.md

  • Shifted to YAML-first inventory guidance.
  • Added clearer patterns for group_vars, host_vars, dynamic inventory notes, and secret-safe inventory examples.

• ansible_cfg.md

  • Reworked the development, CI, and controller-oriented profiles.
  • Standardized guidance around collections_path, security-sensitive comments, and configuration review heuristics.

Added new reference files

• testing.md

  • Documents syntax-check, ansible-lint, role smoke tests, and ansible-test expectations.

• security_vault.md

  • Documents secret handling, wrapper variables, vault-safe example patterns, and review heuristics for sensitive content.

• plugins.md

  • Documents expectations for custom modules, filter plugins, and lookup plugins.
  • Defines skeleton-level expectations such as DOCUMENTATION, EXAMPLES, RETURN, AnsibleModule, and plugin usage guidance.

Overall reference outcome

The references now form a more coherent runtime knowledge base for:

• playbook generation and review
• role generation and review
• collection generation and review
• inventory and config examples
• plugin authoring guidance
• testing and validation expectations
• vault-safe and enterprise-safe patterns

Examples

The example layer was expanded and corrected so it better matches the new references and is more usable for validation and learning.

Updated existing examples

• examples/simple-playbook/

  • Added bundled lightweight example roles for common, nginx, and postgres.
  • Removed a weak ignore_errors pattern from the main playbook.
  • Updated the README to describe bundled roles and provide validation commands.
  • Kept the example focused on inventory, group vars, and role-based orchestration.

• examples/role-rhel/

  • Kept the RHEL nginx example as the main single-platform role example.
  • Updated the README to include validation commands for smoke testing and linting.

• examples/role-multiplatform/

  • Updated the README with validation guidance.
  • Updated the main role dispatcher to use a first_found lookup pattern for vars.
  • Added the missing Solaris ntp.conf.j2 template.
  • Fixed metadata and several task details to improve lintability and consistency.
  • Renamed role-local registered variables to follow role prefix expectations.

• examples/local-collection/

  • Improved the README to describe collection metadata, plugin coverage, and ansible-test usage.
  • Updated the example ansible.cfg to a more current style.
  • Added meta/runtime.yml and a collection-local example playbook.
  • Added filter and lookup plugin examples alongside the existing module example.
  • Added integration test target scaffolding for the module example.
  • Simplified the baseline role so it is easier to validate in a constrained environment.

Added new examples

• examples/ansible-cfg-profiles/

  • New example showing ansible.dev.cfg, ansible.ci.cfg, and ansible.awx.cfg.
  • Includes README guidance for inspecting effective config.

• examples/inventory-vault/

  • New example showing a safe inventory + wrapper-vault pattern.
  • Includes inventory/, group_vars/, host_vars/, and a placeholder vault.example.yml.

Overall example outcome

The examples now cover:

• site-playbook orchestration
• single-platform role design
• multi-platform role design
• local collection structure
• ansible.cfg profile patterns
• inventory and vault-wrapper layout

They also provide clearer validation paths and better alignment with the documented skill behavior.

Skills

The skill entrypoints were updated so they explicitly use the refreshed references instead of leaving new guidance disconnected from the command flows.

Root skill update

• skills/ansible-designer/SKILL.md
  • Updated the global rules to reference:
    • best_practices.md
    • security_vault.md
    • testing.md
  • Expanded the reference table to include the three new reference files.
  • Added stronger emphasis on testing-aware output for generated and updated examples.

Updated sub-skills

All sub-skills were reviewed and updated where needed:

• new-playbook
• review-playbook
• update-playbook
• new-role
• review-role
• update-role
• new-collection
• review-collection
• update-collection
• new-conf
• review-conf
• update-conf

What changed across the sub-skills

• Playbook skills

  • Added explicit references to inventory guidance, testing guidance, and vault-safe handling.
  • Strengthened expectations around validation tasks and example usability.

• Role skills

  • Added explicit references to security_vault.md and testing.md.
  • Strengthened smoke-test expectations and review findings for missing validation paths.

• Collection skills

  • Added explicit references to plugins.md and testing.md.
  • Strengthened plugin documentation and collection validation expectations.

• Config skills

  • Updated the config guidance to prefer collections_path in new examples.
  • Connected vault-related behavior to the dedicated vault/security reference.

Overall skill outcome

The skill layer is now better aligned with the refreshed knowledge base:

• generation skills point to the right reference files
• review skills mention newer validation and safety expectations
• update skills keep consistency with testing and secret-handling guidance

Validation Status

Validation after the refresh produced the following results:

• python3 scripts/validate_structure.py

  • Passed

• python3 scripts/validate_frontmatter.py

  • Still blocked in this environment because pyyaml is unavailable offline

• ansible-playbook --syntax-check

  • Passed for the refreshed example playbooks when run with temporary-path overrides and explicit role/collection paths

• ansible-lint

  • Passed for the refreshed example set when excluding the optional Windows multi-platform example and using dependency-safe environment settings
  • The remaining full-tree lint blocker is environment-specific: ansible.windows is not installed here, so static loading of Windows tasks still fails during full lint

Scope of the Refresh

In practical terms, this update delivered:

• a cleaner, more maintainable reference layer
• broader example coverage
• better alignment between the references and the skill entrypoints
• improved validation and documentation around testing, collections, plugins, and vault-safe patterns

ISSUE TYPE

• Refactoring Pull Request

COMPONENT NAME

ADDITIONAL INFORMATION