fix: Moved all doc files under the skill folder

CONTRIBUTING.md

@@ -151,6 +151,12 @@ If you prefer manual creation:
 
    # Tier 2 validation (design principles)
    make validate-skill-design-changed
+
+   # Skill docs link validation (must use skill-local docs/... paths)
+   uv run python scripts/validate_skill_doc_links.py <pack>/skills/<skill-name>/SKILL.md
+
+   # Skill docs tree validation (skills docs markdown links)
+   uv run python scripts/validate_docs_tree_links.py <pack>/skills/<skill-name>/SKILL.md
 
    # Both must pass before committing
    ```
@@ -262,6 +268,8 @@ Before submitting a PR, test your skill locally:
 - [ ] Skill created with agentic-contribution-skill or manually validated
 - [ ] Tier 1 validation passed: `./scripts/run-skill-linter.sh`
 - [ ] Tier 2 validation passed: `make validate-skill-design-changed`
+- [ ] Skill docs links validation passed: `uv run python scripts/validate_skill_doc_links.py <pack>/skills/<skill-name>/SKILL.md`
+- [ ] Skill docs tree links validation passed: `uv run python scripts/validate_docs_tree_links.py <pack>/skills/<skill-name>/SKILL.md`
 - [ ] Tested skill locally by invoking it in Claude Code
 - [ ] Reviewed generated skill for accuracy
 - [ ] No credentials exposed in skill documentation

Makefile

@@ -40,6 +40,10 @@ install: check-uv
 validate: check-uv
 	@echo "Validating agentic collection structure..."
 	@uv run python scripts/validate_structure.py
+	@echo "Validating skill docs links..."
+	@uv run python scripts/validate_skill_doc_links.py
+	@echo "Validating docs tree links..."
+	@uv run python scripts/validate_docs_tree_links.py
 	@echo "Validating collection compliance (.catalog/)..."
 	@uv run python scripts/validate_collection_compliance.py
 	@echo "✓ Validation passed!"

SKILL_DESIGN_PRINCIPLES.md

@@ -181,6 +181,12 @@ Every skill MUST include a **Dependencies** section listing:
 **Official:** [Title - Product](https://docs.redhat.com/...)
 ```
 
+**Skill-local docs rule (required):**
+- Internal docs consumed by a skill must resolve under that skill directory using `docs/...` links.
+- Do **not** use upward traversal links to pack-level docs such as `../docs/...`, `../../docs/...`, or `../../../docs/...`.
+- Shared docs may be reused via symlinks under `skills/<skill>/docs/...`.
+- Pack-level `docs/INDEX.md` and `docs/SOURCES.md` may exist for repository navigation/source attribution, but skills must not depend on them at execution time.
+
 **Rationale**: Makes dependencies explicit for debugging and troubleshooting.
 
 ## 6. Human-in-the-Loop Requirements

ocp-admin/README.md

@@ -269,15 +269,15 @@ Create OpenShift clusters using the Red Hat Assisted Installer with full workflo
 - `alter_static_network_config_nmstate_for_host` - Apply static networking to hosts
 
 **Documentation**:
-- [Input Validation Guide](docs/input-validation-guide.md) - Parameter requirements
-- [Providers](docs/providers.md) - Infrastructure providers (baremetal, vsphere, oci, nutanix)
-- [Platforms](docs/platforms.md) - OpenShift types (SNO, OCP, ROSA, ARO, OSD)
-- [Networking](docs/networking.md) - Network configuration, VIPs, CIDR planning
-- [Static Networking Guide](docs/static-networking-guide.md) - NMState configuration
-- [Host Requirements](docs/host-requirements.md) - Hardware specifications
-- [Examples](docs/examples.md) - 10 real-world configurations
-- [Troubleshooting](docs/troubleshooting.md) - Common errors and solutions
-- [INDEX.md](docs/INDEX.md) - Complete documentation navigation
+- [Input Validation Guide](skills/cluster-creator/docs/input-validation-guide.md) - Parameter requirements
+- [Providers](skills/cluster-creator/docs/providers.md) - Infrastructure providers (baremetal, vsphere, oci, nutanix)
+- [Platforms](skills/cluster-creator/docs/platforms.md) - OpenShift types (SNO, OCP, ROSA, ARO, OSD)
+- [Networking](skills/cluster-creator/docs/networking.md) - Network configuration, VIPs, CIDR planning
+- [Static Networking Guide](skills/cluster-creator/docs/static-networking-guide.md) - NMState configuration
+- [Host Requirements](skills/cluster-creator/docs/host-requirements.md) - Hardware specifications
+- [Examples](skills/cluster-creator/docs/examples.md) - 10 real-world configurations
+- [Troubleshooting](skills/cluster-creator/docs/troubleshooting.md) - Common errors and solutions
+- [INDEX.md](skills/cluster-creator/docs/INDEX.md) - Complete documentation navigation
 
 ### 2. **cluster-inventory** - Cluster Discovery and Status
 
