refactor: standardize skill documentation on references/ layout

[rhartuv]

Refactor: Standardize skill documentation on references/ layout and consolidate Compass validation

Summary

This PR migrates agentic pack skills from the legacy docs/ convention to the agent-plugins.org references/ layout, removes leftover duplicate directories, flattens accidental references/references/ nesting, and consolidates validation so regressions are caught in CI.
Jira ticket

Motivation

Skill-local documentation must live under references/, not docs/. The old docs/references/ structure caused double-nested references/references/ folders after migration. Pack-level docs/ duplicates also lingered after references/ was introduced.

Changes

Documentation migration (all packs)

• Renamed skills/<name>/docs/ → skills/<name>/references/ across 46+ skills
• Deleted leftover docs/ directories after migration
• Removed duplicate pack-level docs/ trees (ocp-admin, rh-sre, rh-virt, rh-automation) where references/ already existed
• Updated markdown links from docs/... to references/... (including ./references/ form in SKILL.md)
• Flattened 28 references/references/ directories into skills/<name>/references/
• Repaired ~260 symlinks and cross-reference paths broken by the flattening

Validation (single entry point)

• Extended scripts/validate_compass_manifests.py to enforce:
  • No skills/<name>/docs/
  • No references/references/ nesting
  • No skill-local docs/ markdown links
  • No references/ symlinks targeting docs/ paths
• Removed scripts/validate_skill_references_layout.py (merged into compass validation)
• Updated validate_skill_doc_links.py to accept references/... and ./references/...
• Updated validate_docs_tree_links.py to scan skills/*/references/**/*.md

Authoring standards

• SKILL_DESIGN_PRINCIPLES.md — requires references/, forbids nested references/references/, documents symlink pool link rules
• compass-manifest-maintenance skill — workflow to scan, migrate, flatten, delete docs/, fix symlinks, validate via make validate-compass-manifests
• agentic-contribution-skill — creates references/, not docs/
• Pack READMEs, .catalog/collection.yaml embedded_doc paths updated

Note for Reviewers:
Due to file relocation, this PR touches ~700 files. Most changes are path updates and moved files.

Test plan

• make validate passes locally
• uv run python scripts/validate_skill_doc_links.py — passes (70 skills, 388 reference links)
• uv run python scripts/validate_docs_tree_links.py — passes (444 files)
• No skills/*/docs/ directories remain
• No skills/*/references/references/ directories remain
• New/changed skills have valid YAML frontmatter (name, description)
• New/changed agents have valid YAML frontmatter (name, description)