@@ -359,7 +359,7 @@ export KUBECONFIG=/tmp/cluster-report-kubeconfig
 # In Claude Code: /cluster-report
 ```
 
-See [docs/multi-cluster-auth.md](docs/multi-cluster-auth.md) for the full setup guide, token rotation, and troubleshooting.
+See [skills/cluster-report/docs/multi-cluster-auth.md](skills/cluster-report/docs/multi-cluster-auth.md) for the full setup guide, token rotation, and troubleshooting.
 
 ---
 
@@ -533,27 +533,26 @@ Result: Real-time installation status without leaving Claude
 The pack includes 17 comprehensive reference documents covering all aspects of OpenShift administration:
 
 ### Installation & Planning
-- [Input Validation Guide](docs/input-validation-guide.md) - Parameter validation rules
-- [Providers](docs/providers.md) - Infrastructure providers (baremetal, vsphere, oci, nutanix)
-- [Platforms](docs/platforms.md) - OpenShift platform types (SNO, OCP, ROSA, ARO, OSD)
-- [Host Requirements](docs/host-requirements.md) - Hardware specifications
-- [Networking](docs/networking.md) - Network configuration, VIPs, CIDR planning, Egress IP, Multus, SR-IOV, Dual-Stack
-- [Static Networking Guide](docs/static-networking-guide.md) - NMState configuration (Simple/Advanced/Manual modes)
-- [Storage](docs/storage.md) - Storage options, CSI drivers, ODF
-- [Examples](docs/examples.md) - 10 real-world cluster configurations
+- [Input Validation Guide](skills/cluster-creator/docs/input-validation-guide.md) - Parameter validation rules
+- [Providers](skills/cluster-creator/docs/providers.md) - Infrastructure providers (baremetal, vsphere, oci, nutanix)
+- [Platforms](skills/cluster-creator/docs/platforms.md) - OpenShift platform types (SNO, OCP, ROSA, ARO, OSD)
+- [Host Requirements](skills/cluster-creator/docs/host-requirements.md) - Hardware specifications
+- [Networking](skills/cluster-creator/docs/networking.md) - Network configuration, VIPs, CIDR planning, Egress IP, Multus, SR-IOV, Dual-Stack
+- [Static Networking Guide](skills/cluster-creator/docs/static-networking-guide.md) - NMState configuration (Simple/Advanced/Manual modes)
+- [Storage](skills/cluster-creator/docs/storage.md) - Storage options, CSI drivers, ODF
+- [Examples](skills/cluster-creator/docs/examples.md) - 10 real-world cluster configurations
 
 ### Post-Installation
-- [Credentials Management](docs/credentials-management.md) - Authentication, OAuth, RBAC, identity providers
-- [Multi-Cluster Authentication](docs/multi-cluster-auth.md) - Service account tokens, kubeconfig merging
-- [Day-2 Operations](docs/day-2-operations.md) - Monitoring, logging, updates, scaling, maintenance
-- [Certificate Management](docs/certificate-management.md) - Certificate lifecycle and rotation
-- [Backup and Restore](docs/backup-restore.md) - etcd backup/restore procedures
+- [Credentials Management](skills/cluster-creator/docs/credentials-management.md) - Authentication, OAuth, RBAC, identity providers
+- [Multi-Cluster Authentication](skills/cluster-report/docs/multi-cluster-auth.md) - Service account tokens, kubeconfig merging
+- [Day-2 Operations](skills/cluster-creator/docs/day-2-operations.md) - Monitoring, logging, updates, scaling, maintenance
+- [Certificate Management](skills/cluster-creator/docs/certificate-management.md) - Certificate lifecycle and rotation
+- [Backup and Restore](skills/cluster-creator/docs/backup-restore.md) - etcd backup/restore procedures
 
 ### Reference & Troubleshooting
-- [Quick Reference](docs/quick-reference.md) - Common `oc` commands and scenarios
-- [Troubleshooting](docs/troubleshooting.md) - Common errors and resolutions
-- [INDEX.md](docs/INDEX.md) - Complete documentation navigation
-- [TODO_LIST.md](docs/TODO_LIST.md) - Future documentation topics
+- [Quick Reference](skills/cluster-creator/docs/quick-reference.md) - Common `oc` commands and scenarios
+- [Troubleshooting](skills/cluster-creator/docs/troubleshooting.md) - Common errors and resolutions
+- [INDEX.md](skills/cluster-creator/docs/INDEX.md) - Complete documentation navigation
 
 **All documentation**:
 - Derived from official Red Hat sources
@@ -606,7 +605,7 @@ The pack includes 17 comprehensive reference documents covering all aspects of O
 1. Check host requirements match cluster type (SNO vs HA)
 2. Verify VIPs are in same subnet as nodes
 3. Review cluster events: Use `cluster-inventory` skill
-4. Check troubleshooting guide: [docs/troubleshooting.md](docs/troubleshooting.md)
+4. Check troubleshooting guide: [skills/cluster-creator/docs/troubleshooting.md](skills/cluster-creator/docs/troubleshooting.md)
 5. Verify network connectivity between hosts
 
 ### Skills Not Triggering
@@ -645,8 +644,7 @@ ocp-admin/
 │   ├── certificate-management.md
 │   ├── backup-restore.md
 │   ├── quick-reference.md
-│   ├── troubleshooting.md
-│   └── TODO_LIST.md
+│   └── troubleshooting.md
 ├── skills/
 │   ├── cluster-creator/SKILL.md      # End-to-end cluster deployment
 │   ├── cluster-inventory/SKILL.md    # Cluster discovery and status

ocp-admin/skills/cluster-creator/SKILL.md

@@ -125,7 +125,7 @@ TaskCreate(subject: "#12 Retrieve credentials", description: "Download kubeconfi
 
 **Prerequisites Check**: Execute verification from Prerequisites section.
 
-**On Failure**: If prerequisites fail, consult [troubleshooting.md](../../docs/troubleshooting.md) for common setup issues, then stop and report error to user.
+**On Failure**: If prerequisites fail, consult [troubleshooting.md](docs/troubleshooting.md) for common setup issues, then stop and report error to user.
 
 ---
 
@@ -141,11 +141,11 @@ Use AskUserQuestion to collect configuration:
    - **SNO**: Platform is automatically set to "none" (Red Hat API requirement) - DO NOT ask user
    - **HA**: Ask user to select: baremetal, vsphere, nutanix, or oci
 3. **Version**: Call `list_versions`, show "Full Support" versions
-4. **Cluster Name**: Ask "Cluster name? (or type your custom name directly)" - Suggest based on context (e.g., "prod-ocp", "edge-site-01", "dev-cluster") OR user types custom name. Validate: 1-54 chars, lowercase/numbers/hyphens, starts with letter ([validation](../../docs/input-validation-guide.md#cluster-name))
-5. **Base Domain**: Ask "Base domain? (e.g., example.com)" - User types domain directly. Validate: valid DNS format ([validation](../../docs/input-validation-guide.md#base-domain))
+4. **Cluster Name**: Ask "Cluster name? (or type your custom name directly)" - Suggest based on context (e.g., "prod-ocp", "edge-site-01", "dev-cluster") OR user types custom name. Validate: 1-54 chars, lowercase/numbers/hyphens, starts with letter ([validation](docs/input-validation-guide.md#cluster-name))
+5. **Base Domain**: Ask "Base domain? (e.g., example.com)" - User types domain directly. Validate: valid DNS format ([validation](docs/input-validation-guide.md#base-domain))
 6. **CPU Arch**: x86_64 (default), aarch64, ppc64le, s390x
 7. **SSH Key**: Ask "How to provide?" Options: Generate new (recommended, save to cluster folder) | Existing file (path) | Paste | ⚠️ None (warn, require "PROCEED WITHOUT SSH" confirmation)
-8. **Hardware**: Confirm servers meeting [host requirements](../../docs/host-requirements.md) are ready
+8. **Hardware**: Confirm servers meeting [host requirements](docs/host-requirements.md) are ready
 
 **Create folder**: `/tmp/{cluster_name}.{base_domain}/` (permissions 700), display location
 
@@ -157,7 +157,7 @@ Use AskUserQuestion to collect configuration:
 
 Ask: "How to configure networking?" Options: 1) Default (auto CIDRs, DHCP, HA: ask VIPs) | 2) Custom CIDRs (ask each, validate) | 3) Static IPs (Simple/Advanced/Manual modes, use `generate_nmstate_yaml`) | 4) Describe requirements (AI infers from text like "192.168.1.0/24, 100 pods")
 
-**Reference**: [Networking Guide](../../docs/networking.md) has detailed examples for all 4 options
+**Reference**: [Networking Guide](docs/networking.md) has detailed examples for all 4 options
 
 ---
 
@@ -166,7 +166,7 @@ Ask: "How to configure networking?" Options: 1) Default (auto CIDRs, DHCP, HA: a
 
 Display summary: Cluster Name, Type (SNO/HA), Version, Platform, Architecture, Domain, VIPs (if applicable), Networking (DHCP/Static)
 
-**Reference**: [Examples](../../docs/examples.md)
+**Reference**: [Examples](docs/examples.md)
 
 ---
 
@@ -210,7 +210,7 @@ Ask: "Review configuration. Ready to create cluster definition?"
 - **Parameters**: `{cluster_id, nmstate_yaml, mac_address}`
 - **Verify**: Call `list_static_network_config`
 
-**Reference**: [Providers](../../docs/providers.md), [Networking](../../docs/networking.md)
+**Reference**: [Providers](docs/providers.md), [Networking](docs/networking.md)
 
 ---
 
@@ -269,7 +269,7 @@ Display: "Waiting for you to boot hosts. When ready, say 'check for hosts'."
 
 **If insufficient**: Ask to wait/proceed/abort.
 
-**Reference**: [Host Requirements](../../docs/host-requirements.md)
+**Reference**: [Host Requirements](docs/host-requirements.md)
 
 ---
 
@@ -297,7 +297,7 @@ Display: "Waiting for you to boot hosts. When ready, say 'check for hosts'."
 
 **If validation fails**:
 1. Display errors from cluster_info
-2. Consult [troubleshooting.md](../../docs/troubleshooting.md) for cluster status meanings and validation error diagnosis
+2. Consult [troubleshooting.md](docs/troubleshooting.md) for cluster status meanings and validation error diagnosis
 3. Offer options: fix/wait/abort
 
 ---
@@ -337,7 +337,7 @@ Ask: "Start installation now?"
 
 **On Error**:
 1. Display error message
-2. Consult [troubleshooting.md](../../docs/troubleshooting.md) for error diagnosis
+2. Consult [troubleshooting.md](docs/troubleshooting.md) for error diagnosis
 3. If error is new/undocumented, note it for future documentation
 4. Offer retry/abort
 
@@ -367,7 +367,7 @@ Background monitoring? (yes/no)
 **If manual**: Wait for "check status", then call `cluster_info`, display progress, repeat until "installed" or "error"
 
 **If installation fails**:
-1. Consult [troubleshooting.md](../../docs/troubleshooting.md) for cluster lifecycle states and common installation errors
+1. Consult [troubleshooting.md](docs/troubleshooting.md) for cluster lifecycle states and common installation errors
 2. Download logs (`cluster_logs_download_url`) for detailed diagnosis
 3. Offer options: diagnose errors, cleanup and retry, or manual intervention
 4. **Cleanup**: Failed cluster remains in Assisted Installer - use cluster_info to verify state before deleting or retrying with same cluster_id
@@ -384,7 +384,7 @@ Display: "Installation Completed! Cluster: {cluster_name}, Status: installed, Ti
 ### Step 17: Retrieve Credentials
 
 **Document Consultation** (REQUIRED):
-1. **Action**: Read [credentials-management.md](../../docs/credentials-management.md)
+1. **Action**: Read [credentials-management.md](docs/credentials-management.md)
 2. **Output**: "I consulted credentials-management.md for credential download procedures."
 
 **Execute**: Follow download procedure to save kubeconfig and kubeadmin-password to `/tmp/{cluster_name}.{base_domain}/` (permissions 600)
@@ -432,7 +432,7 @@ Congratulations!
 
 **If yes**: Ask destination (default: ~/.kube/clusters/), copy folder with `cp -r`, set permissions 700, display confirmation
 
-**Reference**: [Credentials Management](../../docs/credentials-management.md)
+**Reference**: [Credentials Management](docs/credentials-management.md)
 
 ---
 
@@ -454,27 +454,27 @@ All tools from `openshift-self-managed` MCP server:
 
 ### Reference Documentation
 **Configuration & Validation**:
-- [Input Validation Guide](../../docs/input-validation-guide.md) - Parameter requirements
-- [Networking](../../docs/networking.md) - Network configuration, VIPs, CIDR planning
-- [Static Networking Guide](../../docs/static-networking-guide.md) - NMState configuration
+- [Input Validation Guide](docs/input-validation-guide.md) - Parameter requirements
+- [Networking](docs/networking.md) - Network configuration, VIPs, CIDR planning
+- [Static Networking Guide](docs/static-networking-guide.md) - NMState configuration
 
 **Platform & Infrastructure**:
-- [Providers](../../docs/providers.md) - Infrastructure providers (baremetal, vsphere, oci, nutanix)
-- [Platforms](../../docs/platforms.md) - OpenShift types (SNO, OCP, ROSA, ARO, OSD)
-- [Host Requirements](../../docs/host-requirements.md) - Hardware specs by cluster type
+- [Providers](docs/providers.md) - Infrastructure providers (baremetal, vsphere, oci, nutanix)
+- [Platforms](docs/platforms.md) - OpenShift types (SNO, OCP, ROSA, ARO, OSD)
+- [Host Requirements](docs/host-requirements.md) - Hardware specs by cluster type
 
 **Post-Installation**:
-- [Credentials Management](../../docs/credentials-management.md) - Kubeconfig and authentication setup
-- [Identity Providers](../../docs/idp.md) - HTPasswd, LDAP, OIDC, GitHub authentication
-- [RBAC](../../docs/rbac.md) - Role-Based Access Control and Security Context Constraints
-- [Certificate Rotation](../../docs/certificate-rotation.md) - Certificate management and renewal
-- [Security Checklist](../../docs/security-checklist.md) - Post-installation security verification
-- [Storage](../../docs/storage.md) - Storage options by provider
-- [Examples](../../docs/examples.md) - Configuration examples
-- [Troubleshooting](../../docs/troubleshooting.md) - Common errors and resolutions
+- [Credentials Management](docs/credentials-management.md) - Kubeconfig and authentication setup
+- [Identity Providers](docs/idp.md) - HTPasswd, LDAP, OIDC, GitHub authentication
+- [RBAC](docs/rbac.md) - Role-Based Access Control and Security Context Constraints
+- [Certificate Rotation](docs/certificate-rotation.md) - Certificate management and renewal
+- [Security Checklist](docs/security-checklist.md) - Post-installation security verification
+- [Storage](docs/storage.md) - Storage options by provider
+- [Examples](docs/examples.md) - Configuration examples
+- [Troubleshooting](docs/troubleshooting.md) - Common errors and resolutions
 
 **Complete Documentation Guide**:
-- **[Documentation Index](../../docs/INDEX.md)** - Navigate all ocp-admin documentation (consult for topics not explicitly referenced above)
+- **[Documentation Index](docs/INDEX.md)** - Navigate all ocp-admin documentation (consult for topics not explicitly referenced above)
 
 ---
 
@@ -496,4 +496,4 @@ This skill performs critical, irreversible operations requiring explicit user co
 
 **Result**: SNO deployed in ~45 min. All artifacts in `/tmp/edge-site-01.edge.local/`: kubeconfig, kubeadmin-password, SSH keys, discovery.iso, ISO URL, metadata
 
-**More Examples**: See [examples.md](../../docs/examples.md) for HA, static networking, multi-cluster, and air-gapped configurations.
+**More Examples**: See [examples.md](docs/examples.md) for HA, static networking, multi-cluster, and air-gapped configurations.

ocp-admin/skills/cluster-creator/docs/multi-cluster-auth.md

@@ -0,0 +1 @@
+../../cluster-report/docs/multi-cluster-auth.md