diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0a1b6db8..0378401d 100644 --- a/CONTRIBUTING.md +++ b/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 /skills//SKILL.md + + # Skill docs tree validation (skills docs markdown links) + uv run python scripts/validate_docs_tree_links.py /skills//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 /skills//SKILL.md` +- [ ] Skill docs tree links validation passed: `uv run python scripts/validate_docs_tree_links.py /skills//SKILL.md` - [ ] Tested skill locally by invoking it in Claude Code - [ ] Reviewed generated skill for accuracy - [ ] No credentials exposed in skill documentation diff --git a/Makefile b/Makefile index 60eac6e1..68c91ac4 100644 --- a/Makefile +++ b/Makefile @@ -41,6 +41,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 "Validating MCP tool references (skips gracefully without podman)..." diff --git a/SKILL_DESIGN_PRINCIPLES.md b/SKILL_DESIGN_PRINCIPLES.md index f1733950..f742b9ad 100644 --- a/SKILL_DESIGN_PRINCIPLES.md +++ b/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//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 diff --git a/ocp-admin/README.md b/ocp-admin/README.md index b2709493..ec8a2d35 100644 --- a/ocp-admin/README.md +++ b/ocp-admin/README.md @@ -276,15 +276,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 @@ -447,7 +447,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. --- @@ -647,27 +647,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 @@ -720,7 +719,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 @@ -759,8 +758,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 diff --git a/ocp-admin/skills/cluster-creator/SKILL.md b/ocp-admin/skills/cluster-creator/SKILL.md index 2bf0d057..0f832060 100644 --- a/ocp-admin/skills/cluster-creator/SKILL.md +++ b/ocp-admin/skills/cluster-creator/SKILL.md @@ -126,7 +126,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. --- @@ -142,11 +142,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 @@ -158,7 +158,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 --- @@ -167,7 +167,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) --- @@ -211,7 +211,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) --- @@ -270,7 +270,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) --- @@ -298,7 +298,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 --- @@ -338,7 +338,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 @@ -368,7 +368,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 @@ -385,7 +385,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) @@ -433,7 +433,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) --- @@ -455,27 +455,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) --- @@ -497,4 +497,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. diff --git a/ocp-admin/docs/INDEX.md b/ocp-admin/skills/cluster-creator/docs/INDEX.md similarity index 100% rename from ocp-admin/docs/INDEX.md rename to ocp-admin/skills/cluster-creator/docs/INDEX.md diff --git a/ocp-admin/docs/backup-restore.md b/ocp-admin/skills/cluster-creator/docs/backup-restore.md similarity index 100% rename from ocp-admin/docs/backup-restore.md rename to ocp-admin/skills/cluster-creator/docs/backup-restore.md diff --git a/ocp-admin/docs/certificate-management.md b/ocp-admin/skills/cluster-creator/docs/certificate-management.md similarity index 100% rename from ocp-admin/docs/certificate-management.md rename to ocp-admin/skills/cluster-creator/docs/certificate-management.md diff --git a/ocp-admin/docs/certificate-rotation.md b/ocp-admin/skills/cluster-creator/docs/certificate-rotation.md similarity index 100% rename from ocp-admin/docs/certificate-rotation.md rename to ocp-admin/skills/cluster-creator/docs/certificate-rotation.md diff --git a/ocp-admin/docs/credentials-management.md b/ocp-admin/skills/cluster-creator/docs/credentials-management.md similarity index 100% rename from ocp-admin/docs/credentials-management.md rename to ocp-admin/skills/cluster-creator/docs/credentials-management.md diff --git a/ocp-admin/docs/database-connection-management.md b/ocp-admin/skills/cluster-creator/docs/database-connection-management.md similarity index 100% rename from ocp-admin/docs/database-connection-management.md rename to ocp-admin/skills/cluster-creator/docs/database-connection-management.md diff --git a/ocp-admin/docs/day-2-operations.md b/ocp-admin/skills/cluster-creator/docs/day-2-operations.md similarity index 100% rename from ocp-admin/docs/day-2-operations.md rename to ocp-admin/skills/cluster-creator/docs/day-2-operations.md diff --git a/ocp-admin/docs/etcd-maintenance.md b/ocp-admin/skills/cluster-creator/docs/etcd-maintenance.md similarity index 100% rename from ocp-admin/docs/etcd-maintenance.md rename to ocp-admin/skills/cluster-creator/docs/etcd-maintenance.md diff --git a/ocp-admin/docs/examples.md b/ocp-admin/skills/cluster-creator/docs/examples.md similarity index 100% rename from ocp-admin/docs/examples.md rename to ocp-admin/skills/cluster-creator/docs/examples.md diff --git a/ocp-admin/docs/host-requirements.md b/ocp-admin/skills/cluster-creator/docs/host-requirements.md similarity index 100% rename from ocp-admin/docs/host-requirements.md rename to ocp-admin/skills/cluster-creator/docs/host-requirements.md diff --git a/ocp-admin/docs/idp.md b/ocp-admin/skills/cluster-creator/docs/idp.md similarity index 100% rename from ocp-admin/docs/idp.md rename to ocp-admin/skills/cluster-creator/docs/idp.md diff --git a/ocp-admin/docs/input-validation-guide.md b/ocp-admin/skills/cluster-creator/docs/input-validation-guide.md similarity index 100% rename from ocp-admin/docs/input-validation-guide.md rename to ocp-admin/skills/cluster-creator/docs/input-validation-guide.md diff --git a/ocp-admin/skills/cluster-creator/docs/multi-cluster-auth.md b/ocp-admin/skills/cluster-creator/docs/multi-cluster-auth.md new file mode 120000 index 00000000..c50a7889 --- /dev/null +++ b/ocp-admin/skills/cluster-creator/docs/multi-cluster-auth.md @@ -0,0 +1 @@ +../../cluster-report/docs/multi-cluster-auth.md \ No newline at end of file diff --git a/ocp-admin/docs/networking.md b/ocp-admin/skills/cluster-creator/docs/networking.md similarity index 100% rename from ocp-admin/docs/networking.md rename to ocp-admin/skills/cluster-creator/docs/networking.md diff --git a/ocp-admin/docs/platforms.md b/ocp-admin/skills/cluster-creator/docs/platforms.md similarity index 100% rename from ocp-admin/docs/platforms.md rename to ocp-admin/skills/cluster-creator/docs/platforms.md diff --git a/ocp-admin/docs/providers.md b/ocp-admin/skills/cluster-creator/docs/providers.md similarity index 100% rename from ocp-admin/docs/providers.md rename to ocp-admin/skills/cluster-creator/docs/providers.md diff --git a/ocp-admin/docs/pvc-capacity-planning.md b/ocp-admin/skills/cluster-creator/docs/pvc-capacity-planning.md similarity index 100% rename from ocp-admin/docs/pvc-capacity-planning.md rename to ocp-admin/skills/cluster-creator/docs/pvc-capacity-planning.md diff --git a/ocp-admin/docs/quick-reference.md b/ocp-admin/skills/cluster-creator/docs/quick-reference.md similarity index 100% rename from ocp-admin/docs/quick-reference.md rename to ocp-admin/skills/cluster-creator/docs/quick-reference.md diff --git a/ocp-admin/docs/rbac.md b/ocp-admin/skills/cluster-creator/docs/rbac.md similarity index 100% rename from ocp-admin/docs/rbac.md rename to ocp-admin/skills/cluster-creator/docs/rbac.md diff --git a/ocp-admin/docs/security-checklist.md b/ocp-admin/skills/cluster-creator/docs/security-checklist.md similarity index 100% rename from ocp-admin/docs/security-checklist.md rename to ocp-admin/skills/cluster-creator/docs/security-checklist.md diff --git a/ocp-admin/docs/static-networking-guide.md b/ocp-admin/skills/cluster-creator/docs/static-networking-guide.md similarity index 100% rename from ocp-admin/docs/static-networking-guide.md rename to ocp-admin/skills/cluster-creator/docs/static-networking-guide.md diff --git a/ocp-admin/docs/storage.md b/ocp-admin/skills/cluster-creator/docs/storage.md similarity index 100% rename from ocp-admin/docs/storage.md rename to ocp-admin/skills/cluster-creator/docs/storage.md diff --git a/ocp-admin/docs/troubleshooting.md b/ocp-admin/skills/cluster-creator/docs/troubleshooting.md similarity index 100% rename from ocp-admin/docs/troubleshooting.md rename to ocp-admin/skills/cluster-creator/docs/troubleshooting.md diff --git a/ocp-admin/skills/cluster-inventory/SKILL.md b/ocp-admin/skills/cluster-inventory/SKILL.md index 0cc5d71e..8eea57cc 100644 --- a/ocp-admin/skills/cluster-inventory/SKILL.md +++ b/ocp-admin/skills/cluster-inventory/SKILL.md @@ -238,10 +238,10 @@ Execute when user requests events, troubleshoots errors, or needs installation l - Future: cluster-installer, cluster-deletion ### Reference Documentation -- [troubleshooting.md](../../docs/troubleshooting.md) - Cluster status and error diagnosis -- [PVC Capacity Planning](../../docs/pvc-capacity-planning.md) - Consult when cluster storage details show high PVC usage or approaching capacity -- [Database Connection Management](../../docs/database-connection-management.md) - Consult when cluster workloads include PostgreSQL with high connection usage -- **[Documentation Index](../../docs/INDEX.md)** - Complete guide to all ocp-admin documentation (consult for topics not explicitly referenced above) +- [troubleshooting.md](docs/troubleshooting.md) - Cluster status and error diagnosis +- [PVC Capacity Planning](docs/pvc-capacity-planning.md) - Consult when cluster storage details show high PVC usage or approaching capacity +- [Database Connection Management](docs/database-connection-management.md) - Consult when cluster workloads include PostgreSQL with high connection usage +- **[Documentation Index](docs/INDEX.md)** - Complete guide to all ocp-admin documentation (consult for topics not explicitly referenced above) ## Example Usage diff --git a/ocp-admin/skills/cluster-inventory/docs/INDEX.md b/ocp-admin/skills/cluster-inventory/docs/INDEX.md new file mode 120000 index 00000000..dc8236cf --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/docs/INDEX.md @@ -0,0 +1 @@ +../../cluster-creator/docs/INDEX.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/backup-restore.md b/ocp-admin/skills/cluster-inventory/docs/backup-restore.md new file mode 120000 index 00000000..69a2c4d7 --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/docs/backup-restore.md @@ -0,0 +1 @@ +../../cluster-creator/docs/backup-restore.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/certificate-rotation.md b/ocp-admin/skills/cluster-inventory/docs/certificate-rotation.md new file mode 120000 index 00000000..f24dab8f --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/docs/certificate-rotation.md @@ -0,0 +1 @@ +../../cluster-creator/docs/certificate-rotation.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/credentials-management.md b/ocp-admin/skills/cluster-inventory/docs/credentials-management.md new file mode 120000 index 00000000..3a168f1e --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/docs/credentials-management.md @@ -0,0 +1 @@ +../../cluster-creator/docs/credentials-management.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/database-connection-management.md b/ocp-admin/skills/cluster-inventory/docs/database-connection-management.md new file mode 120000 index 00000000..5cd634fe --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/docs/database-connection-management.md @@ -0,0 +1 @@ +../../cluster-creator/docs/database-connection-management.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/day-2-operations.md b/ocp-admin/skills/cluster-inventory/docs/day-2-operations.md new file mode 120000 index 00000000..f81391c7 --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/docs/day-2-operations.md @@ -0,0 +1 @@ +../../cluster-creator/docs/day-2-operations.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/etcd-maintenance.md b/ocp-admin/skills/cluster-inventory/docs/etcd-maintenance.md new file mode 120000 index 00000000..0ac3e5a8 --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/docs/etcd-maintenance.md @@ -0,0 +1 @@ +../../cluster-creator/docs/etcd-maintenance.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/examples.md b/ocp-admin/skills/cluster-inventory/docs/examples.md new file mode 120000 index 00000000..ff790b2e --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/docs/examples.md @@ -0,0 +1 @@ +../../cluster-creator/docs/examples.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/host-requirements.md b/ocp-admin/skills/cluster-inventory/docs/host-requirements.md new file mode 120000 index 00000000..940ac361 --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/docs/host-requirements.md @@ -0,0 +1 @@ +../../cluster-creator/docs/host-requirements.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/idp.md b/ocp-admin/skills/cluster-inventory/docs/idp.md new file mode 120000 index 00000000..6ff039bc --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/docs/idp.md @@ -0,0 +1 @@ +../../cluster-creator/docs/idp.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/input-validation-guide.md b/ocp-admin/skills/cluster-inventory/docs/input-validation-guide.md new file mode 120000 index 00000000..7fe632b8 --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/docs/input-validation-guide.md @@ -0,0 +1 @@ +../../cluster-creator/docs/input-validation-guide.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/multi-cluster-auth.md b/ocp-admin/skills/cluster-inventory/docs/multi-cluster-auth.md new file mode 120000 index 00000000..c50a7889 --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/docs/multi-cluster-auth.md @@ -0,0 +1 @@ +../../cluster-report/docs/multi-cluster-auth.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/networking.md b/ocp-admin/skills/cluster-inventory/docs/networking.md new file mode 120000 index 00000000..74cf579c --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/docs/networking.md @@ -0,0 +1 @@ +../../cluster-creator/docs/networking.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/platforms.md b/ocp-admin/skills/cluster-inventory/docs/platforms.md new file mode 120000 index 00000000..1705928b --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/docs/platforms.md @@ -0,0 +1 @@ +../../cluster-creator/docs/platforms.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/providers.md b/ocp-admin/skills/cluster-inventory/docs/providers.md new file mode 120000 index 00000000..a9736c66 --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/docs/providers.md @@ -0,0 +1 @@ +../../cluster-creator/docs/providers.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/pvc-capacity-planning.md b/ocp-admin/skills/cluster-inventory/docs/pvc-capacity-planning.md new file mode 120000 index 00000000..fc0f73fc --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/docs/pvc-capacity-planning.md @@ -0,0 +1 @@ +../../cluster-creator/docs/pvc-capacity-planning.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/quick-reference.md b/ocp-admin/skills/cluster-inventory/docs/quick-reference.md new file mode 120000 index 00000000..19cf9f54 --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/docs/quick-reference.md @@ -0,0 +1 @@ +../../cluster-creator/docs/quick-reference.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/rbac.md b/ocp-admin/skills/cluster-inventory/docs/rbac.md new file mode 120000 index 00000000..19e4d531 --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/docs/rbac.md @@ -0,0 +1 @@ +../../cluster-creator/docs/rbac.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/security-checklist.md b/ocp-admin/skills/cluster-inventory/docs/security-checklist.md new file mode 120000 index 00000000..539e3143 --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/docs/security-checklist.md @@ -0,0 +1 @@ +../../cluster-creator/docs/security-checklist.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/static-networking-guide.md b/ocp-admin/skills/cluster-inventory/docs/static-networking-guide.md new file mode 120000 index 00000000..dff4db1b --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/docs/static-networking-guide.md @@ -0,0 +1 @@ +../../cluster-creator/docs/static-networking-guide.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/storage.md b/ocp-admin/skills/cluster-inventory/docs/storage.md new file mode 120000 index 00000000..f0d664da --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/docs/storage.md @@ -0,0 +1 @@ +../../cluster-creator/docs/storage.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/troubleshooting.md b/ocp-admin/skills/cluster-inventory/docs/troubleshooting.md new file mode 120000 index 00000000..66df404a --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/docs/troubleshooting.md @@ -0,0 +1 @@ +../../cluster-creator/docs/troubleshooting.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/SKILL.md b/ocp-admin/skills/cluster-report/SKILL.md index c4a8db28..c8a56989 100644 --- a/ocp-admin/skills/cluster-report/SKILL.md +++ b/ocp-admin/skills/cluster-report/SKILL.md @@ -60,7 +60,7 @@ This skill uses `openshift-administration` MCP server exclusively. This server p **Required Environment Variables**: `KUBECONFIG` — must contain at least one cluster context. Two or more recommended for comparison. -**Multi-Cluster Setup**: For large-scale deployments using service account tokens instead of interactive `oc login`, see [multi-cluster-auth.md](../../docs/multi-cluster-auth.md) and the [build-kubeconfig.py](../../scripts/cluster-report/build-kubeconfig.py) helper script. +**Multi-Cluster Setup**: For large-scale deployments using service account tokens instead of interactive `oc login`, see [multi-cluster-auth.md](docs/multi-cluster-auth.md) and the [build-kubeconfig.py](../../scripts/cluster-report/build-kubeconfig.py) helper script. **Helper Scripts** (Python 3, stdlib only — auditable, do not reimplement): - [`assemble.py`](../../scripts/cluster-report/assemble.py) — resolves `$file` references into complete raw data JSON @@ -328,11 +328,11 @@ Render the structured JSON output as markdown using this template: ### Operational Alerts -⚠️ **etcd**: If any cluster reports etcd fragmentation ratio > 4.0 or DB size approaching quota, see [etcd-maintenance.md](../../docs/etcd-maintenance.md) for defragmentation procedure. +⚠️ **etcd**: If any cluster reports etcd fragmentation ratio > 4.0 or DB size approaching quota, see [etcd-maintenance.md](docs/etcd-maintenance.md) for defragmentation procedure. -⚠️ **PVC Capacity**: If any PVC usage exceeds 80% or `predict_linear` forecasts capacity exhaustion within 24h, see [pvc-capacity-planning.md](../../docs/pvc-capacity-planning.md) for expansion workflow. +⚠️ **PVC Capacity**: If any PVC usage exceeds 80% or `predict_linear` forecasts capacity exhaustion within 24h, see [pvc-capacity-planning.md](docs/pvc-capacity-planning.md) for expansion workflow. -⚠️ **Database Connections**: If PostgreSQL active connections exceed 80% of `max_connections`, see [database-connection-management.md](../../docs/database-connection-management.md) for saturation diagnosis and connection pooling. +⚠️ **Database Connections**: If PostgreSQL active connections exceed 80% of `max_connections`, see [database-connection-management.md](docs/database-connection-management.md) for saturation diagnosis and connection pooling. ``` ### Step 5: Cleanup @@ -384,12 +384,12 @@ Would you like to: - `/cluster-inventory` - List and inspect individual clusters ### Reference Documentation -- [Credentials Management](../../docs/credentials-management.md) - KUBECONFIG setup and multi-cluster contexts -- [Multi-Cluster Auth](../../docs/multi-cluster-auth.md) - Service account token configuration for large deployments -- [etcd Maintenance](../../docs/etcd-maintenance.md) - Consult when etcd fragmentation ratio appears elevated in cluster metrics -- [PVC Capacity Planning](../../docs/pvc-capacity-planning.md) - Consult when PVC usage is high or approaching capacity -- [Database Connection Management](../../docs/database-connection-management.md) - Consult when PostgreSQL connection usage is high -- **[Documentation Index](../../docs/INDEX.md)** - Complete guide to all ocp-admin documentation (consult for topics not explicitly referenced above) +- [Credentials Management](docs/credentials-management.md) - KUBECONFIG setup and multi-cluster contexts +- [Multi-Cluster Auth](docs/multi-cluster-auth.md) - Service account token configuration for large deployments +- [etcd Maintenance](docs/etcd-maintenance.md) - Consult when etcd fragmentation ratio appears elevated in cluster metrics +- [PVC Capacity Planning](docs/pvc-capacity-planning.md) - Consult when PVC usage is high or approaching capacity +- [Database Connection Management](docs/database-connection-management.md) - Consult when PostgreSQL connection usage is high +- **[Documentation Index](docs/INDEX.md)** - Complete guide to all ocp-admin documentation (consult for topics not explicitly referenced above) ## Error Handling diff --git a/ocp-admin/skills/cluster-report/docs/INDEX.md b/ocp-admin/skills/cluster-report/docs/INDEX.md new file mode 120000 index 00000000..dc8236cf --- /dev/null +++ b/ocp-admin/skills/cluster-report/docs/INDEX.md @@ -0,0 +1 @@ +../../cluster-creator/docs/INDEX.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/backup-restore.md b/ocp-admin/skills/cluster-report/docs/backup-restore.md new file mode 120000 index 00000000..69a2c4d7 --- /dev/null +++ b/ocp-admin/skills/cluster-report/docs/backup-restore.md @@ -0,0 +1 @@ +../../cluster-creator/docs/backup-restore.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/certificate-rotation.md b/ocp-admin/skills/cluster-report/docs/certificate-rotation.md new file mode 120000 index 00000000..f24dab8f --- /dev/null +++ b/ocp-admin/skills/cluster-report/docs/certificate-rotation.md @@ -0,0 +1 @@ +../../cluster-creator/docs/certificate-rotation.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/credentials-management.md b/ocp-admin/skills/cluster-report/docs/credentials-management.md new file mode 120000 index 00000000..3a168f1e --- /dev/null +++ b/ocp-admin/skills/cluster-report/docs/credentials-management.md @@ -0,0 +1 @@ +../../cluster-creator/docs/credentials-management.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/database-connection-management.md b/ocp-admin/skills/cluster-report/docs/database-connection-management.md new file mode 120000 index 00000000..5cd634fe --- /dev/null +++ b/ocp-admin/skills/cluster-report/docs/database-connection-management.md @@ -0,0 +1 @@ +../../cluster-creator/docs/database-connection-management.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/day-2-operations.md b/ocp-admin/skills/cluster-report/docs/day-2-operations.md new file mode 120000 index 00000000..f81391c7 --- /dev/null +++ b/ocp-admin/skills/cluster-report/docs/day-2-operations.md @@ -0,0 +1 @@ +../../cluster-creator/docs/day-2-operations.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/etcd-maintenance.md b/ocp-admin/skills/cluster-report/docs/etcd-maintenance.md new file mode 120000 index 00000000..0ac3e5a8 --- /dev/null +++ b/ocp-admin/skills/cluster-report/docs/etcd-maintenance.md @@ -0,0 +1 @@ +../../cluster-creator/docs/etcd-maintenance.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/examples.md b/ocp-admin/skills/cluster-report/docs/examples.md new file mode 120000 index 00000000..ff790b2e --- /dev/null +++ b/ocp-admin/skills/cluster-report/docs/examples.md @@ -0,0 +1 @@ +../../cluster-creator/docs/examples.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/host-requirements.md b/ocp-admin/skills/cluster-report/docs/host-requirements.md new file mode 120000 index 00000000..940ac361 --- /dev/null +++ b/ocp-admin/skills/cluster-report/docs/host-requirements.md @@ -0,0 +1 @@ +../../cluster-creator/docs/host-requirements.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/idp.md b/ocp-admin/skills/cluster-report/docs/idp.md new file mode 120000 index 00000000..6ff039bc --- /dev/null +++ b/ocp-admin/skills/cluster-report/docs/idp.md @@ -0,0 +1 @@ +../../cluster-creator/docs/idp.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/input-validation-guide.md b/ocp-admin/skills/cluster-report/docs/input-validation-guide.md new file mode 120000 index 00000000..7fe632b8 --- /dev/null +++ b/ocp-admin/skills/cluster-report/docs/input-validation-guide.md @@ -0,0 +1 @@ +../../cluster-creator/docs/input-validation-guide.md \ No newline at end of file diff --git a/ocp-admin/docs/multi-cluster-auth.md b/ocp-admin/skills/cluster-report/docs/multi-cluster-auth.md similarity index 100% rename from ocp-admin/docs/multi-cluster-auth.md rename to ocp-admin/skills/cluster-report/docs/multi-cluster-auth.md diff --git a/ocp-admin/skills/cluster-report/docs/networking.md b/ocp-admin/skills/cluster-report/docs/networking.md new file mode 120000 index 00000000..74cf579c --- /dev/null +++ b/ocp-admin/skills/cluster-report/docs/networking.md @@ -0,0 +1 @@ +../../cluster-creator/docs/networking.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/platforms.md b/ocp-admin/skills/cluster-report/docs/platforms.md new file mode 120000 index 00000000..1705928b --- /dev/null +++ b/ocp-admin/skills/cluster-report/docs/platforms.md @@ -0,0 +1 @@ +../../cluster-creator/docs/platforms.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/providers.md b/ocp-admin/skills/cluster-report/docs/providers.md new file mode 120000 index 00000000..a9736c66 --- /dev/null +++ b/ocp-admin/skills/cluster-report/docs/providers.md @@ -0,0 +1 @@ +../../cluster-creator/docs/providers.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/pvc-capacity-planning.md b/ocp-admin/skills/cluster-report/docs/pvc-capacity-planning.md new file mode 120000 index 00000000..fc0f73fc --- /dev/null +++ b/ocp-admin/skills/cluster-report/docs/pvc-capacity-planning.md @@ -0,0 +1 @@ +../../cluster-creator/docs/pvc-capacity-planning.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/quick-reference.md b/ocp-admin/skills/cluster-report/docs/quick-reference.md new file mode 120000 index 00000000..19cf9f54 --- /dev/null +++ b/ocp-admin/skills/cluster-report/docs/quick-reference.md @@ -0,0 +1 @@ +../../cluster-creator/docs/quick-reference.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/rbac.md b/ocp-admin/skills/cluster-report/docs/rbac.md new file mode 120000 index 00000000..19e4d531 --- /dev/null +++ b/ocp-admin/skills/cluster-report/docs/rbac.md @@ -0,0 +1 @@ +../../cluster-creator/docs/rbac.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/security-checklist.md b/ocp-admin/skills/cluster-report/docs/security-checklist.md new file mode 120000 index 00000000..539e3143 --- /dev/null +++ b/ocp-admin/skills/cluster-report/docs/security-checklist.md @@ -0,0 +1 @@ +../../cluster-creator/docs/security-checklist.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/static-networking-guide.md b/ocp-admin/skills/cluster-report/docs/static-networking-guide.md new file mode 120000 index 00000000..dff4db1b --- /dev/null +++ b/ocp-admin/skills/cluster-report/docs/static-networking-guide.md @@ -0,0 +1 @@ +../../cluster-creator/docs/static-networking-guide.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/storage.md b/ocp-admin/skills/cluster-report/docs/storage.md new file mode 120000 index 00000000..f0d664da --- /dev/null +++ b/ocp-admin/skills/cluster-report/docs/storage.md @@ -0,0 +1 @@ +../../cluster-creator/docs/storage.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/troubleshooting.md b/ocp-admin/skills/cluster-report/docs/troubleshooting.md new file mode 120000 index 00000000..66df404a --- /dev/null +++ b/ocp-admin/skills/cluster-report/docs/troubleshooting.md @@ -0,0 +1 @@ +../../cluster-creator/docs/troubleshooting.md \ No newline at end of file diff --git a/rh-ai-engineer/README.md b/rh-ai-engineer/README.md index c5f309da..ff8ee5f8 100644 --- a/rh-ai-engineer/README.md +++ b/rh-ai-engineer/README.md @@ -72,7 +72,7 @@ export AI_OBSERVABILITY_MCP_URL=https://$(oc get route aiobs-mcp-server-route -n | NVIDIA NIM | Optimized inference with TensorRT-LLM on NVIDIA GPUs | `/nim-setup` | | Caikit+TGIS | Models in Caikit format with gRPC API | Model conversion | -See [supported-runtimes.md](docs/references/supported-runtimes.md) for detailed runtime comparison. +See [supported-runtimes.md](skills/serving-runtime-config/docs/references/supported-runtimes.md) for detailed runtime comparison. ## Supported Models @@ -86,4 +86,4 @@ Common models with known hardware profiles: | Mixtral 8x7B | 46.7B MoE | 2x A100 80GB | vLLM | | Mistral 7B | 7B | 1x (16GB VRAM) | vLLM | -See [known-model-profiles.md](docs/references/known-model-profiles.md) for full profiles. Models not listed are supported via live documentation lookup. +See [known-model-profiles.md](skills/model-deploy/docs/references/known-model-profiles.md) for full profiles. Models not listed are supported via live documentation lookup. diff --git a/rh-ai-engineer/skills/ai-observability/SKILL.md b/rh-ai-engineer/skills/ai-observability/SKILL.md index 3e4b2240..22af178e 100644 --- a/rh-ai-engineer/skills/ai-observability/SKILL.md +++ b/rh-ai-engineer/skills/ai-observability/SKILL.md @@ -411,8 +411,8 @@ See [Prerequisites](#prerequisites) for the complete list of required and option - `/model-monitor` - TrustyAI bias/drift metrics (complements infrastructure observability) ### Reference Documentation -- [known-model-profiles.md](../../docs/references/known-model-profiles.md) - Expected performance baselines for common models -- [supported-runtimes.md](../../docs/references/supported-runtimes.md) - Runtime capabilities and known limitations +- [known-model-profiles.md](docs/references/known-model-profiles.md) - Expected performance baselines for common models +- [supported-runtimes.md](docs/references/supported-runtimes.md) - Runtime capabilities and known limitations ## Critical: Human-in-the-Loop Requirements diff --git a/rh-ai-engineer/skills/ai-observability/docs/references/known-model-profiles.md b/rh-ai-engineer/skills/ai-observability/docs/references/known-model-profiles.md new file mode 120000 index 00000000..b4dea51f --- /dev/null +++ b/rh-ai-engineer/skills/ai-observability/docs/references/known-model-profiles.md @@ -0,0 +1 @@ +../../../model-deploy/docs/references/known-model-profiles.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/ai-observability/docs/references/live-doc-lookup.md b/rh-ai-engineer/skills/ai-observability/docs/references/live-doc-lookup.md new file mode 120000 index 00000000..024ac933 --- /dev/null +++ b/rh-ai-engineer/skills/ai-observability/docs/references/live-doc-lookup.md @@ -0,0 +1 @@ +../../../references/live-doc-lookup.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/ai-observability/docs/references/supported-runtimes.md b/rh-ai-engineer/skills/ai-observability/docs/references/supported-runtimes.md new file mode 120000 index 00000000..38211dbf --- /dev/null +++ b/rh-ai-engineer/skills/ai-observability/docs/references/supported-runtimes.md @@ -0,0 +1 @@ +../../../serving-runtime-config/docs/references/supported-runtimes.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/debug-inference/SKILL.md b/rh-ai-engineer/skills/debug-inference/SKILL.md index 7dcf0328..399878ae 100644 --- a/rh-ai-engineer/skills/debug-inference/SKILL.md +++ b/rh-ai-engineer/skills/debug-inference/SKILL.md @@ -342,8 +342,8 @@ See [Prerequisites](#prerequisites) for the complete list of required and option - `/model-monitor` - Check if TrustyAI monitoring detected issues before they became failures ### Reference Documentation -- [known-model-profiles.md](../../docs/references/known-model-profiles.md) - Correct resource sizing for common models -- [supported-runtimes.md](../../docs/references/supported-runtimes.md) - Runtime capabilities and known limitations +- [known-model-profiles.md](docs/references/known-model-profiles.md) - Correct resource sizing for common models +- [supported-runtimes.md](docs/references/supported-runtimes.md) - Runtime capabilities and known limitations - [live-doc-lookup.md](../references/live-doc-lookup.md) - Protocol for looking up unrecognized errors ## Critical: Human-in-the-Loop Requirements diff --git a/rh-ai-engineer/skills/debug-inference/docs/references/known-model-profiles.md b/rh-ai-engineer/skills/debug-inference/docs/references/known-model-profiles.md new file mode 120000 index 00000000..b4dea51f --- /dev/null +++ b/rh-ai-engineer/skills/debug-inference/docs/references/known-model-profiles.md @@ -0,0 +1 @@ +../../../model-deploy/docs/references/known-model-profiles.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/debug-inference/docs/references/live-doc-lookup.md b/rh-ai-engineer/skills/debug-inference/docs/references/live-doc-lookup.md new file mode 120000 index 00000000..024ac933 --- /dev/null +++ b/rh-ai-engineer/skills/debug-inference/docs/references/live-doc-lookup.md @@ -0,0 +1 @@ +../../../references/live-doc-lookup.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/debug-inference/docs/references/supported-runtimes.md b/rh-ai-engineer/skills/debug-inference/docs/references/supported-runtimes.md new file mode 120000 index 00000000..38211dbf --- /dev/null +++ b/rh-ai-engineer/skills/debug-inference/docs/references/supported-runtimes.md @@ -0,0 +1 @@ +../../../serving-runtime-config/docs/references/supported-runtimes.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/model-deploy/SKILL.md b/rh-ai-engineer/skills/model-deploy/SKILL.md index 9627483b..c3aaf891 100644 --- a/rh-ai-engineer/skills/model-deploy/SKILL.md +++ b/rh-ai-engineer/skills/model-deploy/SKILL.md @@ -129,8 +129,8 @@ After the environment is validated, collect remaining deployment configuration. ### Step 3: Determine Runtime **Document Consultation** (read before selecting runtime): -1. **Action**: Read [supported-runtimes.md](../../docs/references/supported-runtimes.md) using the Read tool to understand runtime capabilities and selection criteria -2. **Output to user**: "I consulted [supported-runtimes.md](../../docs/references/supported-runtimes.md) to understand runtime capabilities." +1. **Action**: Read [supported-runtimes.md](docs/references/supported-runtimes.md) using the Read tool to understand runtime capabilities and selection criteria +2. **Output to user**: "I consulted [supported-runtimes.md](docs/references/supported-runtimes.md) to understand runtime capabilities." **Runtime Selection Logic:** @@ -145,8 +145,8 @@ After the environment is validated, collect remaining deployment configuration. ### Step 4: Look Up Model Hardware Profile **Document Consultation** (read before determining hardware requirements): -1. **Action**: Read [known-model-profiles.md](../../docs/references/known-model-profiles.md) using the Read tool to find hardware profile for the requested model -2. **Output to user**: "I consulted [known-model-profiles.md](../../docs/references/known-model-profiles.md) to find hardware requirements for [model-name]." +1. **Action**: Read [known-model-profiles.md](docs/references/known-model-profiles.md) using the Read tool to find hardware profile for the requested model +2. **Output to user**: "I consulted [known-model-profiles.md](docs/references/known-model-profiles.md) to find hardware requirements for [model-name]." **If model IS in known-model-profiles.md:** - Extract: GPU count, GPU type, VRAM, key vLLM args @@ -441,8 +441,8 @@ See [Prerequisites](#prerequisites) for the complete list of required and option - `/guardrails-config` - Add content safety guardrails to LLM deployments ### Reference Documentation -- [known-model-profiles.md](../../docs/references/known-model-profiles.md) - Hardware profiles for common models -- [supported-runtimes.md](../../docs/references/supported-runtimes.md) - Runtime capabilities and selection criteria +- [known-model-profiles.md](docs/references/known-model-profiles.md) - Hardware profiles for common models +- [supported-runtimes.md](docs/references/supported-runtimes.md) - Runtime capabilities and selection criteria - [live-doc-lookup.md](../references/live-doc-lookup.md) - Protocol for fetching specs for unknown models ## Critical: Human-in-the-Loop Requirements @@ -459,4 +459,4 @@ See [skill-conventions.md](../references/skill-conventions.md) for general HITL ## Example Usage -See [model-deploy examples](../../docs/examples/model-deploy.md) for complete deployment walkthroughs (vLLM and NIM). +See [model-deploy examples](docs/examples/model-deploy.md) for complete deployment walkthroughs (vLLM and NIM). diff --git a/rh-ai-engineer/docs/examples/model-deploy.md b/rh-ai-engineer/skills/model-deploy/docs/examples/model-deploy.md similarity index 100% rename from rh-ai-engineer/docs/examples/model-deploy.md rename to rh-ai-engineer/skills/model-deploy/docs/examples/model-deploy.md diff --git a/rh-ai-engineer/docs/references/known-model-profiles.md b/rh-ai-engineer/skills/model-deploy/docs/references/known-model-profiles.md similarity index 100% rename from rh-ai-engineer/docs/references/known-model-profiles.md rename to rh-ai-engineer/skills/model-deploy/docs/references/known-model-profiles.md diff --git a/rh-ai-engineer/skills/model-deploy/docs/references/live-doc-lookup.md b/rh-ai-engineer/skills/model-deploy/docs/references/live-doc-lookup.md new file mode 120000 index 00000000..024ac933 --- /dev/null +++ b/rh-ai-engineer/skills/model-deploy/docs/references/live-doc-lookup.md @@ -0,0 +1 @@ +../../../references/live-doc-lookup.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/model-deploy/docs/references/supported-runtimes.md b/rh-ai-engineer/skills/model-deploy/docs/references/supported-runtimes.md new file mode 120000 index 00000000..38211dbf --- /dev/null +++ b/rh-ai-engineer/skills/model-deploy/docs/references/supported-runtimes.md @@ -0,0 +1 @@ +../../../serving-runtime-config/docs/references/supported-runtimes.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/nim-setup/SKILL.md b/rh-ai-engineer/skills/nim-setup/SKILL.md index 7dc34eaf..1d6bc161 100644 --- a/rh-ai-engineer/skills/nim-setup/SKILL.md +++ b/rh-ai-engineer/skills/nim-setup/SKILL.md @@ -81,8 +81,8 @@ If `rhoai` MCP is not available, skip this check and proceed. ### Step 1: Verify GPU Operator and Node Feature Discovery **Document Consultation** (read before verifying operators): -1. **Action**: Read [supported-runtimes.md](../../docs/references/supported-runtimes.md) using the Read tool to understand NIM platform requirements -2. **Output to user**: "I consulted [supported-runtimes.md](../../docs/references/supported-runtimes.md) to understand NIM platform requirements." +1. **Action**: Read [supported-runtimes.md](docs/references/supported-runtimes.md) using the Read tool to understand NIM platform requirements +2. **Output to user**: "I consulted [supported-runtimes.md](docs/references/supported-runtimes.md) to understand NIM platform requirements." Check that the NVIDIA GPU Operator and NFD Operator are installed and healthy. @@ -363,7 +363,7 @@ When handing off to `/model-deploy` after NIM setup, note these NIM-specific con - **GPU tolerations**: GPU nodes are almost always tainted in production. `/model-deploy` will automatically detect and add tolerations after deployment. ### Reference Documentation -- [supported-runtimes.md](../../docs/references/supported-runtimes.md) - NIM runtime capabilities and requirements +- [supported-runtimes.md](docs/references/supported-runtimes.md) - NIM runtime capabilities and requirements - [live-doc-lookup.md](../references/live-doc-lookup.md) - Protocol for fetching current RHOAI/NIM documentation ## Critical: Human-in-the-Loop Requirements @@ -378,4 +378,4 @@ See [skill-conventions.md](../references/skill-conventions.md) for general HITL ## Example Usage -See [nim-setup examples](../../docs/examples/nim-setup.md) for a complete first-time NIM setup walkthrough. +See [nim-setup examples](docs/examples/nim-setup.md) for a complete first-time NIM setup walkthrough. diff --git a/rh-ai-engineer/docs/examples/nim-setup.md b/rh-ai-engineer/skills/nim-setup/docs/examples/nim-setup.md similarity index 100% rename from rh-ai-engineer/docs/examples/nim-setup.md rename to rh-ai-engineer/skills/nim-setup/docs/examples/nim-setup.md diff --git a/rh-ai-engineer/skills/nim-setup/docs/references/supported-runtimes.md b/rh-ai-engineer/skills/nim-setup/docs/references/supported-runtimes.md new file mode 120000 index 00000000..38211dbf --- /dev/null +++ b/rh-ai-engineer/skills/nim-setup/docs/references/supported-runtimes.md @@ -0,0 +1 @@ +../../../serving-runtime-config/docs/references/supported-runtimes.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/serving-runtime-config/SKILL.md b/rh-ai-engineer/skills/serving-runtime-config/SKILL.md index 3970a74f..84a22df3 100644 --- a/rh-ai-engineer/skills/serving-runtime-config/SKILL.md +++ b/rh-ai-engineer/skills/serving-runtime-config/SKILL.md @@ -87,8 +87,8 @@ Verify the user-specified namespace is an RHOAI Data Science Project. - **Intent**: New runtime from scratch, or customize an existing one? **Document Consultation** (read before listing runtimes): -1. **Action**: Read [supported-runtimes.md](../../docs/references/supported-runtimes.md) using the Read tool to understand available runtimes and their capabilities -2. **Output to user**: "I consulted [supported-runtimes.md](../../docs/references/supported-runtimes.md) to understand available runtimes." +1. **Action**: Read [supported-runtimes.md](docs/references/supported-runtimes.md) using the Read tool to understand available runtimes and their capabilities +2. **Output to user**: "I consulted [supported-runtimes.md](docs/references/supported-runtimes.md) to understand available runtimes." **MCP Tool**: `list_serving_runtimes` (from rhoai) @@ -290,7 +290,7 @@ See [Prerequisites](#prerequisites) for the complete list of required and option - `/debug-inference` - Troubleshoot InferenceService failures after deployment ### Reference Documentation -- [supported-runtimes.md](../../docs/references/supported-runtimes.md) - Runtime capabilities and model format names +- [supported-runtimes.md](docs/references/supported-runtimes.md) - Runtime capabilities and model format names - [live-doc-lookup.md](../references/live-doc-lookup.md) - Protocol for fetching specs for unknown frameworks ## Critical: Human-in-the-Loop Requirements diff --git a/rh-ai-engineer/docs/references/supported-runtimes.md b/rh-ai-engineer/skills/serving-runtime-config/docs/references/supported-runtimes.md similarity index 100% rename from rh-ai-engineer/docs/references/supported-runtimes.md rename to rh-ai-engineer/skills/serving-runtime-config/docs/references/supported-runtimes.md diff --git a/rh-automation/skills/execution-risk-analyzer/SKILL.md b/rh-automation/skills/execution-risk-analyzer/SKILL.md index 3b1ebae9..9fcec4da 100644 --- a/rh-automation/skills/execution-risk-analyzer/SKILL.md +++ b/rh-automation/skills/execution-risk-analyzer/SKILL.md @@ -46,7 +46,7 @@ Do NOT use when: **CRITICAL**: Document consultation MUST happen BEFORE any MCP tool invocations. **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [execution-governance.md](../../docs/aap/execution-governance.md) using the Read tool to understand inventory risk classification, extra_vars safety scanning, and governance controls +1. **Action**: Read [execution-governance.md](docs/aap/execution-governance.md) using the Read tool to understand inventory risk classification, extra_vars safety scanning, and governance controls 2. **Output to user**: "I consulted [execution-governance.md](docs/aap/execution-governance.md) which cites Red Hat's Security Best Practices and Job Templates documentation for execution governance controls." ### Step 2: Identify the Job Template @@ -244,7 +244,7 @@ Per Red Hat's *Security Best Practices* (Ch. 15, Sec. 15.1.4): "Remove user acce - `execution-summary` - Audit trail ### Reference Documentation -- [execution-governance.md](../../docs/aap/execution-governance.md) - Risk classification and safety scanning reference +- [execution-governance.md](docs/aap/execution-governance.md) - Risk classification and safety scanning reference ## Example Usage diff --git a/rh-automation/docs/aap/README.md b/rh-automation/skills/execution-risk-analyzer/docs/aap/README.md similarity index 100% rename from rh-automation/docs/aap/README.md rename to rh-automation/skills/execution-risk-analyzer/docs/aap/README.md diff --git a/rh-automation/docs/aap/execution-governance.md b/rh-automation/skills/execution-risk-analyzer/docs/aap/execution-governance.md similarity index 100% rename from rh-automation/docs/aap/execution-governance.md rename to rh-automation/skills/execution-risk-analyzer/docs/aap/execution-governance.md diff --git a/rh-automation/skills/execution-risk-analyzer/docs/aap/governance-readiness.md b/rh-automation/skills/execution-risk-analyzer/docs/aap/governance-readiness.md new file mode 120000 index 00000000..f3187dee --- /dev/null +++ b/rh-automation/skills/execution-risk-analyzer/docs/aap/governance-readiness.md @@ -0,0 +1 @@ +../../../governance-readiness-assessor/docs/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/skills/execution-risk-analyzer/docs/aap/job-troubleshooting.md b/rh-automation/skills/execution-risk-analyzer/docs/aap/job-troubleshooting.md new file mode 120000 index 00000000..1e59ab9b --- /dev/null +++ b/rh-automation/skills/execution-risk-analyzer/docs/aap/job-troubleshooting.md @@ -0,0 +1 @@ +../../../job-failure-analyzer/docs/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/skills/execution-risk-analyzer/docs/references/error-classification.md b/rh-automation/skills/execution-risk-analyzer/docs/references/error-classification.md new file mode 120000 index 00000000..71b66be0 --- /dev/null +++ b/rh-automation/skills/execution-risk-analyzer/docs/references/error-classification.md @@ -0,0 +1 @@ +../../../resolution-advisor/docs/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/execution-summary/docs/aap/execution-governance.md b/rh-automation/skills/execution-summary/docs/aap/execution-governance.md new file mode 120000 index 00000000..76d56e98 --- /dev/null +++ b/rh-automation/skills/execution-summary/docs/aap/execution-governance.md @@ -0,0 +1 @@ +../../../execution-risk-analyzer/docs/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/skills/execution-summary/docs/aap/governance-readiness.md b/rh-automation/skills/execution-summary/docs/aap/governance-readiness.md new file mode 120000 index 00000000..f3187dee --- /dev/null +++ b/rh-automation/skills/execution-summary/docs/aap/governance-readiness.md @@ -0,0 +1 @@ +../../../governance-readiness-assessor/docs/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/skills/execution-summary/docs/aap/job-troubleshooting.md b/rh-automation/skills/execution-summary/docs/aap/job-troubleshooting.md new file mode 120000 index 00000000..1e59ab9b --- /dev/null +++ b/rh-automation/skills/execution-summary/docs/aap/job-troubleshooting.md @@ -0,0 +1 @@ +../../../job-failure-analyzer/docs/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/skills/execution-summary/docs/references/error-classification.md b/rh-automation/skills/execution-summary/docs/references/error-classification.md new file mode 120000 index 00000000..71b66be0 --- /dev/null +++ b/rh-automation/skills/execution-summary/docs/references/error-classification.md @@ -0,0 +1 @@ +../../../resolution-advisor/docs/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/forensic-troubleshooter/SKILL.md b/rh-automation/skills/forensic-troubleshooter/SKILL.md index c8373c8a..a57aae9c 100644 --- a/rh-automation/skills/forensic-troubleshooter/SKILL.md +++ b/rh-automation/skills/forensic-troubleshooter/SKILL.md @@ -53,7 +53,7 @@ Do NOT use when: - Reports structured analysis with Red Hat citations **Document Consultation** (performed by the skill): -The job-failure-analyzer skill reads [job-troubleshooting.md](../../docs/aap/job-troubleshooting.md) and reports its consultation. +The job-failure-analyzer skill reads [job-troubleshooting.md](docs/aap/job-troubleshooting.md) and reports its consultation. ### 3. Correlate with Host Facts @@ -65,7 +65,7 @@ The job-failure-analyzer skill reads [job-troubleshooting.md](../../docs/aap/job - Reports correlation findings **Document Consultation** (performed by the skill): -The host-fact-inspector skill reads [job-troubleshooting.md](../../docs/aap/job-troubleshooting.md) for correlation patterns. +The host-fact-inspector skill reads [job-troubleshooting.md](docs/aap/job-troubleshooting.md) for correlation patterns. ### 4. Provide Resolution Advisory @@ -76,7 +76,7 @@ The host-fact-inspector skill reads [job-troubleshooting.md](../../docs/aap/job- - Identifies related governance gaps **Document Consultation** (performed by the skill): -The resolution-advisor skill reads [error-classification.md](../../docs/references/error-classification.md) and [job-troubleshooting.md](../../docs/aap/job-troubleshooting.md). +The resolution-advisor skill reads [error-classification.md](docs/references/error-classification.md) and [job-troubleshooting.md](docs/aap/job-troubleshooting.md). ### 5. Generate Execution Summary @@ -104,8 +104,8 @@ The resolution-advisor skill reads [error-classification.md](../../docs/referenc - `governance-assessor` - If root cause points to platform governance gaps ### Reference Documentation -- [job-troubleshooting.md](../../docs/aap/job-troubleshooting.md) - Event parsing, failure patterns, correlation -- [error-classification.md](../../docs/references/error-classification.md) - Error taxonomy and resolution paths +- [job-troubleshooting.md](docs/aap/job-troubleshooting.md) - Event parsing, failure patterns, correlation +- [error-classification.md](docs/references/error-classification.md) - Error taxonomy and resolution paths ## Example Usage diff --git a/rh-automation/skills/forensic-troubleshooter/docs/aap/execution-governance.md b/rh-automation/skills/forensic-troubleshooter/docs/aap/execution-governance.md new file mode 120000 index 00000000..76d56e98 --- /dev/null +++ b/rh-automation/skills/forensic-troubleshooter/docs/aap/execution-governance.md @@ -0,0 +1 @@ +../../../execution-risk-analyzer/docs/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/skills/forensic-troubleshooter/docs/aap/governance-readiness.md b/rh-automation/skills/forensic-troubleshooter/docs/aap/governance-readiness.md new file mode 120000 index 00000000..f3187dee --- /dev/null +++ b/rh-automation/skills/forensic-troubleshooter/docs/aap/governance-readiness.md @@ -0,0 +1 @@ +../../../governance-readiness-assessor/docs/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/skills/forensic-troubleshooter/docs/aap/job-troubleshooting.md b/rh-automation/skills/forensic-troubleshooter/docs/aap/job-troubleshooting.md new file mode 120000 index 00000000..1e59ab9b --- /dev/null +++ b/rh-automation/skills/forensic-troubleshooter/docs/aap/job-troubleshooting.md @@ -0,0 +1 @@ +../../../job-failure-analyzer/docs/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/skills/forensic-troubleshooter/docs/references/error-classification.md b/rh-automation/skills/forensic-troubleshooter/docs/references/error-classification.md new file mode 120000 index 00000000..71b66be0 --- /dev/null +++ b/rh-automation/skills/forensic-troubleshooter/docs/references/error-classification.md @@ -0,0 +1 @@ +../../../resolution-advisor/docs/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/governance-assessor/SKILL.md b/rh-automation/skills/governance-assessor/SKILL.md index 4e2cb917..f7e737e5 100644 --- a/rh-automation/skills/governance-assessor/SKILL.md +++ b/rh-automation/skills/governance-assessor/SKILL.md @@ -68,7 +68,7 @@ Do NOT use when: - Produces the structured Governance Readiness Report with Red Hat citations per domain, compound risk analysis, and prioritized fix order **Document Consultation** (performed by the skill): -The governance-readiness-assessor skill reads [governance-readiness.md](../../docs/aap/governance-readiness.md) and reports its consultation. +The governance-readiness-assessor skill reads [governance-readiness.md](docs/aap/governance-readiness.md) and reports its consultation. ### 3. Present Report and Offer Remediation @@ -108,7 +108,7 @@ Before creating or modifying any AAP resource: - `forensic-troubleshooter` - Follow-up: investigate failures found during assessment ### Reference Documentation -- [governance-readiness.md](../../docs/aap/governance-readiness.md) - 7-domain assessment framework +- [governance-readiness.md](docs/aap/governance-readiness.md) - 7-domain assessment framework ### Sample Reports - [sample-full-assessment.md](references/sample-full-assessment.md) - Full 7+1 domain assessment with compound risk analysis diff --git a/rh-automation/skills/governance-assessor/docs/aap/execution-governance.md b/rh-automation/skills/governance-assessor/docs/aap/execution-governance.md new file mode 120000 index 00000000..76d56e98 --- /dev/null +++ b/rh-automation/skills/governance-assessor/docs/aap/execution-governance.md @@ -0,0 +1 @@ +../../../execution-risk-analyzer/docs/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/skills/governance-assessor/docs/aap/governance-readiness.md b/rh-automation/skills/governance-assessor/docs/aap/governance-readiness.md new file mode 120000 index 00000000..f3187dee --- /dev/null +++ b/rh-automation/skills/governance-assessor/docs/aap/governance-readiness.md @@ -0,0 +1 @@ +../../../governance-readiness-assessor/docs/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/skills/governance-assessor/docs/aap/job-troubleshooting.md b/rh-automation/skills/governance-assessor/docs/aap/job-troubleshooting.md new file mode 120000 index 00000000..1e59ab9b --- /dev/null +++ b/rh-automation/skills/governance-assessor/docs/aap/job-troubleshooting.md @@ -0,0 +1 @@ +../../../job-failure-analyzer/docs/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/skills/governance-assessor/docs/references/error-classification.md b/rh-automation/skills/governance-assessor/docs/references/error-classification.md new file mode 120000 index 00000000..71b66be0 --- /dev/null +++ b/rh-automation/skills/governance-assessor/docs/references/error-classification.md @@ -0,0 +1 @@ +../../../resolution-advisor/docs/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/governance-executor/SKILL.md b/rh-automation/skills/governance-executor/SKILL.md index 052f4279..e73b5f60 100644 --- a/rh-automation/skills/governance-executor/SKILL.md +++ b/rh-automation/skills/governance-executor/SKILL.md @@ -57,7 +57,7 @@ Do NOT use when: - Reports risk assessment with Red Hat citations AND operational context **Document Consultation** (performed by the skill): -The execution-risk-analyzer skill reads [execution-governance.md](../../docs/aap/execution-governance.md) and reports its consultation. +The execution-risk-analyzer skill reads [execution-governance.md](docs/aap/execution-governance.md) and reports its consultation. **If secrets detected**: STOP. Report the finding and recommend using AAP credentials. @@ -109,7 +109,7 @@ The execution-risk-analyzer skill reads [execution-governance.md](../../docs/aap - `governance-assessor` - Pre-execution platform readiness check ### Reference Documentation -- [execution-governance.md](../../docs/aap/execution-governance.md) - Risk classification, check mode, rollback +- [execution-governance.md](docs/aap/execution-governance.md) - Risk classification, check mode, rollback ## Example Usage diff --git a/rh-automation/skills/governance-executor/docs/aap/execution-governance.md b/rh-automation/skills/governance-executor/docs/aap/execution-governance.md new file mode 120000 index 00000000..76d56e98 --- /dev/null +++ b/rh-automation/skills/governance-executor/docs/aap/execution-governance.md @@ -0,0 +1 @@ +../../../execution-risk-analyzer/docs/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/skills/governance-executor/docs/aap/governance-readiness.md b/rh-automation/skills/governance-executor/docs/aap/governance-readiness.md new file mode 120000 index 00000000..f3187dee --- /dev/null +++ b/rh-automation/skills/governance-executor/docs/aap/governance-readiness.md @@ -0,0 +1 @@ +../../../governance-readiness-assessor/docs/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/skills/governance-executor/docs/aap/job-troubleshooting.md b/rh-automation/skills/governance-executor/docs/aap/job-troubleshooting.md new file mode 120000 index 00000000..1e59ab9b --- /dev/null +++ b/rh-automation/skills/governance-executor/docs/aap/job-troubleshooting.md @@ -0,0 +1 @@ +../../../job-failure-analyzer/docs/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/skills/governance-executor/docs/references/error-classification.md b/rh-automation/skills/governance-executor/docs/references/error-classification.md new file mode 120000 index 00000000..71b66be0 --- /dev/null +++ b/rh-automation/skills/governance-executor/docs/references/error-classification.md @@ -0,0 +1 @@ +../../../resolution-advisor/docs/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/governance-readiness-assessor/SKILL.md b/rh-automation/skills/governance-readiness-assessor/SKILL.md index 5674ae28..95d7f5cd 100644 --- a/rh-automation/skills/governance-readiness-assessor/SKILL.md +++ b/rh-automation/skills/governance-readiness-assessor/SKILL.md @@ -60,7 +60,7 @@ Do NOT use when: **CRITICAL**: Document consultation MUST happen BEFORE any MCP tool invocations. **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [governance-readiness.md](../../docs/aap/governance-readiness.md) using the Read tool to understand the 7-domain assessment framework, Red Hat source citations, decision tables, and output template +1. **Action**: Read [governance-readiness.md](docs/aap/governance-readiness.md) using the Read tool to understand the 7-domain assessment framework, Red Hat source citations, decision tables, and output template 2. **Output to user**: "I consulted [governance-readiness.md](docs/aap/governance-readiness.md) to understand Red Hat's governance best practices for the 7-domain assessment framework." ### Step 1.5: Determine Assessment Scope @@ -287,7 +287,7 @@ For any domains with GAP or WARN status, offer to remediate using MCP write tool - `execution-summary` - Generate audit trail after assessment ### Reference Documentation -- [governance-readiness.md](../../docs/aap/governance-readiness.md) - The 7-domain assessment reference +- [governance-readiness.md](docs/aap/governance-readiness.md) - The 7-domain assessment reference ## Critical: Human-in-the-Loop Requirements diff --git a/rh-automation/skills/governance-readiness-assessor/docs/aap/execution-governance.md b/rh-automation/skills/governance-readiness-assessor/docs/aap/execution-governance.md new file mode 120000 index 00000000..76d56e98 --- /dev/null +++ b/rh-automation/skills/governance-readiness-assessor/docs/aap/execution-governance.md @@ -0,0 +1 @@ +../../../execution-risk-analyzer/docs/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/docs/aap/governance-readiness.md b/rh-automation/skills/governance-readiness-assessor/docs/aap/governance-readiness.md similarity index 100% rename from rh-automation/docs/aap/governance-readiness.md rename to rh-automation/skills/governance-readiness-assessor/docs/aap/governance-readiness.md diff --git a/rh-automation/skills/governance-readiness-assessor/docs/aap/job-troubleshooting.md b/rh-automation/skills/governance-readiness-assessor/docs/aap/job-troubleshooting.md new file mode 120000 index 00000000..1e59ab9b --- /dev/null +++ b/rh-automation/skills/governance-readiness-assessor/docs/aap/job-troubleshooting.md @@ -0,0 +1 @@ +../../../job-failure-analyzer/docs/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/skills/governance-readiness-assessor/docs/references/error-classification.md b/rh-automation/skills/governance-readiness-assessor/docs/references/error-classification.md new file mode 120000 index 00000000..71b66be0 --- /dev/null +++ b/rh-automation/skills/governance-readiness-assessor/docs/references/error-classification.md @@ -0,0 +1 @@ +../../../resolution-advisor/docs/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/governed-job-launcher/SKILL.md b/rh-automation/skills/governed-job-launcher/SKILL.md index 2dbe0fd1..d5d13967 100644 --- a/rh-automation/skills/governed-job-launcher/SKILL.md +++ b/rh-automation/skills/governed-job-launcher/SKILL.md @@ -46,7 +46,7 @@ Do NOT use when: **CRITICAL**: Document consultation MUST happen BEFORE any MCP tool invocations. **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [execution-governance.md](../../docs/aap/execution-governance.md) using the Read tool to understand check mode execution, interpretation, phased rollout, and rollback patterns +1. **Action**: Read [execution-governance.md](docs/aap/execution-governance.md) using the Read tool to understand check mode execution, interpretation, phased rollout, and rollback patterns 2. **Output to user**: "I consulted [execution-governance.md](docs/aap/execution-governance.md) to understand Red Hat's check mode behavior, rollback patterns, and phased rollout strategy." ### Step 2: Adapt Execution Strategy Based on Risk Signals @@ -280,7 +280,7 @@ If the job fails, offer rollback options per execution-governance.md: - `execution-summary` - Audit trail after launch ### Reference Documentation -- [execution-governance.md](../../docs/aap/execution-governance.md) - Check mode, rollback, phased rollout patterns +- [execution-governance.md](docs/aap/execution-governance.md) - Check mode, rollback, phased rollout patterns ## Critical: Human-in-the-Loop Requirements diff --git a/rh-automation/skills/governed-job-launcher/docs/aap/execution-governance.md b/rh-automation/skills/governed-job-launcher/docs/aap/execution-governance.md new file mode 120000 index 00000000..76d56e98 --- /dev/null +++ b/rh-automation/skills/governed-job-launcher/docs/aap/execution-governance.md @@ -0,0 +1 @@ +../../../execution-risk-analyzer/docs/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/skills/governed-job-launcher/docs/aap/governance-readiness.md b/rh-automation/skills/governed-job-launcher/docs/aap/governance-readiness.md new file mode 120000 index 00000000..f3187dee --- /dev/null +++ b/rh-automation/skills/governed-job-launcher/docs/aap/governance-readiness.md @@ -0,0 +1 @@ +../../../governance-readiness-assessor/docs/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/skills/governed-job-launcher/docs/aap/job-troubleshooting.md b/rh-automation/skills/governed-job-launcher/docs/aap/job-troubleshooting.md new file mode 120000 index 00000000..1e59ab9b --- /dev/null +++ b/rh-automation/skills/governed-job-launcher/docs/aap/job-troubleshooting.md @@ -0,0 +1 @@ +../../../job-failure-analyzer/docs/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/skills/governed-job-launcher/docs/references/error-classification.md b/rh-automation/skills/governed-job-launcher/docs/references/error-classification.md new file mode 120000 index 00000000..71b66be0 --- /dev/null +++ b/rh-automation/skills/governed-job-launcher/docs/references/error-classification.md @@ -0,0 +1 @@ +../../../resolution-advisor/docs/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/host-fact-inspector/SKILL.md b/rh-automation/skills/host-fact-inspector/SKILL.md index 375a94df..bf971eaa 100644 --- a/rh-automation/skills/host-fact-inspector/SKILL.md +++ b/rh-automation/skills/host-fact-inspector/SKILL.md @@ -45,7 +45,7 @@ Do NOT use when: **CRITICAL**: Document consultation MUST happen BEFORE any MCP tool invocations. **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [job-troubleshooting.md](../../docs/aap/job-troubleshooting.md) using the Read tool to understand the host fact correlation table and error-to-fact mapping +1. **Action**: Read [job-troubleshooting.md](docs/aap/job-troubleshooting.md) using the Read tool to understand the host fact correlation table and error-to-fact mapping 2. **Output to user**: "I consulted [job-troubleshooting.md](docs/aap/job-troubleshooting.md) to understand which host facts correlate with the identified failure patterns." ### Step 2: Look Up Affected Hosts @@ -136,7 +136,7 @@ If facts appear stale or missing, report this: "Host facts may not be current. F - `execution-summary` - Audit trail ### Reference Documentation -- [job-troubleshooting.md](../../docs/aap/job-troubleshooting.md) - Host fact correlation table +- [job-troubleshooting.md](docs/aap/job-troubleshooting.md) - Host fact correlation table ## Example Usage diff --git a/rh-automation/skills/host-fact-inspector/docs/aap/execution-governance.md b/rh-automation/skills/host-fact-inspector/docs/aap/execution-governance.md new file mode 120000 index 00000000..76d56e98 --- /dev/null +++ b/rh-automation/skills/host-fact-inspector/docs/aap/execution-governance.md @@ -0,0 +1 @@ +../../../execution-risk-analyzer/docs/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/skills/host-fact-inspector/docs/aap/governance-readiness.md b/rh-automation/skills/host-fact-inspector/docs/aap/governance-readiness.md new file mode 120000 index 00000000..f3187dee --- /dev/null +++ b/rh-automation/skills/host-fact-inspector/docs/aap/governance-readiness.md @@ -0,0 +1 @@ +../../../governance-readiness-assessor/docs/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/skills/host-fact-inspector/docs/aap/job-troubleshooting.md b/rh-automation/skills/host-fact-inspector/docs/aap/job-troubleshooting.md new file mode 120000 index 00000000..1e59ab9b --- /dev/null +++ b/rh-automation/skills/host-fact-inspector/docs/aap/job-troubleshooting.md @@ -0,0 +1 @@ +../../../job-failure-analyzer/docs/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/skills/host-fact-inspector/docs/references/error-classification.md b/rh-automation/skills/host-fact-inspector/docs/references/error-classification.md new file mode 120000 index 00000000..71b66be0 --- /dev/null +++ b/rh-automation/skills/host-fact-inspector/docs/references/error-classification.md @@ -0,0 +1 @@ +../../../resolution-advisor/docs/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/job-failure-analyzer/SKILL.md b/rh-automation/skills/job-failure-analyzer/SKILL.md index f9a771fb..42728c76 100644 --- a/rh-automation/skills/job-failure-analyzer/SKILL.md +++ b/rh-automation/skills/job-failure-analyzer/SKILL.md @@ -43,7 +43,7 @@ Do NOT use when: **CRITICAL**: Document consultation MUST happen BEFORE any MCP tool invocations. **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [job-troubleshooting.md](../../docs/aap/job-troubleshooting.md) using the Read tool to understand event extraction, failure patterns, host summary interpretation, and root cause classification +1. **Action**: Read [job-troubleshooting.md](docs/aap/job-troubleshooting.md) using the Read tool to understand event extraction, failure patterns, host summary interpretation, and root cause classification 2. **Output to user**: "I consulted [job-troubleshooting.md](docs/aap/job-troubleshooting.md) which references Red Hat's AAP 2.6 Troubleshooting Guide for failure analysis patterns." ### Step 2: Retrieve Job Status @@ -167,7 +167,7 @@ Sort events by `counter` and produce a chronological failure narrative: - `execution-summary` - Audit trail ### Reference Documentation -- [job-troubleshooting.md](../../docs/aap/job-troubleshooting.md) - Event parsing and failure patterns +- [job-troubleshooting.md](docs/aap/job-troubleshooting.md) - Event parsing and failure patterns ## Example Usage diff --git a/rh-automation/skills/job-failure-analyzer/docs/aap/execution-governance.md b/rh-automation/skills/job-failure-analyzer/docs/aap/execution-governance.md new file mode 120000 index 00000000..76d56e98 --- /dev/null +++ b/rh-automation/skills/job-failure-analyzer/docs/aap/execution-governance.md @@ -0,0 +1 @@ +../../../execution-risk-analyzer/docs/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/skills/job-failure-analyzer/docs/aap/governance-readiness.md b/rh-automation/skills/job-failure-analyzer/docs/aap/governance-readiness.md new file mode 120000 index 00000000..f3187dee --- /dev/null +++ b/rh-automation/skills/job-failure-analyzer/docs/aap/governance-readiness.md @@ -0,0 +1 @@ +../../../governance-readiness-assessor/docs/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/docs/aap/job-troubleshooting.md b/rh-automation/skills/job-failure-analyzer/docs/aap/job-troubleshooting.md similarity index 100% rename from rh-automation/docs/aap/job-troubleshooting.md rename to rh-automation/skills/job-failure-analyzer/docs/aap/job-troubleshooting.md diff --git a/rh-automation/skills/job-failure-analyzer/docs/references/error-classification.md b/rh-automation/skills/job-failure-analyzer/docs/references/error-classification.md new file mode 120000 index 00000000..71b66be0 --- /dev/null +++ b/rh-automation/skills/job-failure-analyzer/docs/references/error-classification.md @@ -0,0 +1 @@ +../../../resolution-advisor/docs/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/resolution-advisor/SKILL.md b/rh-automation/skills/resolution-advisor/SKILL.md index 6d2ba580..e85200fd 100644 --- a/rh-automation/skills/resolution-advisor/SKILL.md +++ b/rh-automation/skills/resolution-advisor/SKILL.md @@ -42,8 +42,8 @@ Do NOT use when: **CRITICAL**: Document consultation MUST happen BEFORE providing recommendations. **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [error-classification.md](../../docs/references/error-classification.md) using the Read tool to understand the error taxonomy, classification decision tree, and resolution path mapping -2. **Action**: Read [job-troubleshooting.md](../../docs/aap/job-troubleshooting.md) using the Read tool to understand failure pattern details and Red Hat source citations +1. **Action**: Read [error-classification.md](docs/references/error-classification.md) using the Read tool to understand the error taxonomy, classification decision tree, and resolution path mapping +2. **Action**: Read [job-troubleshooting.md](docs/aap/job-troubleshooting.md) using the Read tool to understand failure pattern details and Red Hat source citations 3. **Output to user**: "I consulted [error-classification.md](docs/references/error-classification.md) and [job-troubleshooting.md](docs/aap/job-troubleshooting.md) to determine the resolution path based on Red Hat's troubleshooting guidance." ### Step 2: Determine Resolution Path @@ -125,8 +125,8 @@ If the failure correlates with a governance readiness domain, recommend the user - `execution-summary` - Audit trail ### Reference Documentation -- [error-classification.md](../../docs/references/error-classification.md) - Error taxonomy and resolution paths -- [job-troubleshooting.md](../../docs/aap/job-troubleshooting.md) - Failure patterns and Red Hat citations +- [error-classification.md](docs/references/error-classification.md) - Error taxonomy and resolution paths +- [job-troubleshooting.md](docs/aap/job-troubleshooting.md) - Failure patterns and Red Hat citations ## Example Usage diff --git a/rh-automation/skills/resolution-advisor/docs/aap/execution-governance.md b/rh-automation/skills/resolution-advisor/docs/aap/execution-governance.md new file mode 120000 index 00000000..76d56e98 --- /dev/null +++ b/rh-automation/skills/resolution-advisor/docs/aap/execution-governance.md @@ -0,0 +1 @@ +../../../execution-risk-analyzer/docs/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/skills/resolution-advisor/docs/aap/governance-readiness.md b/rh-automation/skills/resolution-advisor/docs/aap/governance-readiness.md new file mode 120000 index 00000000..f3187dee --- /dev/null +++ b/rh-automation/skills/resolution-advisor/docs/aap/governance-readiness.md @@ -0,0 +1 @@ +../../../governance-readiness-assessor/docs/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/skills/resolution-advisor/docs/aap/job-troubleshooting.md b/rh-automation/skills/resolution-advisor/docs/aap/job-troubleshooting.md new file mode 120000 index 00000000..1e59ab9b --- /dev/null +++ b/rh-automation/skills/resolution-advisor/docs/aap/job-troubleshooting.md @@ -0,0 +1 @@ +../../../job-failure-analyzer/docs/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/docs/references/README.md b/rh-automation/skills/resolution-advisor/docs/references/README.md similarity index 100% rename from rh-automation/docs/references/README.md rename to rh-automation/skills/resolution-advisor/docs/references/README.md diff --git a/rh-automation/docs/references/error-classification.md b/rh-automation/skills/resolution-advisor/docs/references/error-classification.md similarity index 100% rename from rh-automation/docs/references/error-classification.md rename to rh-automation/skills/resolution-advisor/docs/references/error-classification.md diff --git a/rh-developer/.catalog/collection.json b/rh-developer/.catalog/collection.json index e8d972d4..e537f239 100644 --- a/rh-developer/.catalog/collection.json +++ b/rh-developer/.catalog/collection.json @@ -188,43 +188,43 @@ "resources": [ { "description": "OpenShift platform guides for developers and administrators.", - "embedded_doc": "docs/prerequisites.md", + "embedded_doc": "skills/validate-environment/docs/prerequisites.md", "title": "OpenShift documentation", "url": "https://docs.redhat.com/en/documentation/openshift_container_platform/" }, { "description": "Helm install, upgrade, and chart authoring.", - "embedded_doc": "docs/dynamic-validation.md", + "embedded_doc": "skills/recommend-image/docs/dynamic-validation.md", "title": "Helm documentation", "url": "https://helm.sh/docs/" }, { "description": "OpenShift builds and S2I concepts.", - "embedded_doc": "docs/builder-images.md", + "embedded_doc": "skills/detect-project/docs/builder-images.md", "title": "Source-to-Image (S2I)", "url": "https://docs.openshift.com/container-platform/latest/cicd/builds/understanding-image-builds.html" }, { "description": "UBI and base image guidance.", - "embedded_doc": "docs/image-selection-criteria.md", + "embedded_doc": "skills/recommend-image/docs/image-selection-criteria.md", "title": "Red Hat Universal Base Images", "url": "https://developers.redhat.com/products/rhel/ubi" }, { "description": "Local container workflows used by the pack.", - "embedded_doc": "docs/debugging-patterns.md", + "embedded_doc": "skills/debug-build/docs/debugging-patterns.md", "title": "Podman", "url": "https://docs.podman.io/" }, { "description": "Pack policy for confirmations and destructive actions.", - "embedded_doc": "docs/human-in-the-loop.md", + "embedded_doc": "skills/validate-environment/docs/human-in-the-loop.md", "title": "Human-in-the-loop (pack)", "url": "https://github.com/RHEcosystemAppEng/agentic-collections" }, { "description": "SSH/systemd patterns for `/rhel-deploy`.", - "embedded_doc": "docs/rhel-deployment.md", + "embedded_doc": "skills/rhel-deploy/docs/rhel-deployment.md", "title": "RHEL deployment notes (pack)", "url": "https://github.com/RHEcosystemAppEng/agentic-collections" } diff --git a/rh-developer/.catalog/collection.yaml b/rh-developer/.catalog/collection.yaml index 574d5bd8..cd72ea41 100644 --- a/rh-developer/.catalog/collection.yaml +++ b/rh-developer/.catalog/collection.yaml @@ -276,31 +276,31 @@ resources: - title: OpenShift documentation url: https://docs.redhat.com/en/documentation/openshift_container_platform/ description: OpenShift platform guides for developers and administrators. - embedded_doc: docs/prerequisites.md + embedded_doc: skills/validate-environment/docs/prerequisites.md - title: Helm documentation url: https://helm.sh/docs/ description: Helm install, upgrade, and chart authoring. - embedded_doc: docs/dynamic-validation.md + embedded_doc: skills/recommend-image/docs/dynamic-validation.md - title: Source-to-Image (S2I) url: https://docs.openshift.com/container-platform/latest/cicd/builds/understanding-image-builds.html description: OpenShift builds and S2I concepts. - embedded_doc: docs/builder-images.md + embedded_doc: skills/detect-project/docs/builder-images.md - title: Red Hat Universal Base Images url: https://developers.redhat.com/products/rhel/ubi description: UBI and base image guidance. - embedded_doc: docs/image-selection-criteria.md + embedded_doc: skills/recommend-image/docs/image-selection-criteria.md - title: Podman url: https://docs.podman.io/ description: Local container workflows used by the pack. - embedded_doc: docs/debugging-patterns.md + embedded_doc: skills/debug-build/docs/debugging-patterns.md - title: Human-in-the-loop (pack) url: https://github.com/RHEcosystemAppEng/agentic-collections description: Pack policy for confirmations and destructive actions. - embedded_doc: docs/human-in-the-loop.md + embedded_doc: skills/validate-environment/docs/human-in-the-loop.md - title: RHEL deployment notes (pack) url: https://github.com/RHEcosystemAppEng/agentic-collections description: SSH/systemd patterns for `/rhel-deploy`. - embedded_doc: docs/rhel-deployment.md + embedded_doc: skills/rhel-deploy/docs/rhel-deployment.md legal_resources: license_agreement_url: https://github.com/RHEcosystemAppEng/agentic-collections/blob/main/LICENSE privacy_policy_url: https://www.redhat.com/en/about/privacy-policy diff --git a/rh-developer/skills/containerize-deploy/SKILL.md b/rh-developer/skills/containerize-deploy/SKILL.md index 901c653f..0f8684f6 100644 --- a/rh-developer/skills/containerize-deploy/SKILL.md +++ b/rh-developer/skills/containerize-deploy/SKILL.md @@ -27,7 +27,7 @@ Use `/containerize-deploy` when a user wants a complete guided workflow from sou ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -471,9 +471,9 @@ Present a summary including: - `/debug-rhel` - RHEL deployment failures (systemd, SELinux, firewall) ### Reference Documentation -- [docs/builder-images.md](../../docs/builder-images.md) - Language detection, S2I builder images -- [docs/image-selection-criteria.md](../../docs/image-selection-criteria.md) - Image variant selection, LTS timelines -- [docs/python-s2i-entrypoints.md](../../docs/python-s2i-entrypoints.md) - Python S2I configuration -- [docs/rhel-deployment.md](../../docs/rhel-deployment.md) - RHEL host deployment -- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns and troubleshooting -- [docs/prerequisites.md](../../docs/prerequisites.md) - All required tools by skill +- [docs/builder-images.md](docs/builder-images.md) - Language detection, S2I builder images +- [docs/image-selection-criteria.md](docs/image-selection-criteria.md) - Image variant selection, LTS timelines +- [docs/python-s2i-entrypoints.md](docs/python-s2i-entrypoints.md) - Python S2I configuration +- [docs/rhel-deployment.md](docs/rhel-deployment.md) - RHEL host deployment +- [docs/debugging-patterns.md](docs/debugging-patterns.md) - Common error patterns and troubleshooting +- [docs/prerequisites.md](docs/prerequisites.md) - All required tools by skill diff --git a/rh-developer/skills/containerize-deploy/docs/builder-images.md b/rh-developer/skills/containerize-deploy/docs/builder-images.md new file mode 120000 index 00000000..d7f4c63c --- /dev/null +++ b/rh-developer/skills/containerize-deploy/docs/builder-images.md @@ -0,0 +1 @@ +../../detect-project/docs/builder-images.md \ No newline at end of file diff --git a/rh-developer/skills/containerize-deploy/docs/debugging-patterns.md b/rh-developer/skills/containerize-deploy/docs/debugging-patterns.md new file mode 120000 index 00000000..b446f69b --- /dev/null +++ b/rh-developer/skills/containerize-deploy/docs/debugging-patterns.md @@ -0,0 +1 @@ +../../debug-build/docs/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/containerize-deploy/docs/human-in-the-loop.md b/rh-developer/skills/containerize-deploy/docs/human-in-the-loop.md new file mode 120000 index 00000000..9a524eda --- /dev/null +++ b/rh-developer/skills/containerize-deploy/docs/human-in-the-loop.md @@ -0,0 +1 @@ +../../validate-environment/docs/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/containerize-deploy/docs/image-selection-criteria.md b/rh-developer/skills/containerize-deploy/docs/image-selection-criteria.md new file mode 120000 index 00000000..e55b7311 --- /dev/null +++ b/rh-developer/skills/containerize-deploy/docs/image-selection-criteria.md @@ -0,0 +1 @@ +../../recommend-image/docs/image-selection-criteria.md \ No newline at end of file diff --git a/rh-developer/skills/containerize-deploy/docs/prerequisites.md b/rh-developer/skills/containerize-deploy/docs/prerequisites.md new file mode 120000 index 00000000..9572b8c5 --- /dev/null +++ b/rh-developer/skills/containerize-deploy/docs/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/containerize-deploy/docs/python-s2i-entrypoints.md b/rh-developer/skills/containerize-deploy/docs/python-s2i-entrypoints.md new file mode 120000 index 00000000..c3416418 --- /dev/null +++ b/rh-developer/skills/containerize-deploy/docs/python-s2i-entrypoints.md @@ -0,0 +1 @@ +../../detect-project/docs/python-s2i-entrypoints.md \ No newline at end of file diff --git a/rh-developer/skills/containerize-deploy/docs/rhel-deployment.md b/rh-developer/skills/containerize-deploy/docs/rhel-deployment.md new file mode 120000 index 00000000..2536fab6 --- /dev/null +++ b/rh-developer/skills/containerize-deploy/docs/rhel-deployment.md @@ -0,0 +1 @@ +../../rhel-deploy/docs/rhel-deployment.md \ No newline at end of file diff --git a/rh-developer/skills/containerize-deploy/docs/selinux-troubleshooting.md b/rh-developer/skills/containerize-deploy/docs/selinux-troubleshooting.md new file mode 120000 index 00000000..43136b67 --- /dev/null +++ b/rh-developer/skills/containerize-deploy/docs/selinux-troubleshooting.md @@ -0,0 +1 @@ +../../rhel-deploy/docs/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/debug-build/SKILL.md b/rh-developer/skills/debug-build/SKILL.md index 52d5eb76..a205e3c9 100644 --- a/rh-developer/skills/debug-build/SKILL.md +++ b/rh-developer/skills/debug-build/SKILL.md @@ -27,7 +27,7 @@ Use this skill when OpenShift builds fail, hang, or produce unexpected results. ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -298,7 +298,7 @@ Select an option: ## Build Failure Categories -For S2I build phase failures, common error patterns (Node.js, Python, Java), and troubleshooting decision trees, see [docs/debugging-patterns.md](../../docs/debugging-patterns.md). +For S2I build phase failures, common error patterns (Node.js, Python, Java), and troubleshooting decision trees, see [docs/debugging-patterns.md](docs/debugging-patterns.md). ## Dependencies @@ -311,7 +311,7 @@ For S2I build phase failures, common error patterns (Node.js, Python, Java), and - `/deploy` - To deploy after a successful build ### Reference Documentation -- [docs/builder-images.md](../../docs/builder-images.md) - S2I builder image selection, version mapping -- [docs/python-s2i-entrypoints.md](../../docs/python-s2i-entrypoints.md) - Python APP_MODULE configuration -- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns -- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc), cluster access verification +- [docs/builder-images.md](docs/builder-images.md) - S2I builder image selection, version mapping +- [docs/python-s2i-entrypoints.md](docs/python-s2i-entrypoints.md) - Python APP_MODULE configuration +- [docs/debugging-patterns.md](docs/debugging-patterns.md) - Common error patterns +- [docs/prerequisites.md](docs/prerequisites.md) - Required tools (oc), cluster access verification diff --git a/rh-developer/skills/debug-build/docs/builder-images.md b/rh-developer/skills/debug-build/docs/builder-images.md new file mode 120000 index 00000000..d7f4c63c --- /dev/null +++ b/rh-developer/skills/debug-build/docs/builder-images.md @@ -0,0 +1 @@ +../../detect-project/docs/builder-images.md \ No newline at end of file diff --git a/rh-developer/docs/debugging-patterns.md b/rh-developer/skills/debug-build/docs/debugging-patterns.md similarity index 100% rename from rh-developer/docs/debugging-patterns.md rename to rh-developer/skills/debug-build/docs/debugging-patterns.md diff --git a/rh-developer/skills/debug-build/docs/human-in-the-loop.md b/rh-developer/skills/debug-build/docs/human-in-the-loop.md new file mode 120000 index 00000000..9a524eda --- /dev/null +++ b/rh-developer/skills/debug-build/docs/human-in-the-loop.md @@ -0,0 +1 @@ +../../validate-environment/docs/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/debug-build/docs/prerequisites.md b/rh-developer/skills/debug-build/docs/prerequisites.md new file mode 120000 index 00000000..9572b8c5 --- /dev/null +++ b/rh-developer/skills/debug-build/docs/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/debug-build/docs/python-s2i-entrypoints.md b/rh-developer/skills/debug-build/docs/python-s2i-entrypoints.md new file mode 120000 index 00000000..c3416418 --- /dev/null +++ b/rh-developer/skills/debug-build/docs/python-s2i-entrypoints.md @@ -0,0 +1 @@ +../../detect-project/docs/python-s2i-entrypoints.md \ No newline at end of file diff --git a/rh-developer/skills/debug-build/docs/selinux-troubleshooting.md b/rh-developer/skills/debug-build/docs/selinux-troubleshooting.md new file mode 120000 index 00000000..43136b67 --- /dev/null +++ b/rh-developer/skills/debug-build/docs/selinux-troubleshooting.md @@ -0,0 +1 @@ +../../rhel-deploy/docs/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/debug-container/SKILL.md b/rh-developer/skills/debug-container/SKILL.md index 853e4ae1..eccae87b 100644 --- a/rh-developer/skills/debug-container/SKILL.md +++ b/rh-developer/skills/debug-container/SKILL.md @@ -35,7 +35,7 @@ Diagnose local Podman/Docker container issues by automatically gathering contain ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. ## When to Use This Skill @@ -287,7 +287,7 @@ Continue to diagnosis summary? (yes/no) - Evidence: [from logs] - Impact: [application cannot access data] -See [debugging-patterns.md](../../docs/debugging-patterns.md) for exit code reference. +See [debugging-patterns.md](docs/debugging-patterns.md) for exit code reference. ### Recommended Actions @@ -330,7 +330,7 @@ Select an option: **WAIT for user to select next action.** -For exit codes, common container issues, and SELinux volume guidance, see [debugging-patterns.md](../../docs/debugging-patterns.md). +For exit codes, common container issues, and SELinux volume guidance, see [debugging-patterns.md](docs/debugging-patterns.md). ## Dependencies @@ -342,5 +342,5 @@ For exit codes, common container issues, and SELinux volume guidance, see [debug - `/recommend-image` - select a better base image ### Reference Documentation -- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns, exit codes -- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (podman) +- [docs/debugging-patterns.md](docs/debugging-patterns.md) - Common error patterns, exit codes +- [docs/prerequisites.md](docs/prerequisites.md) - Required tools (podman) diff --git a/rh-developer/skills/debug-container/docs/debugging-patterns.md b/rh-developer/skills/debug-container/docs/debugging-patterns.md new file mode 120000 index 00000000..b446f69b --- /dev/null +++ b/rh-developer/skills/debug-container/docs/debugging-patterns.md @@ -0,0 +1 @@ +../../debug-build/docs/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/debug-container/docs/human-in-the-loop.md b/rh-developer/skills/debug-container/docs/human-in-the-loop.md new file mode 120000 index 00000000..9a524eda --- /dev/null +++ b/rh-developer/skills/debug-container/docs/human-in-the-loop.md @@ -0,0 +1 @@ +../../validate-environment/docs/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/debug-container/docs/prerequisites.md b/rh-developer/skills/debug-container/docs/prerequisites.md new file mode 120000 index 00000000..9572b8c5 --- /dev/null +++ b/rh-developer/skills/debug-container/docs/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/debug-container/docs/selinux-troubleshooting.md b/rh-developer/skills/debug-container/docs/selinux-troubleshooting.md new file mode 120000 index 00000000..43136b67 --- /dev/null +++ b/rh-developer/skills/debug-container/docs/selinux-troubleshooting.md @@ -0,0 +1 @@ +../../rhel-deploy/docs/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/debug-network/SKILL.md b/rh-developer/skills/debug-network/SKILL.md index dc506df7..b5520f04 100644 --- a/rh-developer/skills/debug-network/SKILL.md +++ b/rh-developer/skills/debug-network/SKILL.md @@ -27,7 +27,7 @@ Use this skill when services cannot communicate, routes return 503/502 errors, o ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -317,7 +317,7 @@ Select an option: ## Common Connectivity Issues -For detailed diagnosis and fix tables covering service, route, and network policy issues, see [docs/debugging-patterns.md](../../docs/debugging-patterns.md). +For detailed diagnosis and fix tables covering service, route, and network policy issues, see [docs/debugging-patterns.md](docs/debugging-patterns.md). ## Dependencies @@ -329,5 +329,5 @@ For detailed diagnosis and fix tables covering service, route, and network polic - `/deploy` - To fix and redeploy the service ### Reference Documentation -- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns -- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc), cluster access verification +- [docs/debugging-patterns.md](docs/debugging-patterns.md) - Common error patterns +- [docs/prerequisites.md](docs/prerequisites.md) - Required tools (oc), cluster access verification diff --git a/rh-developer/skills/debug-network/docs/debugging-patterns.md b/rh-developer/skills/debug-network/docs/debugging-patterns.md new file mode 120000 index 00000000..b446f69b --- /dev/null +++ b/rh-developer/skills/debug-network/docs/debugging-patterns.md @@ -0,0 +1 @@ +../../debug-build/docs/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/debug-network/docs/human-in-the-loop.md b/rh-developer/skills/debug-network/docs/human-in-the-loop.md new file mode 120000 index 00000000..9a524eda --- /dev/null +++ b/rh-developer/skills/debug-network/docs/human-in-the-loop.md @@ -0,0 +1 @@ +../../validate-environment/docs/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/debug-network/docs/prerequisites.md b/rh-developer/skills/debug-network/docs/prerequisites.md new file mode 120000 index 00000000..9572b8c5 --- /dev/null +++ b/rh-developer/skills/debug-network/docs/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/debug-network/docs/selinux-troubleshooting.md b/rh-developer/skills/debug-network/docs/selinux-troubleshooting.md new file mode 120000 index 00000000..43136b67 --- /dev/null +++ b/rh-developer/skills/debug-network/docs/selinux-troubleshooting.md @@ -0,0 +1 @@ +../../rhel-deploy/docs/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/debug-pipeline/SKILL.md b/rh-developer/skills/debug-pipeline/SKILL.md index 678a8f6d..15a2e25d 100644 --- a/rh-developer/skills/debug-pipeline/SKILL.md +++ b/rh-developer/skills/debug-pipeline/SKILL.md @@ -43,7 +43,7 @@ Use this skill when OpenShift Pipelines (Tekton) fail, hang, or produce unexpect ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -290,7 +290,7 @@ Select an option: ## Pipeline Failure Reference -For failure categories, error patterns, and troubleshooting decision trees, see [docs/debugging-patterns.md](../../docs/debugging-patterns.md) (sections: Pipeline/Tekton Failure Patterns, Common Tekton Error Messages). +For failure categories, error patterns, and troubleshooting decision trees, see [docs/debugging-patterns.md](docs/debugging-patterns.md) (sections: Pipeline/Tekton Failure Patterns, Common Tekton Error Messages). ## Dependencies @@ -304,5 +304,5 @@ For failure categories, error patterns, and troubleshooting decision trees, see - `/validate-environment` - To verify OpenShift and pipeline operator setup ### Reference Documentation -- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns and pipeline troubleshooting trees -- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc), cluster access verification +- [docs/debugging-patterns.md](docs/debugging-patterns.md) - Common error patterns and pipeline troubleshooting trees +- [docs/prerequisites.md](docs/prerequisites.md) - Required tools (oc), cluster access verification diff --git a/rh-developer/skills/debug-pipeline/docs/debugging-patterns.md b/rh-developer/skills/debug-pipeline/docs/debugging-patterns.md new file mode 120000 index 00000000..b446f69b --- /dev/null +++ b/rh-developer/skills/debug-pipeline/docs/debugging-patterns.md @@ -0,0 +1 @@ +../../debug-build/docs/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/debug-pipeline/docs/human-in-the-loop.md b/rh-developer/skills/debug-pipeline/docs/human-in-the-loop.md new file mode 120000 index 00000000..9a524eda --- /dev/null +++ b/rh-developer/skills/debug-pipeline/docs/human-in-the-loop.md @@ -0,0 +1 @@ +../../validate-environment/docs/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/debug-pipeline/docs/prerequisites.md b/rh-developer/skills/debug-pipeline/docs/prerequisites.md new file mode 120000 index 00000000..9572b8c5 --- /dev/null +++ b/rh-developer/skills/debug-pipeline/docs/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/debug-pipeline/docs/selinux-troubleshooting.md b/rh-developer/skills/debug-pipeline/docs/selinux-troubleshooting.md new file mode 120000 index 00000000..43136b67 --- /dev/null +++ b/rh-developer/skills/debug-pipeline/docs/selinux-troubleshooting.md @@ -0,0 +1 @@ +../../rhel-deploy/docs/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/debug-pod/SKILL.md b/rh-developer/skills/debug-pod/SKILL.md index a215ffeb..088e21e0 100644 --- a/rh-developer/skills/debug-pod/SKILL.md +++ b/rh-developer/skills/debug-pod/SKILL.md @@ -27,7 +27,7 @@ Use this skill when pods are not running, restarting frequently, or stuck in non ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -245,7 +245,7 @@ Select an option: **WAIT for user confirmation before proceeding.** -For pod failure categories and exit code reference, see [debugging-patterns.md](../../docs/debugging-patterns.md). +For pod failure categories and exit code reference, see [debugging-patterns.md](docs/debugging-patterns.md). ## Dependencies @@ -258,5 +258,5 @@ For pod failure categories and exit code reference, see [debugging-patterns.md]( - `/deploy` - To redeploy after fixing issues ### Reference Documentation -- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns and troubleshooting trees -- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc), cluster access verification +- [docs/debugging-patterns.md](docs/debugging-patterns.md) - Common error patterns and troubleshooting trees +- [docs/prerequisites.md](docs/prerequisites.md) - Required tools (oc), cluster access verification diff --git a/rh-developer/skills/debug-pod/docs/debugging-patterns.md b/rh-developer/skills/debug-pod/docs/debugging-patterns.md new file mode 120000 index 00000000..b446f69b --- /dev/null +++ b/rh-developer/skills/debug-pod/docs/debugging-patterns.md @@ -0,0 +1 @@ +../../debug-build/docs/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/debug-pod/docs/human-in-the-loop.md b/rh-developer/skills/debug-pod/docs/human-in-the-loop.md new file mode 120000 index 00000000..9a524eda --- /dev/null +++ b/rh-developer/skills/debug-pod/docs/human-in-the-loop.md @@ -0,0 +1 @@ +../../validate-environment/docs/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/debug-pod/docs/prerequisites.md b/rh-developer/skills/debug-pod/docs/prerequisites.md new file mode 120000 index 00000000..9572b8c5 --- /dev/null +++ b/rh-developer/skills/debug-pod/docs/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/debug-pod/docs/selinux-troubleshooting.md b/rh-developer/skills/debug-pod/docs/selinux-troubleshooting.md new file mode 120000 index 00000000..43136b67 --- /dev/null +++ b/rh-developer/skills/debug-pod/docs/selinux-troubleshooting.md @@ -0,0 +1 @@ +../../rhel-deploy/docs/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/debug-rbac/SKILL.md b/rh-developer/skills/debug-rbac/SKILL.md index abd81600..4be8596e 100644 --- a/rh-developer/skills/debug-rbac/SKILL.md +++ b/rh-developer/skills/debug-rbac/SKILL.md @@ -39,7 +39,7 @@ Diagnose RBAC permission failures on OpenShift by analyzing pod logs, readiness ## Prerequisites -**Required MCP Servers:** `openshift` ([setup](../../docs/prerequisites.md)) +**Required MCP Servers:** `openshift` ([setup](docs/prerequisites.md)) **Required MCP Tools:** - `resources_get` (from openshift) — Retrieve Deployment, Pod, ServiceAccount, Role, and RoleBinding details @@ -425,7 +425,7 @@ Select an option: ## Dependencies ### Required MCP Servers -- `openshift` — Kubernetes/OpenShift resource access for Deployments, Pods, ServiceAccounts, Roles, RoleBindings, and Events ([setup](../../docs/prerequisites.md)) +- `openshift` — Kubernetes/OpenShift resource access for Deployments, Pods, ServiceAccounts, Roles, RoleBindings, and Events ([setup](docs/prerequisites.md)) ### Required MCP Tools - `resources_get` (from openshift) — Retrieve individual resource details (Deployment, Pod, ServiceAccount, Role, RoleBinding) @@ -440,7 +440,7 @@ Select an option: - `/debug-network` — If pods can't reach services (network, not API access) ### Reference Documentation -- **Internal:** [docs/debugging-patterns.md](../../docs/debugging-patterns.md) — Common error patterns and troubleshooting trees +- **Internal:** [docs/debugging-patterns.md](docs/debugging-patterns.md) — Common error patterns and troubleshooting trees - **Official:** [Using RBAC - OpenShift](https://docs.openshift.com/container-platform/latest/authentication/using-rbac.html) ## Example Usage diff --git a/rh-developer/skills/debug-rbac/docs/debugging-patterns.md b/rh-developer/skills/debug-rbac/docs/debugging-patterns.md new file mode 120000 index 00000000..b446f69b --- /dev/null +++ b/rh-developer/skills/debug-rbac/docs/debugging-patterns.md @@ -0,0 +1 @@ +../../debug-build/docs/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/debug-rbac/docs/prerequisites.md b/rh-developer/skills/debug-rbac/docs/prerequisites.md new file mode 120000 index 00000000..9572b8c5 --- /dev/null +++ b/rh-developer/skills/debug-rbac/docs/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/debug-rbac/docs/selinux-troubleshooting.md b/rh-developer/skills/debug-rbac/docs/selinux-troubleshooting.md new file mode 120000 index 00000000..43136b67 --- /dev/null +++ b/rh-developer/skills/debug-rbac/docs/selinux-troubleshooting.md @@ -0,0 +1 @@ +../../rhel-deploy/docs/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/debug-rhel/SKILL.md b/rh-developer/skills/debug-rhel/SKILL.md index d9505131..53d30afb 100644 --- a/rh-developer/skills/debug-rhel/SKILL.md +++ b/rh-developer/skills/debug-rhel/SKILL.md @@ -35,7 +35,7 @@ Diagnose RHEL system issues by automatically gathering systemd status, journal l ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. ## Note: SSH/Bash Required @@ -439,7 +439,7 @@ Select an option: **WAIT for user to select next action.** -For common RHEL issues (systemd exit codes, SELinux denials, firewall), see [debugging-patterns.md](../../docs/debugging-patterns.md) and [selinux-troubleshooting.md](../../docs/selinux-troubleshooting.md). +For common RHEL issues (systemd exit codes, SELinux denials, firewall), see [debugging-patterns.md](docs/debugging-patterns.md) and [selinux-troubleshooting.md](docs/selinux-troubleshooting.md). ## Dependencies @@ -451,7 +451,7 @@ For common RHEL issues (systemd exit codes, SELinux denials, firewall), see [deb - `/debug-container` - debug Podman containers on the host ### Reference Documentation -- [docs/selinux-troubleshooting.md](../../docs/selinux-troubleshooting.md) - SELinux denial analysis -- [docs/rhel-deployment.md](../../docs/rhel-deployment.md) - RHEL deployment patterns -- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns -- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools and setup +- [docs/selinux-troubleshooting.md](docs/selinux-troubleshooting.md) - SELinux denial analysis +- [docs/rhel-deployment.md](docs/rhel-deployment.md) - RHEL deployment patterns +- [docs/debugging-patterns.md](docs/debugging-patterns.md) - Common error patterns +- [docs/prerequisites.md](docs/prerequisites.md) - Required tools and setup diff --git a/rh-developer/skills/debug-rhel/docs/debugging-patterns.md b/rh-developer/skills/debug-rhel/docs/debugging-patterns.md new file mode 120000 index 00000000..b446f69b --- /dev/null +++ b/rh-developer/skills/debug-rhel/docs/debugging-patterns.md @@ -0,0 +1 @@ +../../debug-build/docs/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/debug-rhel/docs/human-in-the-loop.md b/rh-developer/skills/debug-rhel/docs/human-in-the-loop.md new file mode 120000 index 00000000..9a524eda --- /dev/null +++ b/rh-developer/skills/debug-rhel/docs/human-in-the-loop.md @@ -0,0 +1 @@ +../../validate-environment/docs/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/debug-rhel/docs/prerequisites.md b/rh-developer/skills/debug-rhel/docs/prerequisites.md new file mode 120000 index 00000000..9572b8c5 --- /dev/null +++ b/rh-developer/skills/debug-rhel/docs/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/debug-rhel/docs/rhel-deployment.md b/rh-developer/skills/debug-rhel/docs/rhel-deployment.md new file mode 120000 index 00000000..2536fab6 --- /dev/null +++ b/rh-developer/skills/debug-rhel/docs/rhel-deployment.md @@ -0,0 +1 @@ +../../rhel-deploy/docs/rhel-deployment.md \ No newline at end of file diff --git a/rh-developer/skills/debug-rhel/docs/selinux-troubleshooting.md b/rh-developer/skills/debug-rhel/docs/selinux-troubleshooting.md new file mode 120000 index 00000000..43136b67 --- /dev/null +++ b/rh-developer/skills/debug-rhel/docs/selinux-troubleshooting.md @@ -0,0 +1 @@ +../../rhel-deploy/docs/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/debug-scc/SKILL.md b/rh-developer/skills/debug-scc/SKILL.md index 960753ce..4ae10776 100644 --- a/rh-developer/skills/debug-scc/SKILL.md +++ b/rh-developer/skills/debug-scc/SKILL.md @@ -39,7 +39,7 @@ Diagnose OpenShift SCC violations that block pod creation by analyzing security ## Prerequisites -**Required MCP Servers:** `openshift` ([setup](../../docs/prerequisites.md)) +**Required MCP Servers:** `openshift` ([setup](docs/prerequisites.md)) **Required MCP Tools:** - `resources_get` (from openshift) — Retrieve Deployment, ReplicaSet, and ServiceAccount details @@ -435,7 +435,7 @@ Select an option: ## Dependencies ### Required MCP Servers -- `openshift` — Kubernetes/OpenShift resource access for Deployments, ReplicaSets, Events, ServiceAccounts, and SecurityContextConstraints ([setup](../../docs/prerequisites.md)) +- `openshift` — Kubernetes/OpenShift resource access for Deployments, ReplicaSets, Events, ServiceAccounts, and SecurityContextConstraints ([setup](docs/prerequisites.md)) ### Required MCP Tools - `resources_get` (from openshift) — Retrieve individual resource details (Deployment, ReplicaSet, ServiceAccount) @@ -448,7 +448,7 @@ Select an option: - `/debug-rbac` — If pods run but fail with 403 Forbidden API errors (RBAC, not SCC) ### Reference Documentation -- **Internal:** [docs/debugging-patterns.md](../../docs/debugging-patterns.md) — Common error patterns and troubleshooting trees +- **Internal:** [docs/debugging-patterns.md](docs/debugging-patterns.md) — Common error patterns and troubleshooting trees - **Official:** [Managing SCCs - OpenShift](https://docs.openshift.com/container-platform/latest/authentication/managing-security-context-constraints.html) ## Example Usage diff --git a/rh-developer/skills/debug-scc/docs/debugging-patterns.md b/rh-developer/skills/debug-scc/docs/debugging-patterns.md new file mode 120000 index 00000000..b446f69b --- /dev/null +++ b/rh-developer/skills/debug-scc/docs/debugging-patterns.md @@ -0,0 +1 @@ +../../debug-build/docs/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/debug-scc/docs/prerequisites.md b/rh-developer/skills/debug-scc/docs/prerequisites.md new file mode 120000 index 00000000..9572b8c5 --- /dev/null +++ b/rh-developer/skills/debug-scc/docs/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/debug-scc/docs/selinux-troubleshooting.md b/rh-developer/skills/debug-scc/docs/selinux-troubleshooting.md new file mode 120000 index 00000000..43136b67 --- /dev/null +++ b/rh-developer/skills/debug-scc/docs/selinux-troubleshooting.md @@ -0,0 +1 @@ +../../rhel-deploy/docs/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/deploy/SKILL.md b/rh-developer/skills/deploy/SKILL.md index 11d1f2bc..5198e805 100644 --- a/rh-developer/skills/deploy/SKILL.md +++ b/rh-developer/skills/deploy/SKILL.md @@ -27,7 +27,7 @@ Use `/deploy` after building a container image (via `/s2i-build` or external reg ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -275,5 +275,5 @@ Your application is now live! - `/debug-build` - Build failures before deployment ### Reference Documentation -- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc), cluster access verification -- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns and troubleshooting +- [docs/prerequisites.md](docs/prerequisites.md) - Required tools (oc), cluster access verification +- [docs/debugging-patterns.md](docs/debugging-patterns.md) - Common error patterns and troubleshooting diff --git a/rh-developer/skills/deploy/docs/debugging-patterns.md b/rh-developer/skills/deploy/docs/debugging-patterns.md new file mode 120000 index 00000000..b446f69b --- /dev/null +++ b/rh-developer/skills/deploy/docs/debugging-patterns.md @@ -0,0 +1 @@ +../../debug-build/docs/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/deploy/docs/human-in-the-loop.md b/rh-developer/skills/deploy/docs/human-in-the-loop.md new file mode 120000 index 00000000..9a524eda --- /dev/null +++ b/rh-developer/skills/deploy/docs/human-in-the-loop.md @@ -0,0 +1 @@ +../../validate-environment/docs/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/deploy/docs/prerequisites.md b/rh-developer/skills/deploy/docs/prerequisites.md new file mode 120000 index 00000000..9572b8c5 --- /dev/null +++ b/rh-developer/skills/deploy/docs/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/deploy/docs/selinux-troubleshooting.md b/rh-developer/skills/deploy/docs/selinux-troubleshooting.md new file mode 120000 index 00000000..43136b67 --- /dev/null +++ b/rh-developer/skills/deploy/docs/selinux-troubleshooting.md @@ -0,0 +1 @@ +../../rhel-deploy/docs/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/detect-project/SKILL.md b/rh-developer/skills/detect-project/SKILL.md index a06644c4..933c0389 100644 --- a/rh-developer/skills/detect-project/SKILL.md +++ b/rh-developer/skills/detect-project/SKILL.md @@ -27,7 +27,7 @@ Analyze the project to detect language/framework and recommend a build strategy. ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -274,6 +274,6 @@ After successful detection, these values should be available for other skills: - `/rhel-deploy` - Deploy to RHEL using detected project info ### Reference Documentation -- [docs/builder-images.md](../../docs/builder-images.md) - Language detection matrix, version-to-image mapping, S2I builder selection -- [docs/python-s2i-entrypoints.md](../../docs/python-s2i-entrypoints.md) - Python entry point detection, APP_MODULE configuration -- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (git) +- [docs/builder-images.md](docs/builder-images.md) - Language detection matrix, version-to-image mapping, S2I builder selection +- [docs/python-s2i-entrypoints.md](docs/python-s2i-entrypoints.md) - Python entry point detection, APP_MODULE configuration +- [docs/prerequisites.md](docs/prerequisites.md) - Required tools (git) diff --git a/rh-developer/docs/builder-images.md b/rh-developer/skills/detect-project/docs/builder-images.md similarity index 100% rename from rh-developer/docs/builder-images.md rename to rh-developer/skills/detect-project/docs/builder-images.md diff --git a/rh-developer/skills/detect-project/docs/human-in-the-loop.md b/rh-developer/skills/detect-project/docs/human-in-the-loop.md new file mode 120000 index 00000000..9a524eda --- /dev/null +++ b/rh-developer/skills/detect-project/docs/human-in-the-loop.md @@ -0,0 +1 @@ +../../validate-environment/docs/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/detect-project/docs/prerequisites.md b/rh-developer/skills/detect-project/docs/prerequisites.md new file mode 120000 index 00000000..9572b8c5 --- /dev/null +++ b/rh-developer/skills/detect-project/docs/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/docs/python-s2i-entrypoints.md b/rh-developer/skills/detect-project/docs/python-s2i-entrypoints.md similarity index 100% rename from rh-developer/docs/python-s2i-entrypoints.md rename to rh-developer/skills/detect-project/docs/python-s2i-entrypoints.md diff --git a/rh-developer/skills/helm-deploy/SKILL.md b/rh-developer/skills/helm-deploy/SKILL.md index d7a2f43f..cc7fed5d 100644 --- a/rh-developer/skills/helm-deploy/SKILL.md +++ b/rh-developer/skills/helm-deploy/SKILL.md @@ -28,7 +28,7 @@ Deploy applications to OpenShift using Helm charts. Supports existing charts or ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -353,6 +353,6 @@ Your application is live! - `/debug-network` - Diagnose networking issues with deployed services ### Reference Documentation -- [docs/builder-images.md](../../docs/builder-images.md) - Container image references for chart values -- [docs/image-selection-criteria.md](../../docs/image-selection-criteria.md) - Image variant selection for production deployments -- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc, helm) +- [docs/builder-images.md](docs/builder-images.md) - Container image references for chart values +- [docs/image-selection-criteria.md](docs/image-selection-criteria.md) - Image variant selection for production deployments +- [docs/prerequisites.md](docs/prerequisites.md) - Required tools (oc, helm) diff --git a/rh-developer/skills/helm-deploy/docs/builder-images.md b/rh-developer/skills/helm-deploy/docs/builder-images.md new file mode 120000 index 00000000..d7f4c63c --- /dev/null +++ b/rh-developer/skills/helm-deploy/docs/builder-images.md @@ -0,0 +1 @@ +../../detect-project/docs/builder-images.md \ No newline at end of file diff --git a/rh-developer/skills/helm-deploy/docs/human-in-the-loop.md b/rh-developer/skills/helm-deploy/docs/human-in-the-loop.md new file mode 120000 index 00000000..9a524eda --- /dev/null +++ b/rh-developer/skills/helm-deploy/docs/human-in-the-loop.md @@ -0,0 +1 @@ +../../validate-environment/docs/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/helm-deploy/docs/image-selection-criteria.md b/rh-developer/skills/helm-deploy/docs/image-selection-criteria.md new file mode 120000 index 00000000..e55b7311 --- /dev/null +++ b/rh-developer/skills/helm-deploy/docs/image-selection-criteria.md @@ -0,0 +1 @@ +../../recommend-image/docs/image-selection-criteria.md \ No newline at end of file diff --git a/rh-developer/skills/helm-deploy/docs/prerequisites.md b/rh-developer/skills/helm-deploy/docs/prerequisites.md new file mode 120000 index 00000000..9572b8c5 --- /dev/null +++ b/rh-developer/skills/helm-deploy/docs/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/incident-triage/SKILL.md b/rh-developer/skills/incident-triage/SKILL.md index 7dbeb5a7..7fa2ab52 100644 --- a/rh-developer/skills/incident-triage/SKILL.md +++ b/rh-developer/skills/incident-triage/SKILL.md @@ -40,7 +40,8 @@ Structured incident investigation for OpenShift — traces from symptoms to root ## Prerequisites **Required MCP Servers:** -- `openshift` ([setup](../../docs/prerequisites.md)) — Kubernetes/OpenShift resource access +- `openshift` ([setup](docs/prerequisites.md)) — Kubernetes/OpenShift resource access +- `observability` — Prometheus metric discovery and PromQL query execution **Required MCP Tools:** - `resources_get` (from openshift) — Retrieve Deployment, ReplicaSet, Pod, Service, and other resource details @@ -454,7 +455,8 @@ Select an option: ## Dependencies ### Required MCP Servers -- `openshift` — Kubernetes/OpenShift resource access for Deployments, Pods, Events, Services, and cluster resources ([setup](../../docs/prerequisites.md)) +- `openshift` — Kubernetes/OpenShift resource access for Deployments, Pods, Events, Services, and cluster resources ([setup](docs/prerequisites.md)) +- `observability` — Prometheus metric discovery, metadata, series, and PromQL query execution ### Required MCP Tools - `resources_get` (from openshift) — Retrieve individual resource details @@ -475,7 +477,7 @@ Select an option: - `/deploy` — Redeployment after fixes ### Reference Documentation -- **Internal:** [docs/debugging-patterns.md](../../docs/debugging-patterns.md) — Common error patterns and troubleshooting trees +- **Internal:** [docs/debugging-patterns.md](docs/debugging-patterns.md) — Common error patterns and troubleshooting trees - **Official:** [OpenShift Troubleshooting](https://docs.openshift.com/container-platform/latest/support/troubleshooting/troubleshooting-operator-issues.html) ## Example Usage diff --git a/rh-developer/skills/incident-triage/docs/debugging-patterns.md b/rh-developer/skills/incident-triage/docs/debugging-patterns.md new file mode 120000 index 00000000..b446f69b --- /dev/null +++ b/rh-developer/skills/incident-triage/docs/debugging-patterns.md @@ -0,0 +1 @@ +../../debug-build/docs/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/incident-triage/docs/prerequisites.md b/rh-developer/skills/incident-triage/docs/prerequisites.md new file mode 120000 index 00000000..9572b8c5 --- /dev/null +++ b/rh-developer/skills/incident-triage/docs/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/incident-triage/docs/selinux-troubleshooting.md b/rh-developer/skills/incident-triage/docs/selinux-troubleshooting.md new file mode 120000 index 00000000..43136b67 --- /dev/null +++ b/rh-developer/skills/incident-triage/docs/selinux-troubleshooting.md @@ -0,0 +1 @@ +../../rhel-deploy/docs/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/recommend-image/SKILL.md b/rh-developer/skills/recommend-image/SKILL.md index 6e2cb42c..28d6d883 100644 --- a/rh-developer/skills/recommend-image/SKILL.md +++ b/rh-developer/skills/recommend-image/SKILL.md @@ -24,7 +24,7 @@ Provide intelligent, use-case-aware container image recommendations that go beyo ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -116,7 +116,7 @@ For each language, evaluate available variants against user requirements. **Key Scoring Factors:** Image size, security posture, build tools availability, startup time, LTS status -> **See [docs/image-selection-criteria.md](../../docs/image-selection-criteria.md)** for comprehensive scoring matrices with weighted criteria by environment (production/development/edge/serverless). +> **See [docs/image-selection-criteria.md](docs/image-selection-criteria.md)** for comprehensive scoring matrices with weighted criteria by environment (production/development/edge/serverless). ### Step 3.5: Dynamic Image Validation @@ -143,7 +143,7 @@ To provide accurate image recommendations, I need `skopeo` to inspect container - Check architecture support (amd64, arm64) - Show when the image was last built -**Install skopeo:** See [docs/prerequisites.md](../../docs/prerequisites.md) for installation commands by OS. +**Install skopeo:** See [docs/prerequisites.md](docs/prerequisites.md) for installation commands by OS. After installing, run `/recommend-image` again for enhanced recommendations. @@ -266,7 +266,7 @@ Return to Step 2 with new inputs. - **Development** → Full variant - **Serverless** → Smallest available (minimal or native binary) -> **See [docs/image-selection-criteria.md](../../docs/image-selection-criteria.md)** for comprehensive image size references, LTS timelines, decision trees, and framework-specific recommendations (Quarkus, Spring Boot, Next.js, Django/Flask). +> **See [docs/image-selection-criteria.md](docs/image-selection-criteria.md)** for comprehensive image size references, LTS timelines, decision trees, and framework-specific recommendations (Quarkus, Spring Boot, Next.js, Django/Flask). ## Dependencies @@ -278,7 +278,7 @@ Return to Step 2 with new inputs. - `/s2i-build` - Build with the recommended image ### Reference Documentation -- [docs/image-selection-criteria.md](../../docs/image-selection-criteria.md) - Comprehensive scoring matrices, image size reference, LTS timelines, decision trees -- [docs/builder-images.md](../../docs/builder-images.md) - UBI image registry, framework-specific recommendations, variant availability -- [docs/dynamic-validation.md](../../docs/dynamic-validation.md) - Skopeo commands, Red Hat Security Data API, image verification patterns -- [docs/prerequisites.md](../../docs/prerequisites.md) - Skopeo installation instructions +- [docs/image-selection-criteria.md](docs/image-selection-criteria.md) - Comprehensive scoring matrices, image size reference, LTS timelines, decision trees +- [docs/builder-images.md](docs/builder-images.md) - UBI image registry, framework-specific recommendations, variant availability +- [docs/dynamic-validation.md](docs/dynamic-validation.md) - Skopeo commands, Red Hat Security Data API, image verification patterns +- [docs/prerequisites.md](docs/prerequisites.md) - Skopeo installation instructions diff --git a/rh-developer/skills/recommend-image/docs/builder-images.md b/rh-developer/skills/recommend-image/docs/builder-images.md new file mode 120000 index 00000000..d7f4c63c --- /dev/null +++ b/rh-developer/skills/recommend-image/docs/builder-images.md @@ -0,0 +1 @@ +../../detect-project/docs/builder-images.md \ No newline at end of file diff --git a/rh-developer/docs/dynamic-validation.md b/rh-developer/skills/recommend-image/docs/dynamic-validation.md similarity index 100% rename from rh-developer/docs/dynamic-validation.md rename to rh-developer/skills/recommend-image/docs/dynamic-validation.md diff --git a/rh-developer/skills/recommend-image/docs/human-in-the-loop.md b/rh-developer/skills/recommend-image/docs/human-in-the-loop.md new file mode 120000 index 00000000..9a524eda --- /dev/null +++ b/rh-developer/skills/recommend-image/docs/human-in-the-loop.md @@ -0,0 +1 @@ +../../validate-environment/docs/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/docs/image-selection-criteria.md b/rh-developer/skills/recommend-image/docs/image-selection-criteria.md similarity index 100% rename from rh-developer/docs/image-selection-criteria.md rename to rh-developer/skills/recommend-image/docs/image-selection-criteria.md diff --git a/rh-developer/skills/recommend-image/docs/prerequisites.md b/rh-developer/skills/recommend-image/docs/prerequisites.md new file mode 120000 index 00000000..9572b8c5 --- /dev/null +++ b/rh-developer/skills/recommend-image/docs/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/rhel-deploy/SKILL.md b/rh-developer/skills/rhel-deploy/SKILL.md index dcb57dac..ffacd851 100644 --- a/rh-developer/skills/rhel-deploy/SKILL.md +++ b/rh-developer/skills/rhel-deploy/SKILL.md @@ -43,7 +43,7 @@ Use `/rhel-deploy` when deploying applications to standalone RHEL, Fedora, or Ce ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -242,7 +242,7 @@ ssh [target] "podman pull [image-reference]" | Environment | [list env vars] | | Run Mode | [rootless / rootful] | -**SELinux Volume Labels:** Use `:z` for shared volumes, `:Z` for private volumes. See [docs/rhel-deployment.md](../../docs/rhel-deployment.md) for SELinux configuration details. +**SELinux Volume Labels:** Use `:z` for shared volumes, `:Z` for private volumes. See [docs/rhel-deployment.md](docs/rhel-deployment.md) for SELinux configuration details. Proceed with this configuration? (yes/modify/cancel) ``` @@ -324,7 +324,7 @@ Proceed with firewall configuration? (yes/skip) **Runtime packages for [language]:** -See [docs/rhel-deployment.md](../../docs/rhel-deployment.md) for the complete runtime package mapping by language and RHEL version (Node.js, Python, Java, Go, Ruby, PHP). +See [docs/rhel-deployment.md](docs/rhel-deployment.md) for the complete runtime package mapping by language and RHEL version (Node.js, Python, Java, Go, Ruby, PHP). **Commands to execute:** ```bash @@ -381,7 +381,7 @@ Proceed with deployment? (yes/no) | `${PORT}` | [container-port] | Application listen port | | `${START_COMMAND}` | [see below] | Language-specific start command | -**Start commands by language:** See [docs/rhel-deployment.md](../../docs/rhel-deployment.md) for language-specific systemd unit templates (Node.js, Python, Java, Go). +**Start commands by language:** See [docs/rhel-deployment.md](docs/rhel-deployment.md) for language-specific systemd unit templates (Node.js, Python, Java, Go). **Target location:** `/etc/systemd/system/[app-name].service` @@ -478,7 +478,7 @@ Select an option: - `/debug-container` - Container startup issues on RHEL host ### Reference Documentation -- [docs/rhel-deployment.md](../../docs/rhel-deployment.md) - Systemd templates, SELinux, firewall, runtime packages -- [docs/selinux-troubleshooting.md](../../docs/selinux-troubleshooting.md) - SELinux denial analysis and fixes -- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns and troubleshooting -- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (ssh, podman) +- [docs/rhel-deployment.md](docs/rhel-deployment.md) - Systemd templates, SELinux, firewall, runtime packages +- [docs/selinux-troubleshooting.md](docs/selinux-troubleshooting.md) - SELinux denial analysis and fixes +- [docs/debugging-patterns.md](docs/debugging-patterns.md) - Common error patterns and troubleshooting +- [docs/prerequisites.md](docs/prerequisites.md) - Required tools (ssh, podman) diff --git a/rh-developer/skills/rhel-deploy/docs/debugging-patterns.md b/rh-developer/skills/rhel-deploy/docs/debugging-patterns.md new file mode 120000 index 00000000..b446f69b --- /dev/null +++ b/rh-developer/skills/rhel-deploy/docs/debugging-patterns.md @@ -0,0 +1 @@ +../../debug-build/docs/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/rhel-deploy/docs/human-in-the-loop.md b/rh-developer/skills/rhel-deploy/docs/human-in-the-loop.md new file mode 120000 index 00000000..9a524eda --- /dev/null +++ b/rh-developer/skills/rhel-deploy/docs/human-in-the-loop.md @@ -0,0 +1 @@ +../../validate-environment/docs/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/rhel-deploy/docs/prerequisites.md b/rh-developer/skills/rhel-deploy/docs/prerequisites.md new file mode 120000 index 00000000..9572b8c5 --- /dev/null +++ b/rh-developer/skills/rhel-deploy/docs/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/docs/rhel-deployment.md b/rh-developer/skills/rhel-deploy/docs/rhel-deployment.md similarity index 100% rename from rh-developer/docs/rhel-deployment.md rename to rh-developer/skills/rhel-deploy/docs/rhel-deployment.md diff --git a/rh-developer/docs/selinux-troubleshooting.md b/rh-developer/skills/rhel-deploy/docs/selinux-troubleshooting.md similarity index 100% rename from rh-developer/docs/selinux-troubleshooting.md rename to rh-developer/skills/rhel-deploy/docs/selinux-troubleshooting.md diff --git a/rh-developer/skills/s2i-build/SKILL.md b/rh-developer/skills/s2i-build/SKILL.md index 90f11d3b..15903e47 100644 --- a/rh-developer/skills/s2i-build/SKILL.md +++ b/rh-developer/skills/s2i-build/SKILL.md @@ -27,7 +27,7 @@ Use this skill after `/detect-project` to build container images from source cod ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -387,7 +387,7 @@ What would you like to do? - `/deploy` - After successful build, to deploy the image ### Reference Documentation -- [docs/builder-images.md](../../docs/builder-images.md) - S2I builder image selection, version mapping -- [docs/python-s2i-entrypoints.md](../../docs/python-s2i-entrypoints.md) - Python APP_MODULE configuration, entry point troubleshooting -- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common build error patterns and troubleshooting -- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc) +- [docs/builder-images.md](docs/builder-images.md) - S2I builder image selection, version mapping +- [docs/python-s2i-entrypoints.md](docs/python-s2i-entrypoints.md) - Python APP_MODULE configuration, entry point troubleshooting +- [docs/debugging-patterns.md](docs/debugging-patterns.md) - Common build error patterns and troubleshooting +- [docs/prerequisites.md](docs/prerequisites.md) - Required tools (oc) diff --git a/rh-developer/skills/s2i-build/docs/builder-images.md b/rh-developer/skills/s2i-build/docs/builder-images.md new file mode 120000 index 00000000..d7f4c63c --- /dev/null +++ b/rh-developer/skills/s2i-build/docs/builder-images.md @@ -0,0 +1 @@ +../../detect-project/docs/builder-images.md \ No newline at end of file diff --git a/rh-developer/skills/s2i-build/docs/debugging-patterns.md b/rh-developer/skills/s2i-build/docs/debugging-patterns.md new file mode 120000 index 00000000..b446f69b --- /dev/null +++ b/rh-developer/skills/s2i-build/docs/debugging-patterns.md @@ -0,0 +1 @@ +../../debug-build/docs/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/s2i-build/docs/human-in-the-loop.md b/rh-developer/skills/s2i-build/docs/human-in-the-loop.md new file mode 120000 index 00000000..9a524eda --- /dev/null +++ b/rh-developer/skills/s2i-build/docs/human-in-the-loop.md @@ -0,0 +1 @@ +../../validate-environment/docs/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/s2i-build/docs/prerequisites.md b/rh-developer/skills/s2i-build/docs/prerequisites.md new file mode 120000 index 00000000..9572b8c5 --- /dev/null +++ b/rh-developer/skills/s2i-build/docs/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/s2i-build/docs/python-s2i-entrypoints.md b/rh-developer/skills/s2i-build/docs/python-s2i-entrypoints.md new file mode 120000 index 00000000..c3416418 --- /dev/null +++ b/rh-developer/skills/s2i-build/docs/python-s2i-entrypoints.md @@ -0,0 +1 @@ +../../detect-project/docs/python-s2i-entrypoints.md \ No newline at end of file diff --git a/rh-developer/skills/s2i-build/docs/selinux-troubleshooting.md b/rh-developer/skills/s2i-build/docs/selinux-troubleshooting.md new file mode 120000 index 00000000..43136b67 --- /dev/null +++ b/rh-developer/skills/s2i-build/docs/selinux-troubleshooting.md @@ -0,0 +1 @@ +../../rhel-deploy/docs/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/validate-environment/SKILL.md b/rh-developer/skills/validate-environment/SKILL.md index 2b5ae8a5..abd85418 100644 --- a/rh-developer/skills/validate-environment/SKILL.md +++ b/rh-developer/skills/validate-environment/SKILL.md @@ -22,7 +22,7 @@ Check that required tools and environment are properly configured. ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. **Key Rules:** 1. WAIT for user to select validation scope before running checks @@ -65,7 +65,7 @@ check_tool() { **Tools to check:** git, curl, jq, oc, helm, podman, docker, skopeo, ssh -> **See [docs/prerequisites.md](../../docs/prerequisites.md)** for the complete tool requirements by skill, check commands, and installation instructions. +> **See [docs/prerequisites.md](docs/prerequisites.md)** for the complete tool requirements by skill, check commands, and installation instructions. ### Step 3: Check OpenShift Connectivity (if TARGET includes openshift) @@ -185,7 +185,7 @@ Select an option or describe what you'd like to do: This tool is required for [skill-names]. -See [docs/prerequisites.md](../../docs/prerequisites.md) for installation commands by OS. +See [docs/prerequisites.md](docs/prerequisites.md) for installation commands by OS. ``` ### Cluster Connection Failed @@ -231,4 +231,4 @@ Options: - `/deploy` - Deployment requiring oc and cluster access ### Reference Documentation -- [docs/prerequisites.md](../../docs/prerequisites.md) - Comprehensive tool requirements by skill, installation commands, cluster access verification +- [docs/prerequisites.md](docs/prerequisites.md) - Comprehensive tool requirements by skill, installation commands, cluster access verification diff --git a/rh-developer/docs/human-in-the-loop.md b/rh-developer/skills/validate-environment/docs/human-in-the-loop.md similarity index 100% rename from rh-developer/docs/human-in-the-loop.md rename to rh-developer/skills/validate-environment/docs/human-in-the-loop.md diff --git a/rh-developer/docs/prerequisites.md b/rh-developer/skills/validate-environment/docs/prerequisites.md similarity index 100% rename from rh-developer/docs/prerequisites.md rename to rh-developer/skills/validate-environment/docs/prerequisites.md diff --git a/rh-sre/.catalog/collection.json b/rh-sre/.catalog/collection.json index 71455547..afb95e2b 100644 --- a/rh-sre/.catalog/collection.json +++ b/rh-sre/.catalog/collection.json @@ -143,43 +143,43 @@ }, { "description": "Creating remediation plans, playbook generation.", - "embedded_doc": "docs/ansible/cve-remediation-templates.md", + "embedded_doc": "skills/playbook-generator/docs/ansible/cve-remediation-templates.md", "title": "Red Hat Lightspeed Remediations Guide", "url": "https://docs.redhat.com/en/documentation/red_hat_lightspeed/1-latest/html-single/red_hat_lightspeed_remediations_guide/index" }, { "description": "MCP server used by this collection; parameter reference.", - "embedded_doc": "docs/references/lightspeed-mcp-parameters.md", + "embedded_doc": "skills/cve-impact/docs/references/lightspeed-mcp-parameters.md", "title": "Red Hat Lightspeed MCP", "url": "https://github.com/RedHatInsights/insights-mcp" }, { "description": "CVE identification, classification, threat intelligence.", - "embedded_doc": "docs/insights/vulnerability-logic.md", + "embedded_doc": "skills/cve-validation/docs/insights/vulnerability-logic.md", "title": "Assessing and Monitoring Security Vulnerabilities on RHEL Systems", "url": "https://docs.redhat.com/en/documentation/red_hat_lightspeed/1-latest/html/assessing_and_monitoring_security_vulnerabilities_on_rhel_systems/vuln-cves_vuln-overview" }, { "description": "DNF commands, updating packages, repository management.", - "embedded_doc": "docs/rhel/package-management.md", + "embedded_doc": "skills/playbook-generator/docs/rhel/package-management.md", "title": "Managing Software with the DNF Tool (RHEL 9)", "url": "https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html-single/managing_software_with_the_dnf_tool/index" }, { "description": "Red Hat severity ratings, CVSS usage.", - "embedded_doc": "docs/references/cvss-scoring.md", + "embedded_doc": "skills/cve-validation/docs/references/cvss-scoring.md", "title": "Severity Ratings (Red Hat Customer Portal)", "url": "https://access.redhat.com/security/updates/classification" }, { "description": "AAP 2.6 docs; projects, job templates, playbook integration.", - "embedded_doc": "docs/ansible/playbook-integration-aap.md", + "embedded_doc": "skills/playbook-executor/docs/ansible/playbook-integration-aap.md", "title": "Red Hat Ansible Automation Platform Documentation", "url": "https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6" }, { "description": "Job templates, check mode, dry-run execution.", - "embedded_doc": "docs/ansible/aap-job-execution.md", + "embedded_doc": "skills/playbook-executor/docs/ansible/aap-job-execution.md", "title": "AAP Job Execution", "url": "https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/using_automation_execution/controller-job-templates" }, diff --git a/rh-sre/.catalog/collection.yaml b/rh-sre/.catalog/collection.yaml index 1ff0e5cd..0d74e6c1 100644 --- a/rh-sre/.catalog/collection.yaml +++ b/rh-sre/.catalog/collection.yaml @@ -266,31 +266,31 @@ resources: - title: Red Hat Lightspeed Remediations Guide url: https://docs.redhat.com/en/documentation/red_hat_lightspeed/1-latest/html-single/red_hat_lightspeed_remediations_guide/index description: Creating remediation plans, playbook generation. - embedded_doc: docs/ansible/cve-remediation-templates.md + embedded_doc: skills/playbook-generator/docs/ansible/cve-remediation-templates.md - title: Red Hat Lightspeed MCP url: https://github.com/RedHatInsights/insights-mcp description: MCP server used by this collection; parameter reference. - embedded_doc: docs/references/lightspeed-mcp-parameters.md + embedded_doc: skills/cve-impact/docs/references/lightspeed-mcp-parameters.md - title: Assessing and Monitoring Security Vulnerabilities on RHEL Systems url: https://docs.redhat.com/en/documentation/red_hat_lightspeed/1-latest/html/assessing_and_monitoring_security_vulnerabilities_on_rhel_systems/vuln-cves_vuln-overview description: CVE identification, classification, threat intelligence. - embedded_doc: docs/insights/vulnerability-logic.md + embedded_doc: skills/cve-validation/docs/insights/vulnerability-logic.md - title: Managing Software with the DNF Tool (RHEL 9) url: https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html-single/managing_software_with_the_dnf_tool/index description: DNF commands, updating packages, repository management. - embedded_doc: docs/rhel/package-management.md + embedded_doc: skills/playbook-generator/docs/rhel/package-management.md - title: Severity Ratings (Red Hat Customer Portal) url: https://access.redhat.com/security/updates/classification description: Red Hat severity ratings, CVSS usage. - embedded_doc: docs/references/cvss-scoring.md + embedded_doc: skills/cve-validation/docs/references/cvss-scoring.md - title: Red Hat Ansible Automation Platform Documentation url: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6 description: AAP 2.6 docs; projects, job templates, playbook integration. - embedded_doc: docs/ansible/playbook-integration-aap.md + embedded_doc: skills/playbook-executor/docs/ansible/playbook-integration-aap.md - title: AAP Job Execution url: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/using_automation_execution/controller-job-templates description: Job templates, check mode, dry-run execution. - embedded_doc: docs/ansible/aap-job-execution.md + embedded_doc: skills/playbook-executor/docs/ansible/aap-job-execution.md - title: Ansible Automation Platform url: https://www.redhat.com/en/technologies/management/ansible description: AAP product overview for playbook execution. diff --git a/rh-sre/skills/cve-impact/SKILL.md b/rh-sre/skills/cve-impact/SKILL.md index 896af539..33f896c9 100644 --- a/rh-sre/skills/cve-impact/SKILL.md +++ b/rh-sre/skills/cve-impact/SKILL.md @@ -24,7 +24,7 @@ This skill helps SREs analyze CVE vulnerabilities to understand their impact on ## Invocation Note (Host-Specific) -When invoked by another skill (e.g. remediation), use the Skill tool—do NOT use "Task Output" with the skill name as task ID. That causes "No task found with ID: cve-impact". See [skill-invocation.md](../../../docs/references/skill-invocation.md). +When invoked by another skill (e.g. remediation), use the Skill tool—do NOT use "Task Output" with the skill name as task ID. That causes "No task found with ID: cve-impact". See [skill-invocation.md](docs/references/skill-invocation.md). ## Prerequisites @@ -185,8 +185,8 @@ How would you like to proceed? (first page / all pages / N pages) **CRITICAL**: Document consultation MUST happen BEFORE tool invocation. **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [cvss-scoring.md](../../docs/references/cvss-scoring.md) using the Read tool to understand CVSS score interpretation and severity mapping -2. **Output to user**: "I consulted [cvss-scoring.md](../../docs/references/cvss-scoring.md) to understand CVSS score interpretation and severity mapping." +1. **Action**: Read [cvss-scoring.md](docs/references/cvss-scoring.md) using the Read tool to understand CVSS score interpretation and severity mapping +2. **Output to user**: "I consulted [cvss-scoring.md](docs/references/cvss-scoring.md) to understand CVSS score interpretation and severity mapping." **MCP Tool**: `get_cve` or `vulnerability__get_cve` (from lightspeed-mcp) @@ -222,8 +222,8 @@ Last Modified: YYYY-MM-DD **CRITICAL**: Document consultation MUST happen BEFORE tool invocation. **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [insights-api.md](../../docs/insights/insights-api.md) using the Read tool to understand the system identification response format -2. **Output to user**: "I consulted [insights-api.md](../../docs/insights/insights-api.md) to understand the system identification response format." +1. **Action**: Read [insights-api.md](docs/insights/insights-api.md) using the Read tool to understand the system identification response format +2. **Output to user**: "I consulted [insights-api.md](docs/insights/insights-api.md) to understand the system identification response format." **MCP Tool**: `get_cve_systems` or `vulnerability__get_cve_systems` (from lightspeed-mcp) @@ -253,8 +253,8 @@ Total Affected Systems: N **CRITICAL**: Document consultation MUST happen BEFORE classification logic. **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [fleet-management.md](../../docs/insights/fleet-management.md) using the Read tool to understand system tagging and classification strategies -2. **Output to user**: "I consulted [fleet-management.md](../../docs/insights/fleet-management.md) to understand system tagging and classification strategies." +1. **Action**: Read [fleet-management.md](docs/insights/fleet-management.md) using the Read tool to understand system tagging and classification strategies +2. **Output to user**: "I consulted [fleet-management.md](docs/insights/fleet-management.md) to understand system tagging and classification strategies." Classify affected systems by environment and criticality based on tags from Red Hat Lightspeed: ``` @@ -271,8 +271,8 @@ System Classification: **CRITICAL**: Document consultation MUST happen BEFORE risk assessment. **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [cvss-scoring.md](../../docs/references/cvss-scoring.md) using the Read tool to understand risk prioritization based on CVSS vectors -2. **Output to user**: "I consulted [cvss-scoring.md](../../docs/references/cvss-scoring.md) to understand risk prioritization based on CVSS vectors." +1. **Action**: Read [cvss-scoring.md](docs/references/cvss-scoring.md) using the Read tool to understand risk prioritization based on CVSS vectors +2. **Output to user**: "I consulted [cvss-scoring.md](docs/references/cvss-scoring.md) to understand risk prioritization based on CVSS vectors." Provide a risk assessment based on: - CVSS score and severity @@ -326,7 +326,7 @@ Check if automated playbook or manual steps are available. | [03-output-templates.md](references/03-output-templates.md) | Report format | | [04-examples.md](references/04-examples.md) | Query-type examples | | [05-error-handling.md](references/05-error-handling.md) | CVE not found, no systems, Lightspeed failures | -| [lightspeed-mcp-tool-failures.md](../../../docs/references/lightspeed-mcp-tool-failures.md) | explain_cves dnf_modules workaround | +| [lightspeed-mcp-tool-failures.md](docs/references/lightspeed-mcp-tool-failures.md) | explain_cves dnf_modules workaround | ## Parsing MCP Responses @@ -393,10 +393,10 @@ Save each MCP tool result to a file, then run the parser with one or more paths. - Purpose: Understand overall infrastructure before assessing CVE impact ### Reference Documentation -- [cvss-scoring.md](../../docs/references/cvss-scoring.md) - CVSS score interpretation and severity mapping -- [vulnerability-logic.md](../../docs/insights/vulnerability-logic.md) - CVE severity classification and filtering -- [insights-api.md](../../docs/insights/insights-api.md) - System identification response format -- [fleet-management.md](../../docs/insights/fleet-management.md) - System tagging and classification strategies +- [cvss-scoring.md](docs/references/cvss-scoring.md) - CVSS score interpretation and severity mapping +- [vulnerability-logic.md](docs/insights/vulnerability-logic.md) - CVE severity classification and filtering +- [insights-api.md](docs/insights/insights-api.md) - System identification response format +- [fleet-management.md](docs/insights/fleet-management.md) - System tagging and classification strategies - [references/02-cve-parsing-guide.md](references/02-cve-parsing-guide.md) - Parse MCP vulnerability responses; use the parser script instead of generating inline Python ## Tools Reference diff --git a/rh-sre/skills/cve-impact/docs/SOURCES.md b/rh-sre/skills/cve-impact/docs/SOURCES.md new file mode 120000 index 00000000..50989401 --- /dev/null +++ b/rh-sre/skills/cve-impact/docs/SOURCES.md @@ -0,0 +1 @@ +../../../docs/SOURCES.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/ansible/aap-integration.md b/rh-sre/skills/cve-impact/docs/ansible/aap-integration.md new file mode 120000 index 00000000..e9f9036f --- /dev/null +++ b/rh-sre/skills/cve-impact/docs/ansible/aap-integration.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/ansible/aap-integration.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/ansible/cve-remediation-templates.md b/rh-sre/skills/cve-impact/docs/ansible/cve-remediation-templates.md new file mode 120000 index 00000000..269e56f2 --- /dev/null +++ b/rh-sre/skills/cve-impact/docs/ansible/cve-remediation-templates.md @@ -0,0 +1 @@ +../../../playbook-generator/docs/ansible/cve-remediation-templates.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/ansible/error-handling.md b/rh-sre/skills/cve-impact/docs/ansible/error-handling.md new file mode 120000 index 00000000..c4b7b276 --- /dev/null +++ b/rh-sre/skills/cve-impact/docs/ansible/error-handling.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/ansible/error-handling.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/ansible/idempotency.md b/rh-sre/skills/cve-impact/docs/ansible/idempotency.md new file mode 120000 index 00000000..c97ef9a0 --- /dev/null +++ b/rh-sre/skills/cve-impact/docs/ansible/idempotency.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/ansible/idempotency.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/insights/fleet-management.md b/rh-sre/skills/cve-impact/docs/insights/fleet-management.md new file mode 120000 index 00000000..8ecd1956 --- /dev/null +++ b/rh-sre/skills/cve-impact/docs/insights/fleet-management.md @@ -0,0 +1 @@ +../../../fleet-inventory/docs/insights/fleet-management.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/insights/insights-api.md b/rh-sre/skills/cve-impact/docs/insights/insights-api.md new file mode 120000 index 00000000..48ae0c69 --- /dev/null +++ b/rh-sre/skills/cve-impact/docs/insights/insights-api.md @@ -0,0 +1 @@ +../../../fleet-inventory/docs/insights/insights-api.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/insights/vulnerability-logic.md b/rh-sre/skills/cve-impact/docs/insights/vulnerability-logic.md new file mode 120000 index 00000000..a4b16aa8 --- /dev/null +++ b/rh-sre/skills/cve-impact/docs/insights/vulnerability-logic.md @@ -0,0 +1 @@ +../../../cve-validation/docs/insights/vulnerability-logic.md \ No newline at end of file diff --git a/rh-sre/docs/references/README.md b/rh-sre/skills/cve-impact/docs/references/README.md similarity index 100% rename from rh-sre/docs/references/README.md rename to rh-sre/skills/cve-impact/docs/references/README.md diff --git a/rh-sre/skills/cve-impact/docs/references/compliance-frameworks.md b/rh-sre/skills/cve-impact/docs/references/compliance-frameworks.md new file mode 120000 index 00000000..333cdfdf --- /dev/null +++ b/rh-sre/skills/cve-impact/docs/references/compliance-frameworks.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/references/compliance-frameworks.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/references/cvss-scoring.md b/rh-sre/skills/cve-impact/docs/references/cvss-scoring.md new file mode 120000 index 00000000..30fd4ef7 --- /dev/null +++ b/rh-sre/skills/cve-impact/docs/references/cvss-scoring.md @@ -0,0 +1 @@ +../../../cve-validation/docs/references/cvss-scoring.md \ No newline at end of file diff --git a/rh-sre/docs/references/lightspeed-mcp-parameters.md b/rh-sre/skills/cve-impact/docs/references/lightspeed-mcp-parameters.md similarity index 100% rename from rh-sre/docs/references/lightspeed-mcp-parameters.md rename to rh-sre/skills/cve-impact/docs/references/lightspeed-mcp-parameters.md diff --git a/rh-sre/docs/references/lightspeed-mcp-tool-failures.md b/rh-sre/skills/cve-impact/docs/references/lightspeed-mcp-tool-failures.md similarity index 100% rename from rh-sre/docs/references/lightspeed-mcp-tool-failures.md rename to rh-sre/skills/cve-impact/docs/references/lightspeed-mcp-tool-failures.md diff --git a/rh-sre/skills/cve-impact/docs/references/skill-invocation.md b/rh-sre/skills/cve-impact/docs/references/skill-invocation.md new file mode 120000 index 00000000..f7e6fef0 --- /dev/null +++ b/rh-sre/skills/cve-impact/docs/references/skill-invocation.md @@ -0,0 +1 @@ +../../../remediation/docs/references/skill-invocation.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/rhel/package-management.md b/rh-sre/skills/cve-impact/docs/rhel/package-management.md new file mode 120000 index 00000000..65fda622 --- /dev/null +++ b/rh-sre/skills/cve-impact/docs/rhel/package-management.md @@ -0,0 +1 @@ +../../../playbook-generator/docs/rhel/package-management.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/rhel/selinux-context.md b/rh-sre/skills/cve-impact/docs/rhel/selinux-context.md new file mode 120000 index 00000000..5159d6cf --- /dev/null +++ b/rh-sre/skills/cve-impact/docs/rhel/selinux-context.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/rhel/selinux-context.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/rhel/systemd-services.md b/rh-sre/skills/cve-impact/docs/rhel/systemd-services.md new file mode 120000 index 00000000..a3bbcb2c --- /dev/null +++ b/rh-sre/skills/cve-impact/docs/rhel/systemd-services.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/rhel/systemd-services.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/rhel/version-compatibility.md b/rh-sre/skills/cve-impact/docs/rhel/version-compatibility.md new file mode 120000 index 00000000..1f952f5c --- /dev/null +++ b/rh-sre/skills/cve-impact/docs/rhel/version-compatibility.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/rhel/version-compatibility.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/SKILL.md b/rh-sre/skills/cve-validation/SKILL.md index 13b0b113..5ce9c6c0 100644 --- a/rh-sre/skills/cve-validation/SKILL.md +++ b/rh-sre/skills/cve-validation/SKILL.md @@ -31,7 +31,7 @@ This skill validates CVE identifiers and checks remediation availability in Red ## Invocation Note (Host-Specific) -When invoked by another skill (e.g. remediation), use the Skill tool—do NOT use "Task Output" with the skill name as task ID. That causes "No task found with ID: cve-validation". See [skill-invocation.md](../../../docs/references/skill-invocation.md). +When invoked by another skill (e.g. remediation), use the Skill tool—do NOT use "Task Output" with the skill name as task ID. That causes "No task found with ID: cve-validation". See [skill-invocation.md](docs/references/skill-invocation.md). ## Prerequisites @@ -138,9 +138,9 @@ Let the API determine existence. A 404 from get_cve means "not found"; format va **CRITICAL**: Document consultation MUST happen BEFORE tool invocation. **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [vulnerability-logic.md](../../docs/insights/vulnerability-logic.md) using the Read tool to understand CVE validation criteria +1. **Action**: Read [vulnerability-logic.md](docs/insights/vulnerability-logic.md) using the Read tool to understand CVE validation criteria 2. **Action**: Read [references/01-remediation-indicators.md](references/01-remediation-indicators.md) to interpret get_cve response—**CRITICAL** to avoid misinterpreting remediation availability -3. **Output to user**: "I consulted [vulnerability-logic.md](../../docs/insights/vulnerability-logic.md) and [01-remediation-indicators.md](references/01-remediation-indicators.md) for CVE validation and remediation indicator interpretation." +3. **Output to user**: "I consulted [vulnerability-logic.md](docs/insights/vulnerability-logic.md) and [01-remediation-indicators.md](references/01-remediation-indicators.md) for CVE validation and remediation indicator interpretation." **MCP Tool**: `get_cve` or `vulnerability__get_cve` (from lightspeed-mcp) @@ -191,8 +191,8 @@ Retrieve CVE metadata from Red Hat Lightspeed: **CRITICAL**: Document consultation MUST happen BEFORE validation logic. **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [cvss-scoring.md](../../docs/references/cvss-scoring.md) using the Read tool to understand Red Hat severity classification and CVSS score ranges -2. **Output to user**: "I consulted [cvss-scoring.md](../../docs/references/cvss-scoring.md) to understand Red Hat severity classification and CVSS score ranges." +1. **Action**: Read [cvss-scoring.md](docs/references/cvss-scoring.md) using the Read tool to understand Red Hat severity classification and CVSS score ranges +2. **Output to user**: "I consulted [cvss-scoring.md](docs/references/cvss-scoring.md) to understand Red Hat severity classification and CVSS score ranges." Perform comprehensive validation: @@ -331,10 +331,10 @@ Validate format first; if regex matches, ALWAYS call get_cve (do not reject on y - Purpose: Create automated remediation for valid, remediable CVEs ### Reference Documentation -- [vulnerability-logic.md](../../docs/insights/vulnerability-logic.md) - CVE validation criteria +- [vulnerability-logic.md](docs/insights/vulnerability-logic.md) - CVE validation criteria - [references/01-remediation-indicators.md](references/01-remediation-indicators.md) - **REQUIRED** - Correct interpretation of get_cve response (advisory_available, remediation, advisories_list). Do NOT use rules[] for remediation decision. -- [cvss-scoring.md](../../docs/references/cvss-scoring.md) - Red Hat severity classification and CVSS score ranges -- [cve-remediation-templates.md](../../docs/ansible/cve-remediation-templates.md) - Manual remediation templates for CVEs without automated playbooks +- [cvss-scoring.md](docs/references/cvss-scoring.md) - Red Hat severity classification and CVSS score ranges +- [cve-remediation-templates.md](docs/ansible/cve-remediation-templates.md) - Manual remediation templates for CVEs without automated playbooks ## Tools Reference diff --git a/rh-sre/skills/cve-validation/docs/ansible/aap-integration.md b/rh-sre/skills/cve-validation/docs/ansible/aap-integration.md new file mode 120000 index 00000000..e9f9036f --- /dev/null +++ b/rh-sre/skills/cve-validation/docs/ansible/aap-integration.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/ansible/aap-integration.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/docs/ansible/cve-remediation-templates.md b/rh-sre/skills/cve-validation/docs/ansible/cve-remediation-templates.md new file mode 120000 index 00000000..269e56f2 --- /dev/null +++ b/rh-sre/skills/cve-validation/docs/ansible/cve-remediation-templates.md @@ -0,0 +1 @@ +../../../playbook-generator/docs/ansible/cve-remediation-templates.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/docs/ansible/error-handling.md b/rh-sre/skills/cve-validation/docs/ansible/error-handling.md new file mode 120000 index 00000000..c4b7b276 --- /dev/null +++ b/rh-sre/skills/cve-validation/docs/ansible/error-handling.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/ansible/error-handling.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/docs/ansible/idempotency.md b/rh-sre/skills/cve-validation/docs/ansible/idempotency.md new file mode 120000 index 00000000..c97ef9a0 --- /dev/null +++ b/rh-sre/skills/cve-validation/docs/ansible/idempotency.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/ansible/idempotency.md \ No newline at end of file diff --git a/rh-sre/docs/insights/vulnerability-logic.md b/rh-sre/skills/cve-validation/docs/insights/vulnerability-logic.md similarity index 100% rename from rh-sre/docs/insights/vulnerability-logic.md rename to rh-sre/skills/cve-validation/docs/insights/vulnerability-logic.md diff --git a/rh-sre/skills/cve-validation/docs/references/compliance-frameworks.md b/rh-sre/skills/cve-validation/docs/references/compliance-frameworks.md new file mode 120000 index 00000000..333cdfdf --- /dev/null +++ b/rh-sre/skills/cve-validation/docs/references/compliance-frameworks.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/references/compliance-frameworks.md \ No newline at end of file diff --git a/rh-sre/docs/references/cvss-scoring.md b/rh-sre/skills/cve-validation/docs/references/cvss-scoring.md similarity index 100% rename from rh-sre/docs/references/cvss-scoring.md rename to rh-sre/skills/cve-validation/docs/references/cvss-scoring.md diff --git a/rh-sre/skills/cve-validation/docs/references/skill-invocation.md b/rh-sre/skills/cve-validation/docs/references/skill-invocation.md new file mode 120000 index 00000000..f7e6fef0 --- /dev/null +++ b/rh-sre/skills/cve-validation/docs/references/skill-invocation.md @@ -0,0 +1 @@ +../../../remediation/docs/references/skill-invocation.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/docs/rhel/package-management.md b/rh-sre/skills/cve-validation/docs/rhel/package-management.md new file mode 120000 index 00000000..65fda622 --- /dev/null +++ b/rh-sre/skills/cve-validation/docs/rhel/package-management.md @@ -0,0 +1 @@ +../../../playbook-generator/docs/rhel/package-management.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/docs/rhel/selinux-context.md b/rh-sre/skills/cve-validation/docs/rhel/selinux-context.md new file mode 120000 index 00000000..5159d6cf --- /dev/null +++ b/rh-sre/skills/cve-validation/docs/rhel/selinux-context.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/rhel/selinux-context.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/docs/rhel/systemd-services.md b/rh-sre/skills/cve-validation/docs/rhel/systemd-services.md new file mode 120000 index 00000000..a3bbcb2c --- /dev/null +++ b/rh-sre/skills/cve-validation/docs/rhel/systemd-services.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/rhel/systemd-services.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/docs/rhel/version-compatibility.md b/rh-sre/skills/cve-validation/docs/rhel/version-compatibility.md new file mode 120000 index 00000000..1f952f5c --- /dev/null +++ b/rh-sre/skills/cve-validation/docs/rhel/version-compatibility.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/rhel/version-compatibility.md \ No newline at end of file diff --git a/rh-sre/skills/fleet-inventory/SKILL.md b/rh-sre/skills/fleet-inventory/SKILL.md index 17ed2a79..fff3ffa0 100644 --- a/rh-sre/skills/fleet-inventory/SKILL.md +++ b/rh-sre/skills/fleet-inventory/SKILL.md @@ -100,8 +100,8 @@ Proceeding with fleet inventory query... ### Step 1: Retrieve System Inventory **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [insights-api.md](../../docs/insights/insights-api.md) using the Read tool to understand the `get_host_details` response format and pagination handling -2. **Output to user**: "I consulted [insights-api.md](../../docs/insights/insights-api.md) to understand the `get_host_details` response format and pagination handling." +1. **Action**: Read [insights-api.md](docs/insights/insights-api.md) using the Read tool to understand the `get_host_details` response format and pagination handling +2. **Output to user**: "I consulted [insights-api.md](docs/insights/insights-api.md) to understand the `get_host_details` response format and pagination handling." **MCP Tool**: `get_host_details` (from lightspeed-mcp) @@ -126,8 +126,8 @@ Proceeding with fleet inventory query... ### Step 2: Filter and Organize Systems **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [fleet-management.md](../../docs/insights/fleet-management.md) using the Read tool to understand fleet inventory reporting structure and best practices -2. **Output to user**: "I consulted [fleet-management.md](../../docs/insights/fleet-management.md) to structure this inventory report." +1. **Action**: Read [fleet-management.md](docs/insights/fleet-management.md) using the Read tool to understand fleet inventory reporting structure and best practices +2. **Output to user**: "I consulted [fleet-management.md](docs/insights/fleet-management.md) to structure this inventory report." Apply user-requested filters and grouping. See [references/01-parameter-reference.md](references/01-parameter-reference.md) for filtering and sorting patterns. @@ -218,8 +218,8 @@ Examples: - Use after: "Show affected systems" → "Remediate those systems" ### Reference Documentation -- [insights-api.md](../../docs/insights/insights-api.md) - Red Hat Lightspeed API patterns and response formats -- [fleet-management.md](../../docs/insights/fleet-management.md) - System inventory best practices and filtering strategies +- [insights-api.md](docs/insights/insights-api.md) - Red Hat Lightspeed API patterns and response formats +- [fleet-management.md](docs/insights/fleet-management.md) - System inventory best practices and filtering strategies ### Skill Orchestration Pattern diff --git a/rh-sre/skills/fleet-inventory/docs/insights/fleet-management.md b/rh-sre/skills/fleet-inventory/docs/insights/fleet-management.md new file mode 100644 index 00000000..daef71c2 --- /dev/null +++ b/rh-sre/skills/fleet-inventory/docs/insights/fleet-management.md @@ -0,0 +1,11 @@ +--- +title: TODO +status: draft +--- + +# TODO + +Placeholder stub created during skill-local docs migration. + +- Keep link targets valid for migration PR review. +- Content will be authored in a follow-up PR. diff --git a/rh-sre/skills/fleet-inventory/docs/insights/insights-api.md b/rh-sre/skills/fleet-inventory/docs/insights/insights-api.md new file mode 100644 index 00000000..daef71c2 --- /dev/null +++ b/rh-sre/skills/fleet-inventory/docs/insights/insights-api.md @@ -0,0 +1,11 @@ +--- +title: TODO +status: draft +--- + +# TODO + +Placeholder stub created during skill-local docs migration. + +- Keep link targets valid for migration PR review. +- Content will be authored in a follow-up PR. diff --git a/rh-sre/skills/mcp-aap-validator/SKILL.md b/rh-sre/skills/mcp-aap-validator/SKILL.md index b97247fa..1ba827f9 100644 --- a/rh-sre/skills/mcp-aap-validator/SKILL.md +++ b/rh-sre/skills/mcp-aap-validator/SKILL.md @@ -72,4 +72,4 @@ Use ✅ for success, ❌ for failure, ⚠️ for partial (e.g. one server OK, on - `/job-template-creator` - Requires AAP MCP validation before template operations ### Reference Documentation -- [AAP Integration Test Guide](../../docs/testing/aap-integration-test-guide.md) - AAP MCP setup, env vars, connectivity verification +- [AAP Integration Test Guide](docs/testing/aap-integration-test-guide.md) - AAP MCP setup, env vars, connectivity verification diff --git a/rh-sre/skills/mcp-aap-validator/docs/ansible/aap-integration.md b/rh-sre/skills/mcp-aap-validator/docs/ansible/aap-integration.md new file mode 100644 index 00000000..30e219e7 --- /dev/null +++ b/rh-sre/skills/mcp-aap-validator/docs/ansible/aap-integration.md @@ -0,0 +1,8 @@ +--- +title: TODO +status: draft +--- + +# TODO + +Placeholder created to satisfy skill-local docs link integrity. diff --git a/rh-sre/skills/mcp-aap-validator/docs/ansible/aap-job-execution.md b/rh-sre/skills/mcp-aap-validator/docs/ansible/aap-job-execution.md new file mode 120000 index 00000000..31d880e7 --- /dev/null +++ b/rh-sre/skills/mcp-aap-validator/docs/ansible/aap-job-execution.md @@ -0,0 +1 @@ +../../../playbook-executor/docs/ansible/aap-job-execution.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-aap-validator/docs/ansible/cve-remediation-templates.md b/rh-sre/skills/mcp-aap-validator/docs/ansible/cve-remediation-templates.md new file mode 120000 index 00000000..269e56f2 --- /dev/null +++ b/rh-sre/skills/mcp-aap-validator/docs/ansible/cve-remediation-templates.md @@ -0,0 +1 @@ +../../../playbook-generator/docs/ansible/cve-remediation-templates.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-aap-validator/docs/ansible/error-handling.md b/rh-sre/skills/mcp-aap-validator/docs/ansible/error-handling.md new file mode 100644 index 00000000..30e219e7 --- /dev/null +++ b/rh-sre/skills/mcp-aap-validator/docs/ansible/error-handling.md @@ -0,0 +1,8 @@ +--- +title: TODO +status: draft +--- + +# TODO + +Placeholder created to satisfy skill-local docs link integrity. diff --git a/rh-sre/skills/mcp-aap-validator/docs/ansible/idempotency.md b/rh-sre/skills/mcp-aap-validator/docs/ansible/idempotency.md new file mode 100644 index 00000000..30e219e7 --- /dev/null +++ b/rh-sre/skills/mcp-aap-validator/docs/ansible/idempotency.md @@ -0,0 +1,8 @@ +--- +title: TODO +status: draft +--- + +# TODO + +Placeholder created to satisfy skill-local docs link integrity. diff --git a/rh-sre/skills/mcp-aap-validator/docs/ansible/playbook-integration-aap.md b/rh-sre/skills/mcp-aap-validator/docs/ansible/playbook-integration-aap.md new file mode 120000 index 00000000..e6e5e180 --- /dev/null +++ b/rh-sre/skills/mcp-aap-validator/docs/ansible/playbook-integration-aap.md @@ -0,0 +1 @@ +../../../playbook-executor/docs/ansible/playbook-integration-aap.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-aap-validator/docs/insights/vulnerability-logic.md b/rh-sre/skills/mcp-aap-validator/docs/insights/vulnerability-logic.md new file mode 120000 index 00000000..a4b16aa8 --- /dev/null +++ b/rh-sre/skills/mcp-aap-validator/docs/insights/vulnerability-logic.md @@ -0,0 +1 @@ +../../../cve-validation/docs/insights/vulnerability-logic.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-aap-validator/docs/references/compliance-frameworks.md b/rh-sre/skills/mcp-aap-validator/docs/references/compliance-frameworks.md new file mode 100644 index 00000000..720ddea0 --- /dev/null +++ b/rh-sre/skills/mcp-aap-validator/docs/references/compliance-frameworks.md @@ -0,0 +1,8 @@ +--- +title: TODO +status: draft +--- + +# TODO + +Placeholder — content pending. diff --git a/rh-sre/skills/mcp-aap-validator/docs/references/cvss-scoring.md b/rh-sre/skills/mcp-aap-validator/docs/references/cvss-scoring.md new file mode 120000 index 00000000..30fd4ef7 --- /dev/null +++ b/rh-sre/skills/mcp-aap-validator/docs/references/cvss-scoring.md @@ -0,0 +1 @@ +../../../cve-validation/docs/references/cvss-scoring.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-aap-validator/docs/rhel/package-management.md b/rh-sre/skills/mcp-aap-validator/docs/rhel/package-management.md new file mode 120000 index 00000000..65fda622 --- /dev/null +++ b/rh-sre/skills/mcp-aap-validator/docs/rhel/package-management.md @@ -0,0 +1 @@ +../../../playbook-generator/docs/rhel/package-management.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-aap-validator/docs/rhel/selinux-context.md b/rh-sre/skills/mcp-aap-validator/docs/rhel/selinux-context.md new file mode 100644 index 00000000..30e219e7 --- /dev/null +++ b/rh-sre/skills/mcp-aap-validator/docs/rhel/selinux-context.md @@ -0,0 +1,8 @@ +--- +title: TODO +status: draft +--- + +# TODO + +Placeholder created to satisfy skill-local docs link integrity. diff --git a/rh-sre/skills/mcp-aap-validator/docs/rhel/systemd-services.md b/rh-sre/skills/mcp-aap-validator/docs/rhel/systemd-services.md new file mode 100644 index 00000000..30e219e7 --- /dev/null +++ b/rh-sre/skills/mcp-aap-validator/docs/rhel/systemd-services.md @@ -0,0 +1,8 @@ +--- +title: TODO +status: draft +--- + +# TODO + +Placeholder created to satisfy skill-local docs link integrity. diff --git a/rh-sre/skills/mcp-aap-validator/docs/rhel/version-compatibility.md b/rh-sre/skills/mcp-aap-validator/docs/rhel/version-compatibility.md new file mode 100644 index 00000000..30e219e7 --- /dev/null +++ b/rh-sre/skills/mcp-aap-validator/docs/rhel/version-compatibility.md @@ -0,0 +1,8 @@ +--- +title: TODO +status: draft +--- + +# TODO + +Placeholder created to satisfy skill-local docs link integrity. diff --git a/rh-sre/docs/testing/aap-integration-test-guide.md b/rh-sre/skills/mcp-aap-validator/docs/testing/aap-integration-test-guide.md similarity index 100% rename from rh-sre/docs/testing/aap-integration-test-guide.md rename to rh-sre/skills/mcp-aap-validator/docs/testing/aap-integration-test-guide.md diff --git a/rh-sre/skills/mcp-lightspeed-validator/SKILL.md b/rh-sre/skills/mcp-lightspeed-validator/SKILL.md index a0b44717..f1b4fd6a 100644 --- a/rh-sre/skills/mcp-lightspeed-validator/SKILL.md +++ b/rh-sre/skills/mcp-lightspeed-validator/SKILL.md @@ -67,4 +67,4 @@ Use ✅ for success, ❌ for failure, ⚠️ for partial (e.g. connected but err - `/cve-validation`, `/cve-impact`, `/fleet-inventory` - All require Lightspeed MCP ### Reference Documentation -- [Red Hat Lightspeed Documentation Overview](../../docs/insights/README.md) - Lightspeed setup, CVE assessment, vulnerability logic +- [Red Hat Lightspeed Documentation Overview](docs/insights/README.md) - Lightspeed setup, CVE assessment, vulnerability logic diff --git a/rh-sre/skills/mcp-lightspeed-validator/docs/SOURCES.md b/rh-sre/skills/mcp-lightspeed-validator/docs/SOURCES.md new file mode 120000 index 00000000..50989401 --- /dev/null +++ b/rh-sre/skills/mcp-lightspeed-validator/docs/SOURCES.md @@ -0,0 +1 @@ +../../../docs/SOURCES.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/docs/ansible/aap-integration.md b/rh-sre/skills/mcp-lightspeed-validator/docs/ansible/aap-integration.md new file mode 120000 index 00000000..e9f9036f --- /dev/null +++ b/rh-sre/skills/mcp-lightspeed-validator/docs/ansible/aap-integration.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/ansible/aap-integration.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/docs/ansible/cve-remediation-templates.md b/rh-sre/skills/mcp-lightspeed-validator/docs/ansible/cve-remediation-templates.md new file mode 120000 index 00000000..269e56f2 --- /dev/null +++ b/rh-sre/skills/mcp-lightspeed-validator/docs/ansible/cve-remediation-templates.md @@ -0,0 +1 @@ +../../../playbook-generator/docs/ansible/cve-remediation-templates.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/docs/ansible/error-handling.md b/rh-sre/skills/mcp-lightspeed-validator/docs/ansible/error-handling.md new file mode 120000 index 00000000..c4b7b276 --- /dev/null +++ b/rh-sre/skills/mcp-lightspeed-validator/docs/ansible/error-handling.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/ansible/error-handling.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/docs/ansible/idempotency.md b/rh-sre/skills/mcp-lightspeed-validator/docs/ansible/idempotency.md new file mode 120000 index 00000000..c97ef9a0 --- /dev/null +++ b/rh-sre/skills/mcp-lightspeed-validator/docs/ansible/idempotency.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/ansible/idempotency.md \ No newline at end of file diff --git a/rh-sre/docs/insights/README.md b/rh-sre/skills/mcp-lightspeed-validator/docs/insights/README.md similarity index 100% rename from rh-sre/docs/insights/README.md rename to rh-sre/skills/mcp-lightspeed-validator/docs/insights/README.md diff --git a/rh-sre/skills/mcp-lightspeed-validator/docs/insights/vulnerability-logic.md b/rh-sre/skills/mcp-lightspeed-validator/docs/insights/vulnerability-logic.md new file mode 120000 index 00000000..a4b16aa8 --- /dev/null +++ b/rh-sre/skills/mcp-lightspeed-validator/docs/insights/vulnerability-logic.md @@ -0,0 +1 @@ +../../../cve-validation/docs/insights/vulnerability-logic.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/docs/references/compliance-frameworks.md b/rh-sre/skills/mcp-lightspeed-validator/docs/references/compliance-frameworks.md new file mode 120000 index 00000000..333cdfdf --- /dev/null +++ b/rh-sre/skills/mcp-lightspeed-validator/docs/references/compliance-frameworks.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/references/compliance-frameworks.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/docs/references/cvss-scoring.md b/rh-sre/skills/mcp-lightspeed-validator/docs/references/cvss-scoring.md new file mode 120000 index 00000000..30fd4ef7 --- /dev/null +++ b/rh-sre/skills/mcp-lightspeed-validator/docs/references/cvss-scoring.md @@ -0,0 +1 @@ +../../../cve-validation/docs/references/cvss-scoring.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/docs/rhel/package-management.md b/rh-sre/skills/mcp-lightspeed-validator/docs/rhel/package-management.md new file mode 120000 index 00000000..65fda622 --- /dev/null +++ b/rh-sre/skills/mcp-lightspeed-validator/docs/rhel/package-management.md @@ -0,0 +1 @@ +../../../playbook-generator/docs/rhel/package-management.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/docs/rhel/selinux-context.md b/rh-sre/skills/mcp-lightspeed-validator/docs/rhel/selinux-context.md new file mode 120000 index 00000000..5159d6cf --- /dev/null +++ b/rh-sre/skills/mcp-lightspeed-validator/docs/rhel/selinux-context.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/rhel/selinux-context.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/docs/rhel/systemd-services.md b/rh-sre/skills/mcp-lightspeed-validator/docs/rhel/systemd-services.md new file mode 120000 index 00000000..a3bbcb2c --- /dev/null +++ b/rh-sre/skills/mcp-lightspeed-validator/docs/rhel/systemd-services.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/rhel/systemd-services.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/docs/rhel/version-compatibility.md b/rh-sre/skills/mcp-lightspeed-validator/docs/rhel/version-compatibility.md new file mode 120000 index 00000000..1f952f5c --- /dev/null +++ b/rh-sre/skills/mcp-lightspeed-validator/docs/rhel/version-compatibility.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/rhel/version-compatibility.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/SKILL.md b/rh-sre/skills/playbook-executor/SKILL.md index d751547c..1498469a 100644 --- a/rh-sre/skills/playbook-executor/SKILL.md +++ b/rh-sre/skills/playbook-executor/SKILL.md @@ -413,8 +413,8 @@ If user chooses relaunch: **MCP Tool** `jobs_relaunch_retrieve` with `hosts: "fa ### Reference Documentation - [references/](references/) - Step-numbered reference files (01–05) for templates and examples -- [AAP Job Execution Guide](../../docs/ansible/aap-job-execution.md) - AAP job execution best practices -- [Playbook Integration with AAP](../../docs/ansible/playbook-integration-aap.md) - Playbook-to-AAP workflow +- [AAP Job Execution Guide](docs/ansible/aap-job-execution.md) - AAP job execution best practices +- [Playbook Integration with AAP](docs/ansible/playbook-integration-aap.md) - Playbook-to-AAP workflow ## Critical: Human-in-the-Loop Requirements diff --git a/rh-sre/skills/playbook-executor/docs/ansible/aap-integration.md b/rh-sre/skills/playbook-executor/docs/ansible/aap-integration.md new file mode 120000 index 00000000..e9f9036f --- /dev/null +++ b/rh-sre/skills/playbook-executor/docs/ansible/aap-integration.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/ansible/aap-integration.md \ No newline at end of file diff --git a/rh-sre/docs/ansible/aap-job-execution.md b/rh-sre/skills/playbook-executor/docs/ansible/aap-job-execution.md similarity index 100% rename from rh-sre/docs/ansible/aap-job-execution.md rename to rh-sre/skills/playbook-executor/docs/ansible/aap-job-execution.md diff --git a/rh-sre/skills/playbook-executor/docs/ansible/cve-remediation-templates.md b/rh-sre/skills/playbook-executor/docs/ansible/cve-remediation-templates.md new file mode 120000 index 00000000..269e56f2 --- /dev/null +++ b/rh-sre/skills/playbook-executor/docs/ansible/cve-remediation-templates.md @@ -0,0 +1 @@ +../../../playbook-generator/docs/ansible/cve-remediation-templates.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/docs/ansible/error-handling.md b/rh-sre/skills/playbook-executor/docs/ansible/error-handling.md new file mode 120000 index 00000000..c4b7b276 --- /dev/null +++ b/rh-sre/skills/playbook-executor/docs/ansible/error-handling.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/ansible/error-handling.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/docs/ansible/idempotency.md b/rh-sre/skills/playbook-executor/docs/ansible/idempotency.md new file mode 120000 index 00000000..c97ef9a0 --- /dev/null +++ b/rh-sre/skills/playbook-executor/docs/ansible/idempotency.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/ansible/idempotency.md \ No newline at end of file diff --git a/rh-sre/docs/ansible/playbook-integration-aap.md b/rh-sre/skills/playbook-executor/docs/ansible/playbook-integration-aap.md similarity index 100% rename from rh-sre/docs/ansible/playbook-integration-aap.md rename to rh-sre/skills/playbook-executor/docs/ansible/playbook-integration-aap.md diff --git a/rh-sre/skills/playbook-executor/docs/insights/vulnerability-logic.md b/rh-sre/skills/playbook-executor/docs/insights/vulnerability-logic.md new file mode 120000 index 00000000..a4b16aa8 --- /dev/null +++ b/rh-sre/skills/playbook-executor/docs/insights/vulnerability-logic.md @@ -0,0 +1 @@ +../../../cve-validation/docs/insights/vulnerability-logic.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/docs/references/compliance-frameworks.md b/rh-sre/skills/playbook-executor/docs/references/compliance-frameworks.md new file mode 120000 index 00000000..333cdfdf --- /dev/null +++ b/rh-sre/skills/playbook-executor/docs/references/compliance-frameworks.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/references/compliance-frameworks.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/docs/references/cvss-scoring.md b/rh-sre/skills/playbook-executor/docs/references/cvss-scoring.md new file mode 120000 index 00000000..30fd4ef7 --- /dev/null +++ b/rh-sre/skills/playbook-executor/docs/references/cvss-scoring.md @@ -0,0 +1 @@ +../../../cve-validation/docs/references/cvss-scoring.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/docs/rhel/package-management.md b/rh-sre/skills/playbook-executor/docs/rhel/package-management.md new file mode 120000 index 00000000..65fda622 --- /dev/null +++ b/rh-sre/skills/playbook-executor/docs/rhel/package-management.md @@ -0,0 +1 @@ +../../../playbook-generator/docs/rhel/package-management.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/docs/rhel/selinux-context.md b/rh-sre/skills/playbook-executor/docs/rhel/selinux-context.md new file mode 120000 index 00000000..5159d6cf --- /dev/null +++ b/rh-sre/skills/playbook-executor/docs/rhel/selinux-context.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/rhel/selinux-context.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/docs/rhel/systemd-services.md b/rh-sre/skills/playbook-executor/docs/rhel/systemd-services.md new file mode 120000 index 00000000..a3bbcb2c --- /dev/null +++ b/rh-sre/skills/playbook-executor/docs/rhel/systemd-services.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/rhel/systemd-services.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/docs/rhel/version-compatibility.md b/rh-sre/skills/playbook-executor/docs/rhel/version-compatibility.md new file mode 120000 index 00000000..1f952f5c --- /dev/null +++ b/rh-sre/skills/playbook-executor/docs/rhel/version-compatibility.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/rhel/version-compatibility.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/SKILL.md b/rh-sre/skills/playbook-generator/SKILL.md index 4352531a..fb3893b1 100644 --- a/rh-sre/skills/playbook-generator/SKILL.md +++ b/rh-sre/skills/playbook-generator/SKILL.md @@ -149,8 +149,8 @@ Do NOT validate for "best practices" or add missing elements—return AS IS. - `playbook-executor` - Executes generated playbooks and tracks job status ### Reference Documentation -- [cve-remediation-templates.md](../../docs/ansible/cve-remediation-templates.md) - Ansible playbook templates for different CVE types -- [package-management.md](../../docs/rhel/package-management.md) - RHEL package management best practices (DNF vs YUM, reboot detection) +- [cve-remediation-templates.md](docs/ansible/cve-remediation-templates.md) - Ansible playbook templates for different CVE types +- [package-management.md](docs/rhel/package-management.md) - RHEL package management best practices (DNF vs YUM, reboot detection) ## Critical: Human-in-the-Loop Requirements diff --git a/rh-sre/skills/playbook-generator/docs/SOURCES.md b/rh-sre/skills/playbook-generator/docs/SOURCES.md new file mode 120000 index 00000000..50989401 --- /dev/null +++ b/rh-sre/skills/playbook-generator/docs/SOURCES.md @@ -0,0 +1 @@ +../../../docs/SOURCES.md \ No newline at end of file diff --git a/rh-sre/docs/ansible/README.md b/rh-sre/skills/playbook-generator/docs/ansible/README.md similarity index 100% rename from rh-sre/docs/ansible/README.md rename to rh-sre/skills/playbook-generator/docs/ansible/README.md diff --git a/rh-sre/skills/playbook-generator/docs/ansible/aap-integration.md b/rh-sre/skills/playbook-generator/docs/ansible/aap-integration.md new file mode 120000 index 00000000..e9f9036f --- /dev/null +++ b/rh-sre/skills/playbook-generator/docs/ansible/aap-integration.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/ansible/aap-integration.md \ No newline at end of file diff --git a/rh-sre/docs/ansible/cve-remediation-templates.md b/rh-sre/skills/playbook-generator/docs/ansible/cve-remediation-templates.md similarity index 100% rename from rh-sre/docs/ansible/cve-remediation-templates.md rename to rh-sre/skills/playbook-generator/docs/ansible/cve-remediation-templates.md diff --git a/rh-sre/skills/playbook-generator/docs/ansible/error-handling.md b/rh-sre/skills/playbook-generator/docs/ansible/error-handling.md new file mode 120000 index 00000000..c4b7b276 --- /dev/null +++ b/rh-sre/skills/playbook-generator/docs/ansible/error-handling.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/ansible/error-handling.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/docs/ansible/idempotency.md b/rh-sre/skills/playbook-generator/docs/ansible/idempotency.md new file mode 120000 index 00000000..c97ef9a0 --- /dev/null +++ b/rh-sre/skills/playbook-generator/docs/ansible/idempotency.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/ansible/idempotency.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/docs/insights/vulnerability-logic.md b/rh-sre/skills/playbook-generator/docs/insights/vulnerability-logic.md new file mode 120000 index 00000000..a4b16aa8 --- /dev/null +++ b/rh-sre/skills/playbook-generator/docs/insights/vulnerability-logic.md @@ -0,0 +1 @@ +../../../cve-validation/docs/insights/vulnerability-logic.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/docs/references/compliance-frameworks.md b/rh-sre/skills/playbook-generator/docs/references/compliance-frameworks.md new file mode 120000 index 00000000..333cdfdf --- /dev/null +++ b/rh-sre/skills/playbook-generator/docs/references/compliance-frameworks.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/references/compliance-frameworks.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/docs/references/cvss-scoring.md b/rh-sre/skills/playbook-generator/docs/references/cvss-scoring.md new file mode 120000 index 00000000..30fd4ef7 --- /dev/null +++ b/rh-sre/skills/playbook-generator/docs/references/cvss-scoring.md @@ -0,0 +1 @@ +../../../cve-validation/docs/references/cvss-scoring.md \ No newline at end of file diff --git a/rh-sre/docs/rhel/README.md b/rh-sre/skills/playbook-generator/docs/rhel/README.md similarity index 100% rename from rh-sre/docs/rhel/README.md rename to rh-sre/skills/playbook-generator/docs/rhel/README.md diff --git a/rh-sre/docs/rhel/package-management.md b/rh-sre/skills/playbook-generator/docs/rhel/package-management.md similarity index 100% rename from rh-sre/docs/rhel/package-management.md rename to rh-sre/skills/playbook-generator/docs/rhel/package-management.md diff --git a/rh-sre/skills/playbook-generator/docs/rhel/selinux-context.md b/rh-sre/skills/playbook-generator/docs/rhel/selinux-context.md new file mode 120000 index 00000000..5159d6cf --- /dev/null +++ b/rh-sre/skills/playbook-generator/docs/rhel/selinux-context.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/rhel/selinux-context.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/docs/rhel/systemd-services.md b/rh-sre/skills/playbook-generator/docs/rhel/systemd-services.md new file mode 120000 index 00000000..a3bbcb2c --- /dev/null +++ b/rh-sre/skills/playbook-generator/docs/rhel/systemd-services.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/rhel/systemd-services.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/docs/rhel/version-compatibility.md b/rh-sre/skills/playbook-generator/docs/rhel/version-compatibility.md new file mode 120000 index 00000000..1f952f5c --- /dev/null +++ b/rh-sre/skills/playbook-generator/docs/rhel/version-compatibility.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/rhel/version-compatibility.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/SKILL.md b/rh-sre/skills/remediation/SKILL.md index d467081f..6d1678a2 100644 --- a/rh-sre/skills/remediation/SKILL.md +++ b/rh-sre/skills/remediation/SKILL.md @@ -80,7 +80,7 @@ Execute skills in this order. **MANDATORY**: Use actual Skill tool invocations, **Sequencing (MANDATORY)**: Invoke validators **one at a time**. **Do NOT proceed to Step 1 until Step 0 is complete.** Wait for each validator to return explicit results (PASSED / FAILED / PARTIAL) before moving on. "Successfully loaded skill" alone does NOT mean validation completed—you must see the actual validation outcome. -**Invocation**: Use the Skill tool for ALL sub-skill invocations (validators, cve-validation, cve-impact, system-context, playbook-generator, playbook-executor, remediation-verifier). **Do NOT use "Task Output" with the skill name as task ID**—that causes "No task found" errors (e.g. "No task found with ID: cve-validation"). See [skill-invocation.md](../../docs/references/skill-invocation.md). +**Invocation**: Use the Skill tool for ALL sub-skill invocations (validators, cve-validation, cve-impact, system-context, playbook-generator, playbook-executor, remediation-verifier). **Do NOT use "Task Output" with the skill name as task ID**—that causes "No task found" errors (e.g. "No task found with ID: cve-validation"). See [skill-invocation.md](docs/references/skill-invocation.md). **Handle result**: If validation fails, stop and provide setup instructions. If passed, proceed to Step 1. **If any skill invocation fails** (e.g. "No task found with ID: ..."): Proceed with a warning—do not block. Later steps will surface real errors if MCP is unavailable. @@ -207,9 +207,9 @@ Execute skills in this order. **MANDATORY**: Use actual Skill tool invocations, ### Reference Documentation - [references/01-remediation-plan-template.md](references/01-remediation-plan-template.md) - Plan format for user validation -- [lightspeed-mcp-tool-failures.md](../../docs/references/lightspeed-mcp-tool-failures.md) - Backend errors (e.g. explain_cves), user-friendly message, workarounds -- [cve-remediation-templates.md](../../docs/ansible/cve-remediation-templates.md) -- [package-management.md](../../docs/rhel/package-management.md) +- [lightspeed-mcp-tool-failures.md](docs/references/lightspeed-mcp-tool-failures.md) - Backend errors (e.g. explain_cves), user-friendly message, workarounds +- [cve-remediation-templates.md](docs/ansible/cve-remediation-templates.md) +- [package-management.md](docs/rhel/package-management.md) ## Critical: Human-in-the-Loop Requirements @@ -239,7 +239,7 @@ This skill requires explicit user confirmation at: **vulnerability__explain_cves**: Requires a valid `system_uuid` from inventory. Do NOT call it unless you have the resolved UUID from Step 3 (system-context) or Step 1 (cve-impact). Never pass `system_uuid: "undefined"` or placeholder values—this causes validation errors. For remediation availability at Step 2, use `get_cve` via cve-validation only. -**Lightspeed tool failures**: If a tool fails with a cryptic backend error (e.g. `'dnf_modules'`), do NOT retry or expose the raw error. Use workarounds from [lightspeed-mcp-tool-failures.md](../../docs/references/lightspeed-mcp-tool-failures.md). +**Lightspeed tool failures**: If a tool fails with a cryptic backend error (e.g. `'dnf_modules'`), do NOT retry or expose the raw error. Use workarounds from [lightspeed-mcp-tool-failures.md](docs/references/lightspeed-mcp-tool-failures.md). ## Error Handling @@ -247,7 +247,7 @@ This skill requires explicit user confirmation at: - **No Remediation Available**: "CVE-XXXX-YYYY doesn't have an automated remediation playbook. Manual patching required." - **System Not Found**: "System XXXX is not in the Lightspeed inventory. Please ensure it's registered." - **Batch Partial Failure**: "Successfully processed X of Y CVEs. Failed: [list]. Reason: [explanations]" -- **Lightspeed tool failures** (e.g. explain_cves `'dnf_modules'`): Do NOT show raw error. Use user-friendly message and workaround from [lightspeed-mcp-tool-failures.md](../../docs/references/lightspeed-mcp-tool-failures.md). +- **Lightspeed tool failures** (e.g. explain_cves `'dnf_modules'`): Do NOT show raw error. Use user-friendly message and workaround from [lightspeed-mcp-tool-failures.md](docs/references/lightspeed-mcp-tool-failures.md). ## Output Format diff --git a/rh-sre/skills/remediation/docs/ansible/aap-integration.md b/rh-sre/skills/remediation/docs/ansible/aap-integration.md new file mode 120000 index 00000000..e9f9036f --- /dev/null +++ b/rh-sre/skills/remediation/docs/ansible/aap-integration.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/ansible/aap-integration.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/docs/ansible/cve-remediation-templates.md b/rh-sre/skills/remediation/docs/ansible/cve-remediation-templates.md new file mode 120000 index 00000000..269e56f2 --- /dev/null +++ b/rh-sre/skills/remediation/docs/ansible/cve-remediation-templates.md @@ -0,0 +1 @@ +../../../playbook-generator/docs/ansible/cve-remediation-templates.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/docs/ansible/error-handling.md b/rh-sre/skills/remediation/docs/ansible/error-handling.md new file mode 120000 index 00000000..c4b7b276 --- /dev/null +++ b/rh-sre/skills/remediation/docs/ansible/error-handling.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/ansible/error-handling.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/docs/ansible/idempotency.md b/rh-sre/skills/remediation/docs/ansible/idempotency.md new file mode 120000 index 00000000..c97ef9a0 --- /dev/null +++ b/rh-sre/skills/remediation/docs/ansible/idempotency.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/ansible/idempotency.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/docs/insights/vulnerability-logic.md b/rh-sre/skills/remediation/docs/insights/vulnerability-logic.md new file mode 120000 index 00000000..a4b16aa8 --- /dev/null +++ b/rh-sre/skills/remediation/docs/insights/vulnerability-logic.md @@ -0,0 +1 @@ +../../../cve-validation/docs/insights/vulnerability-logic.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/docs/references/compliance-frameworks.md b/rh-sre/skills/remediation/docs/references/compliance-frameworks.md new file mode 120000 index 00000000..333cdfdf --- /dev/null +++ b/rh-sre/skills/remediation/docs/references/compliance-frameworks.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/references/compliance-frameworks.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/docs/references/cvss-scoring.md b/rh-sre/skills/remediation/docs/references/cvss-scoring.md new file mode 120000 index 00000000..30fd4ef7 --- /dev/null +++ b/rh-sre/skills/remediation/docs/references/cvss-scoring.md @@ -0,0 +1 @@ +../../../cve-validation/docs/references/cvss-scoring.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/docs/references/lightspeed-mcp-tool-failures.md b/rh-sre/skills/remediation/docs/references/lightspeed-mcp-tool-failures.md new file mode 120000 index 00000000..394e7b5c --- /dev/null +++ b/rh-sre/skills/remediation/docs/references/lightspeed-mcp-tool-failures.md @@ -0,0 +1 @@ +../../../cve-impact/docs/references/lightspeed-mcp-tool-failures.md \ No newline at end of file diff --git a/rh-sre/docs/references/skill-invocation.md b/rh-sre/skills/remediation/docs/references/skill-invocation.md similarity index 100% rename from rh-sre/docs/references/skill-invocation.md rename to rh-sre/skills/remediation/docs/references/skill-invocation.md diff --git a/rh-sre/skills/remediation/docs/rhel/package-management.md b/rh-sre/skills/remediation/docs/rhel/package-management.md new file mode 120000 index 00000000..65fda622 --- /dev/null +++ b/rh-sre/skills/remediation/docs/rhel/package-management.md @@ -0,0 +1 @@ +../../../playbook-generator/docs/rhel/package-management.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/docs/rhel/selinux-context.md b/rh-sre/skills/remediation/docs/rhel/selinux-context.md new file mode 120000 index 00000000..5159d6cf --- /dev/null +++ b/rh-sre/skills/remediation/docs/rhel/selinux-context.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/rhel/selinux-context.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/docs/rhel/systemd-services.md b/rh-sre/skills/remediation/docs/rhel/systemd-services.md new file mode 120000 index 00000000..a3bbcb2c --- /dev/null +++ b/rh-sre/skills/remediation/docs/rhel/systemd-services.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/rhel/systemd-services.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/docs/rhel/version-compatibility.md b/rh-sre/skills/remediation/docs/rhel/version-compatibility.md new file mode 120000 index 00000000..1f952f5c --- /dev/null +++ b/rh-sre/skills/remediation/docs/rhel/version-compatibility.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/docs/rhel/version-compatibility.md \ No newline at end of file diff --git a/rh-virt/README.md b/rh-virt/README.md index b12b063e..cd6eb934 100644 --- a/rh-virt/README.md +++ b/rh-virt/README.md @@ -404,7 +404,7 @@ The **vm-create** skill includes automatic error diagnosis and workaround propos - **ErrorUnschedulable** - Node taints/tolerations mismatch, resource constraints, node selector issues - **ErrorDataVolumeNotReady** - Storage provisioning delays, storage class issues, quota exceeded -**For comprehensive troubleshooting guidance**, see [docs/troubleshooting/INDEX.md](docs/troubleshooting/INDEX.md). +**For comprehensive troubleshooting guidance**, see [docs/troubleshooting/INDEX.md](skills/vm-rebalance/docs/troubleshooting/INDEX.md). ### MCP Server Won't Start diff --git a/rh-virt/skills/vm-clone/SKILL.md b/rh-virt/skills/vm-clone/SKILL.md index 1584f8f0..e1774b3c 100644 --- a/rh-virt/skills/vm-clone/SKILL.md +++ b/rh-virt/skills/vm-clone/SKILL.md @@ -244,8 +244,8 @@ Use `resources_get` on DataVolume, check `status.phase` (Pending/Succeeded/Faile **Document Consultation** (OPTIONAL - when cloning fails): - **When to consult**: Storage cloning fails, VM creation fails, PVC clone not supported, storage class issues - **When NOT to consult**: VM already exists, RBAC errors, namespace not found (clear causes) -- **Action**: Read [storage-errors.md](../../docs/troubleshooting/storage-errors.md) for VM cloning failures, storage provisioning, DataVolume errors -- **Output to user**: "I consulted [storage-errors.md](../../docs/troubleshooting/storage-errors.md) to understand potential causes." +- **Action**: Read [storage-errors.md](docs/troubleshooting/storage-errors.md) for VM cloning failures, storage provisioning, DataVolume errors +- **Output to user**: "I consulted [storage-errors.md](docs/troubleshooting/storage-errors.md) to understand potential causes." ```markdown ## ❌ VM Cloning Failed @@ -260,7 +260,7 @@ Use `resources_get` on DataVolume, check `status.phase` (Pending/Succeeded/Faile - PVC clone not supported - Storage class doesn't support cloning - Source VM still running - Some storage backends require source VM stopped -**Troubleshooting** (see [storage-errors.md](../../docs/troubleshooting/storage-errors.md)): +**Troubleshooting** (see [storage-errors.md](docs/troubleshooting/storage-errors.md)): 1. Check storage quota: `resources_list` for ResourceQuota in target namespace 2. Check permissions: `resources_list` to verify RBAC (note: `oc auth can-i` has no MCP equivalent) 3. Check storage class: `resources_get` for StorageClass config, `resources_list` for available classes @@ -327,8 +327,8 @@ Allow modifications during clone: instance type/size, storage size, network conf - `vm-delete` - Clean up failed clones or unwanted copies ### Reference Documentation -- [storage-errors.md](../../docs/troubleshooting/storage-errors.md) - VM cloning failure scenarios, storage provisioning issues, and DataVolume cloning errors (optionally consulted when cloning operations fail) -- [Troubleshooting INDEX](../../docs/troubleshooting/INDEX.md) - Navigation hub for discovering additional error categories when encountering unexpected issues outside the categories above +- [storage-errors.md](docs/troubleshooting/storage-errors.md) - VM cloning failure scenarios, storage provisioning issues, and DataVolume cloning errors (optionally consulted when cloning operations fail) +- [Troubleshooting INDEX](docs/troubleshooting/INDEX.md) - Navigation hub for discovering additional error categories when encountering unexpected issues outside the categories above - [OpenShift Virtualization Cloning](https://docs.redhat.com/en/documentation/openshift_container_platform/4.21/html-single/virtualization/index#virt/virtual_machines/cloning_vms/virt-cloning-vm.html) - [DataVolume Cloning](https://github.com/kubevirt/containerized-data-importer/blob/main/doc/datavolumes.md#cloning) - [KubeVirt VirtualMachine API](https://kubevirt.io/api-reference/) diff --git a/rh-virt/skills/vm-clone/docs/README.md b/rh-virt/skills/vm-clone/docs/README.md new file mode 120000 index 00000000..fa619329 --- /dev/null +++ b/rh-virt/skills/vm-clone/docs/README.md @@ -0,0 +1 @@ +../../vm-delete/docs/README.md \ No newline at end of file diff --git a/rh-virt/skills/vm-clone/docs/SOURCES.md b/rh-virt/skills/vm-clone/docs/SOURCES.md new file mode 120000 index 00000000..8ecd7839 --- /dev/null +++ b/rh-virt/skills/vm-clone/docs/SOURCES.md @@ -0,0 +1 @@ +../../vm-delete/docs/SOURCES.md \ No newline at end of file diff --git a/rh-virt/skills/vm-clone/docs/troubleshooting/INDEX.md b/rh-virt/skills/vm-clone/docs/troubleshooting/INDEX.md new file mode 120000 index 00000000..a3fcc197 --- /dev/null +++ b/rh-virt/skills/vm-clone/docs/troubleshooting/INDEX.md @@ -0,0 +1 @@ +../../../vm-rebalance/docs/troubleshooting/INDEX.md \ No newline at end of file diff --git a/rh-virt/skills/vm-clone/docs/troubleshooting/lifecycle-errors.md b/rh-virt/skills/vm-clone/docs/troubleshooting/lifecycle-errors.md new file mode 120000 index 00000000..693aee70 --- /dev/null +++ b/rh-virt/skills/vm-clone/docs/troubleshooting/lifecycle-errors.md @@ -0,0 +1 @@ +../../../vm-rebalance/docs/troubleshooting/lifecycle-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-clone/docs/troubleshooting/network-errors.md b/rh-virt/skills/vm-clone/docs/troubleshooting/network-errors.md new file mode 120000 index 00000000..334c0fc8 --- /dev/null +++ b/rh-virt/skills/vm-clone/docs/troubleshooting/network-errors.md @@ -0,0 +1 @@ +../../../vm-create/docs/troubleshooting/network-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-clone/docs/troubleshooting/runtime-errors.md b/rh-virt/skills/vm-clone/docs/troubleshooting/runtime-errors.md new file mode 120000 index 00000000..728999a3 --- /dev/null +++ b/rh-virt/skills/vm-clone/docs/troubleshooting/runtime-errors.md @@ -0,0 +1 @@ +../../../vm-create/docs/troubleshooting/runtime-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-clone/docs/troubleshooting/scheduling-errors.md b/rh-virt/skills/vm-clone/docs/troubleshooting/scheduling-errors.md new file mode 120000 index 00000000..c95dda33 --- /dev/null +++ b/rh-virt/skills/vm-clone/docs/troubleshooting/scheduling-errors.md @@ -0,0 +1 @@ +../../../vm-rebalance/docs/troubleshooting/scheduling-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-clone/docs/troubleshooting/storage-errors.md b/rh-virt/skills/vm-clone/docs/troubleshooting/storage-errors.md new file mode 120000 index 00000000..c3fb9854 --- /dev/null +++ b/rh-virt/skills/vm-clone/docs/troubleshooting/storage-errors.md @@ -0,0 +1 @@ +../../../vm-rebalance/docs/troubleshooting/storage-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-create/SKILL.md b/rh-virt/skills/vm-create/SKILL.md index 01445014..dd02dacb 100644 --- a/rh-virt/skills/vm-create/SKILL.md +++ b/rh-virt/skills/vm-create/SKILL.md @@ -172,7 +172,9 @@ Confirm: yes/no/modify #### 5a. Diagnostic Workflow (ErrorUnschedulable) -**Reference**: See [scheduling-errors.md](../../docs/troubleshooting/scheduling-errors.md) for diagnosis strategies. +**CRITICAL: Document Consultation FIRST:** +1. Read [scheduling-errors.md](docs/troubleshooting/scheduling-errors.md) using Read tool +2. Output: "I detected ErrorUnschedulable. I consulted [scheduling-errors.md] to understand diagnosis strategies." **Gather diagnostics:** - List events: `events_list` (namespace=``) → Filter for VM/VMI @@ -296,11 +298,11 @@ Troubleshooting: See Common Issues - `vm-lifecycle-manager` - Start VMs | `vm-inventory` - List VMs | `vm-delete` - Delete VMs | `vm-clone` - Clone VMs | `vm-snapshot-create` - Snapshot VMs ### Reference Documentation -- [scheduling-errors.md](../../docs/troubleshooting/scheduling-errors.md) - ErrorUnschedulable (consulted Step 5a) -- [storage-errors.md](../../docs/troubleshooting/storage-errors.md) - ErrorDataVolumeNotReady -- [network-errors.md](../../docs/troubleshooting/network-errors.md) - Network failures -- [runtime-errors.md](../../docs/troubleshooting/runtime-errors.md) - CrashLoopBackOff -- [Troubleshooting INDEX](../../docs/troubleshooting/INDEX.md) - Full error index +- [scheduling-errors.md](docs/troubleshooting/scheduling-errors.md) - ErrorUnschedulable (consulted Step 5a) +- [storage-errors.md](docs/troubleshooting/storage-errors.md) - ErrorDataVolumeNotReady +- [network-errors.md](docs/troubleshooting/network-errors.md) - Network failures +- [runtime-errors.md](docs/troubleshooting/runtime-errors.md) - CrashLoopBackOff +- [Troubleshooting INDEX](docs/troubleshooting/INDEX.md) - Full error index - [OpenShift Virt Docs](https://docs.redhat.com/en/documentation/openshift_container_platform/4.21/html-single/virtualization/index) - [KubeVirt API](https://kubevirt.io/api-reference/) - [OpenShift MCP](https://github.com/openshift/openshift-mcp-server) diff --git a/rh-virt/skills/vm-create/docs/README.md b/rh-virt/skills/vm-create/docs/README.md new file mode 120000 index 00000000..fa619329 --- /dev/null +++ b/rh-virt/skills/vm-create/docs/README.md @@ -0,0 +1 @@ +../../vm-delete/docs/README.md \ No newline at end of file diff --git a/rh-virt/skills/vm-create/docs/SOURCES.md b/rh-virt/skills/vm-create/docs/SOURCES.md new file mode 120000 index 00000000..8ecd7839 --- /dev/null +++ b/rh-virt/skills/vm-create/docs/SOURCES.md @@ -0,0 +1 @@ +../../vm-delete/docs/SOURCES.md \ No newline at end of file diff --git a/rh-virt/skills/vm-create/docs/troubleshooting/INDEX.md b/rh-virt/skills/vm-create/docs/troubleshooting/INDEX.md new file mode 120000 index 00000000..a3fcc197 --- /dev/null +++ b/rh-virt/skills/vm-create/docs/troubleshooting/INDEX.md @@ -0,0 +1 @@ +../../../vm-rebalance/docs/troubleshooting/INDEX.md \ No newline at end of file diff --git a/rh-virt/skills/vm-create/docs/troubleshooting/lifecycle-errors.md b/rh-virt/skills/vm-create/docs/troubleshooting/lifecycle-errors.md new file mode 120000 index 00000000..693aee70 --- /dev/null +++ b/rh-virt/skills/vm-create/docs/troubleshooting/lifecycle-errors.md @@ -0,0 +1 @@ +../../../vm-rebalance/docs/troubleshooting/lifecycle-errors.md \ No newline at end of file diff --git a/rh-virt/docs/troubleshooting/network-errors.md b/rh-virt/skills/vm-create/docs/troubleshooting/network-errors.md similarity index 100% rename from rh-virt/docs/troubleshooting/network-errors.md rename to rh-virt/skills/vm-create/docs/troubleshooting/network-errors.md diff --git a/rh-virt/docs/troubleshooting/runtime-errors.md b/rh-virt/skills/vm-create/docs/troubleshooting/runtime-errors.md similarity index 100% rename from rh-virt/docs/troubleshooting/runtime-errors.md rename to rh-virt/skills/vm-create/docs/troubleshooting/runtime-errors.md diff --git a/rh-virt/skills/vm-create/docs/troubleshooting/scheduling-errors.md b/rh-virt/skills/vm-create/docs/troubleshooting/scheduling-errors.md new file mode 120000 index 00000000..c95dda33 --- /dev/null +++ b/rh-virt/skills/vm-create/docs/troubleshooting/scheduling-errors.md @@ -0,0 +1 @@ +../../../vm-rebalance/docs/troubleshooting/scheduling-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-create/docs/troubleshooting/storage-errors.md b/rh-virt/skills/vm-create/docs/troubleshooting/storage-errors.md new file mode 120000 index 00000000..c3fb9854 --- /dev/null +++ b/rh-virt/skills/vm-create/docs/troubleshooting/storage-errors.md @@ -0,0 +1 @@ +../../../vm-rebalance/docs/troubleshooting/storage-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-delete/SKILL.md b/rh-virt/skills/vm-delete/SKILL.md index e30dc658..be1d1959 100644 --- a/rh-virt/skills/vm-delete/SKILL.md +++ b/rh-virt/skills/vm-delete/SKILL.md @@ -214,7 +214,7 @@ Report: `🗑️ Deleting storage... ✓ DV deleted (storage freed) ✓ PVC dele **Partial failure (storage failed):** -**OPTIONAL**: Read [storage-errors.md](../../docs/troubleshooting/storage-errors.md) for PVC cleanup. Output: "Consulted storage-errors.md for failure." +**OPTIONAL**: Read [storage-errors.md](docs/troubleshooting/storage-errors.md) for PVC cleanup. Output: "Consulted storage-errors.md for failure." ```markdown ## ⚠️ Partial Deletion @@ -224,7 +224,7 @@ Report: `🗑️ Deleting storage... ✓ DV deleted (storage freed) ✓ PVC dele **Complete failure:** -**OPTIONAL**: Read [lifecycle-errors.md](../../docs/troubleshooting/lifecycle-errors.md) for deletion failures. Output: "Consulted lifecycle-errors.md for failure causes." +**OPTIONAL**: Read [lifecycle-errors.md](docs/troubleshooting/lifecycle-errors.md) for deletion failures. Output: "Consulted lifecycle-errors.md for failure causes." ```markdown ## ❌ VM Deletion Failed @@ -244,11 +244,11 @@ Report: `🗑️ Deleting storage... ✓ DV deleted (storage freed) ✓ PVC dele ### Issue 3: VM Has Finalizers **Error**: "VM deletion blocked by finalizers" -**Solution**: Consult [lifecycle-errors.md](../../docs/troubleshooting/lifecycle-errors.md) "VM Stuck in Terminating" for MCP-first approach using `resources_get` to check finalizers, `resources_create_or_update` to remove if needed. +**Solution**: Consult [lifecycle-errors.md](docs/troubleshooting/lifecycle-errors.md) "VM Stuck in Terminating" for MCP-first approach using `resources_get` to check finalizers, `resources_create_or_update` to remove if needed. ### Issue 4: Storage Deletion Failure **Error**: "PVC deletion failed: resource in use" -**Solution**: Verify VM deleted first. Consult [storage-errors.md](../../docs/troubleshooting/storage-errors.md) for MCP-first diagnostics using `pods_list_in_namespace` to check mounts, `resources_get` for PVC status. +**Solution**: Verify VM deleted first. Consult [storage-errors.md](docs/troubleshooting/storage-errors.md) for MCP-first diagnostics using `pods_list_in_namespace` to check mounts, `resources_get` for PVC status. ### Issue 5: Confirmation Mismatch **Error**: "Names do not match" @@ -275,9 +275,9 @@ Report: `🗑️ Deleting storage... ✓ DV deleted (storage freed) ✓ PVC dele - `vm-lifecycle-manager` - Stop VMs | `vm-inventory` - List VMs | `vm-create` - Create VMs | `vm-clone` - Clone VMs ### Reference Documentation -- [lifecycle-errors.md](../../docs/troubleshooting/lifecycle-errors.md) - Deletion failures, finalizers, stuck Terminating (consulted on deletion failure) -- [storage-errors.md](../../docs/troubleshooting/storage-errors.md) - Storage deletion, PVC cleanup (consulted on storage failure) -- [Troubleshooting INDEX](../../docs/troubleshooting/INDEX.md) - Full error index +- [lifecycle-errors.md](docs/troubleshooting/lifecycle-errors.md) - Deletion failures, finalizers, stuck Terminating (consulted on deletion failure) +- [storage-errors.md](docs/troubleshooting/storage-errors.md) - Storage deletion, PVC cleanup (consulted on storage failure) +- [Troubleshooting INDEX](docs/troubleshooting/INDEX.md) - Full error index - [OpenShift Virt Docs](https://docs.redhat.com/en/documentation/openshift_container_platform/4.21/html-single/virtualization/index) - [KubeVirt API](https://kubevirt.io/api-reference/) - [K8s Finalizers](https://kubernetes.io/docs/concepts/overview/working-with-objects/finalizers/) diff --git a/rh-virt/skills/vm-delete/docs/README.md b/rh-virt/skills/vm-delete/docs/README.md new file mode 100644 index 00000000..720ddea0 --- /dev/null +++ b/rh-virt/skills/vm-delete/docs/README.md @@ -0,0 +1,8 @@ +--- +title: TODO +status: draft +--- + +# TODO + +Placeholder — content pending. diff --git a/rh-virt/skills/vm-delete/docs/SOURCES.md b/rh-virt/skills/vm-delete/docs/SOURCES.md new file mode 100644 index 00000000..720ddea0 --- /dev/null +++ b/rh-virt/skills/vm-delete/docs/SOURCES.md @@ -0,0 +1,8 @@ +--- +title: TODO +status: draft +--- + +# TODO + +Placeholder — content pending. diff --git a/rh-virt/skills/vm-delete/docs/troubleshooting/INDEX.md b/rh-virt/skills/vm-delete/docs/troubleshooting/INDEX.md new file mode 120000 index 00000000..a3fcc197 --- /dev/null +++ b/rh-virt/skills/vm-delete/docs/troubleshooting/INDEX.md @@ -0,0 +1 @@ +../../../vm-rebalance/docs/troubleshooting/INDEX.md \ No newline at end of file diff --git a/rh-virt/skills/vm-delete/docs/troubleshooting/lifecycle-errors.md b/rh-virt/skills/vm-delete/docs/troubleshooting/lifecycle-errors.md new file mode 120000 index 00000000..693aee70 --- /dev/null +++ b/rh-virt/skills/vm-delete/docs/troubleshooting/lifecycle-errors.md @@ -0,0 +1 @@ +../../../vm-rebalance/docs/troubleshooting/lifecycle-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-delete/docs/troubleshooting/network-errors.md b/rh-virt/skills/vm-delete/docs/troubleshooting/network-errors.md new file mode 120000 index 00000000..334c0fc8 --- /dev/null +++ b/rh-virt/skills/vm-delete/docs/troubleshooting/network-errors.md @@ -0,0 +1 @@ +../../../vm-create/docs/troubleshooting/network-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-delete/docs/troubleshooting/runtime-errors.md b/rh-virt/skills/vm-delete/docs/troubleshooting/runtime-errors.md new file mode 120000 index 00000000..728999a3 --- /dev/null +++ b/rh-virt/skills/vm-delete/docs/troubleshooting/runtime-errors.md @@ -0,0 +1 @@ +../../../vm-create/docs/troubleshooting/runtime-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-delete/docs/troubleshooting/scheduling-errors.md b/rh-virt/skills/vm-delete/docs/troubleshooting/scheduling-errors.md new file mode 120000 index 00000000..c95dda33 --- /dev/null +++ b/rh-virt/skills/vm-delete/docs/troubleshooting/scheduling-errors.md @@ -0,0 +1 @@ +../../../vm-rebalance/docs/troubleshooting/scheduling-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-delete/docs/troubleshooting/storage-errors.md b/rh-virt/skills/vm-delete/docs/troubleshooting/storage-errors.md new file mode 120000 index 00000000..c3fb9854 --- /dev/null +++ b/rh-virt/skills/vm-delete/docs/troubleshooting/storage-errors.md @@ -0,0 +1 @@ +../../../vm-rebalance/docs/troubleshooting/storage-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-lifecycle-manager/SKILL.md b/rh-virt/skills/vm-lifecycle-manager/SKILL.md index 0f86b4f6..e24343fd 100644 --- a/rh-virt/skills/vm-lifecycle-manager/SKILL.md +++ b/rh-virt/skills/vm-lifecycle-manager/SKILL.md @@ -134,7 +134,7 @@ Confirm: yes/no **On Failure:** -**OPTIONAL**: Read [lifecycle-errors.md](../../docs/troubleshooting/lifecycle-errors.md) for start/stop failures or [scheduling-errors.md](../../docs/troubleshooting/scheduling-errors.md) for ErrorUnschedulable. Output: "Consulted lifecycle-errors.md for failure." +**OPTIONAL**: Read [lifecycle-errors.md](docs/troubleshooting/lifecycle-errors.md) for start/stop failures or [scheduling-errors.md](docs/troubleshooting/scheduling-errors.md) for ErrorUnschedulable. Output: "Consulted lifecycle-errors.md for failure." **When to consult**: Start/stop failures, stuck transitions, unexpected errors. **NOT**: Already in state, not found, RBAC errors. @@ -201,9 +201,9 @@ Confirm: yes/no - `vm-troubleshooter` (planned) - Diagnose startup/shutdown issues ### Reference Documentation -- [lifecycle-errors.md](../../docs/troubleshooting/lifecycle-errors.md) - Start/stop failures, stuck transitions (consulted on failures) -- [scheduling-errors.md](../../docs/troubleshooting/scheduling-errors.md) - ErrorUnschedulable, resource constraints (consulted when VM won't start) -- [Troubleshooting INDEX](../../docs/troubleshooting/INDEX.md) - Navigation hub for error categories +- [lifecycle-errors.md](docs/troubleshooting/lifecycle-errors.md) - Start/stop failures, stuck transitions (consulted on failures) +- [scheduling-errors.md](docs/troubleshooting/scheduling-errors.md) - ErrorUnschedulable, resource constraints (consulted when VM won't start) +- [Troubleshooting INDEX](docs/troubleshooting/INDEX.md) - Navigation hub for error categories - [OpenShift Virt Docs](https://docs.redhat.com/en/documentation/openshift_container_platform/4.21/html-single/virtualization/index#virt/about_virt/about-virt.html) - [KubeVirt Lifecycle](https://kubevirt.io/user-guide/virtual_machines/lifecycle/) - [RunStrategy Docs](https://kubevirt.io/user-guide/virtual_machines/run_strategies/) diff --git a/rh-virt/skills/vm-lifecycle-manager/docs/README.md b/rh-virt/skills/vm-lifecycle-manager/docs/README.md new file mode 120000 index 00000000..fa619329 --- /dev/null +++ b/rh-virt/skills/vm-lifecycle-manager/docs/README.md @@ -0,0 +1 @@ +../../vm-delete/docs/README.md \ No newline at end of file diff --git a/rh-virt/skills/vm-lifecycle-manager/docs/SOURCES.md b/rh-virt/skills/vm-lifecycle-manager/docs/SOURCES.md new file mode 120000 index 00000000..8ecd7839 --- /dev/null +++ b/rh-virt/skills/vm-lifecycle-manager/docs/SOURCES.md @@ -0,0 +1 @@ +../../vm-delete/docs/SOURCES.md \ No newline at end of file diff --git a/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/INDEX.md b/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/INDEX.md new file mode 120000 index 00000000..a3fcc197 --- /dev/null +++ b/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/INDEX.md @@ -0,0 +1 @@ +../../../vm-rebalance/docs/troubleshooting/INDEX.md \ No newline at end of file diff --git a/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/lifecycle-errors.md b/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/lifecycle-errors.md new file mode 120000 index 00000000..693aee70 --- /dev/null +++ b/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/lifecycle-errors.md @@ -0,0 +1 @@ +../../../vm-rebalance/docs/troubleshooting/lifecycle-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/network-errors.md b/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/network-errors.md new file mode 120000 index 00000000..334c0fc8 --- /dev/null +++ b/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/network-errors.md @@ -0,0 +1 @@ +../../../vm-create/docs/troubleshooting/network-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/runtime-errors.md b/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/runtime-errors.md new file mode 120000 index 00000000..728999a3 --- /dev/null +++ b/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/runtime-errors.md @@ -0,0 +1 @@ +../../../vm-create/docs/troubleshooting/runtime-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/scheduling-errors.md b/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/scheduling-errors.md new file mode 120000 index 00000000..c95dda33 --- /dev/null +++ b/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/scheduling-errors.md @@ -0,0 +1 @@ +../../../vm-rebalance/docs/troubleshooting/scheduling-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/storage-errors.md b/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/storage-errors.md new file mode 120000 index 00000000..c3fb9854 --- /dev/null +++ b/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/storage-errors.md @@ -0,0 +1 @@ +../../../vm-rebalance/docs/troubleshooting/storage-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-rebalance/SKILL.md b/rh-virt/skills/vm-rebalance/SKILL.md index f972e5e7..948285bb 100644 --- a/rh-virt/skills/vm-rebalance/SKILL.md +++ b/rh-virt/skills/vm-rebalance/SKILL.md @@ -144,7 +144,7 @@ Orchestrate VM migrations across OpenShift cluster nodes for load balancing, mai **Errors**: Not found → "Node doesn't exist" | Not Ready → "Choose different target" | Cordoned → "Uncordon or choose different target" -**Reference**: [scheduling-errors.md](../../docs/troubleshooting/scheduling-errors.md) +**Reference**: [scheduling-errors.md](docs/troubleshooting/scheduling-errors.md) ## Node Selection for Automatic Rebalancing @@ -273,12 +273,12 @@ If any node's CPU or Memory percentage **exceeds 100%** after rebalancing: ### Error 1: Live Migration Fails - Storage Not RWX **Symptom**: "Cannot live migrate: PVC access mode is ReadWriteOnce" **Solution**: Use cold migration OR convert PVC to RWX -**Reference**: [storage-errors.md](../../docs/troubleshooting/storage-errors.md) +**Reference**: [storage-errors.md](docs/troubleshooting/storage-errors.md) ### Error 2: VM Stuck ErrorUnschedulable After Cold Migration **Symptom**: "VM cannot be scheduled: ErrorUnschedulable" **Solution**: Check node capacity (`nodes_top`), verify no blocking taints (`resources_get` Node), add tolerations, choose different target, remove nodeSelector -**Reference**: [scheduling-errors.md](../../docs/troubleshooting/scheduling-errors.md) +**Reference**: [scheduling-errors.md](docs/troubleshooting/scheduling-errors.md) ### Error 3: Live Migration Times Out **Symptom**: "Migration exceeded timeout: 150s per GiB" @@ -332,10 +332,10 @@ If any node's CPU or Memory percentage **exceeds 100%** after rebalancing: - [references/production-considerations.md](./references/production-considerations.md) - HA, capacity, security **Troubleshooting**: -- [Troubleshooting INDEX](../../docs/troubleshooting/INDEX.md) - Master index -- [scheduling-errors.md](../../docs/troubleshooting/scheduling-errors.md) - ErrorUnschedulable, taints -- [storage-errors.md](../../docs/troubleshooting/storage-errors.md) - PVC access modes -- [lifecycle-errors.md](../../docs/troubleshooting/lifecycle-errors.md) - VM start/stop +- [Troubleshooting INDEX](docs/troubleshooting/INDEX.md) - Master index +- [scheduling-errors.md](docs/troubleshooting/scheduling-errors.md) - ErrorUnschedulable, taints +- [storage-errors.md](docs/troubleshooting/storage-errors.md) - PVC access modes +- [lifecycle-errors.md](docs/troubleshooting/lifecycle-errors.md) - VM start/stop **Official Documentation**: - [OpenShift Virt - Live Migration](https://docs.redhat.com/en/documentation/openshift_container_platform/4.21/html-single/virtualization/index#virt-live-migration) diff --git a/rh-virt/skills/vm-rebalance/docs/README.md b/rh-virt/skills/vm-rebalance/docs/README.md new file mode 120000 index 00000000..fa619329 --- /dev/null +++ b/rh-virt/skills/vm-rebalance/docs/README.md @@ -0,0 +1 @@ +../../vm-delete/docs/README.md \ No newline at end of file diff --git a/rh-virt/skills/vm-rebalance/docs/SOURCES.md b/rh-virt/skills/vm-rebalance/docs/SOURCES.md new file mode 120000 index 00000000..8ecd7839 --- /dev/null +++ b/rh-virt/skills/vm-rebalance/docs/SOURCES.md @@ -0,0 +1 @@ +../../vm-delete/docs/SOURCES.md \ No newline at end of file diff --git a/rh-virt/docs/troubleshooting/INDEX.md b/rh-virt/skills/vm-rebalance/docs/troubleshooting/INDEX.md similarity index 99% rename from rh-virt/docs/troubleshooting/INDEX.md rename to rh-virt/skills/vm-rebalance/docs/troubleshooting/INDEX.md index a2e76963..fb7598b3 100644 --- a/rh-virt/docs/troubleshooting/INDEX.md +++ b/rh-virt/skills/vm-rebalance/docs/troubleshooting/INDEX.md @@ -327,6 +327,6 @@ To document a new error: ## 📚 Additional Resources -- [rh-virt README](../../README.md) - MCP server setup and skill documentation +- [rh-virt README](../../../../README.md) - MCP server setup and skill documentation - [SOURCES.md](../SOURCES.md) - Official Red Hat documentation sources - [Semantic Index](.ai-index/semantic-index.json) - AI-optimized doc discovery diff --git a/rh-virt/docs/troubleshooting/lifecycle-errors.md b/rh-virt/skills/vm-rebalance/docs/troubleshooting/lifecycle-errors.md similarity index 100% rename from rh-virt/docs/troubleshooting/lifecycle-errors.md rename to rh-virt/skills/vm-rebalance/docs/troubleshooting/lifecycle-errors.md diff --git a/rh-virt/skills/vm-rebalance/docs/troubleshooting/network-errors.md b/rh-virt/skills/vm-rebalance/docs/troubleshooting/network-errors.md new file mode 120000 index 00000000..334c0fc8 --- /dev/null +++ b/rh-virt/skills/vm-rebalance/docs/troubleshooting/network-errors.md @@ -0,0 +1 @@ +../../../vm-create/docs/troubleshooting/network-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-rebalance/docs/troubleshooting/runtime-errors.md b/rh-virt/skills/vm-rebalance/docs/troubleshooting/runtime-errors.md new file mode 120000 index 00000000..728999a3 --- /dev/null +++ b/rh-virt/skills/vm-rebalance/docs/troubleshooting/runtime-errors.md @@ -0,0 +1 @@ +../../../vm-create/docs/troubleshooting/runtime-errors.md \ No newline at end of file diff --git a/rh-virt/docs/troubleshooting/scheduling-errors.md b/rh-virt/skills/vm-rebalance/docs/troubleshooting/scheduling-errors.md similarity index 100% rename from rh-virt/docs/troubleshooting/scheduling-errors.md rename to rh-virt/skills/vm-rebalance/docs/troubleshooting/scheduling-errors.md diff --git a/rh-virt/docs/troubleshooting/storage-errors.md b/rh-virt/skills/vm-rebalance/docs/troubleshooting/storage-errors.md similarity index 100% rename from rh-virt/docs/troubleshooting/storage-errors.md rename to rh-virt/skills/vm-rebalance/docs/troubleshooting/storage-errors.md diff --git a/scripts/ci-validate-changed-skills.sh b/scripts/ci-validate-changed-skills.sh index d41eaa17..06f17c77 100755 --- a/scripts/ci-validate-changed-skills.sh +++ b/scripts/ci-validate-changed-skills.sh @@ -37,5 +37,8 @@ fi echo "Validating changed skills:" echo "$CHANGED" | sed 's/^/ - /' -# Run validator on changed skills only -uv run python scripts/validate_skill_design.py $(echo "$CHANGED" | tr '\n' ' ') +# Run validators on changed skills only +SKILL_ARGS=$(echo "$CHANGED" | tr '\n' ' ') +uv run python scripts/validate_skill_design.py $SKILL_ARGS +uv run python scripts/validate_skill_doc_links.py $SKILL_ARGS +uv run python scripts/validate_docs_tree_links.py $SKILL_ARGS diff --git a/scripts/validate_docs_tree_links.py b/scripts/validate_docs_tree_links.py new file mode 100644 index 00000000..9e21e2f1 --- /dev/null +++ b/scripts/validate_docs_tree_links.py @@ -0,0 +1,186 @@ +#!/usr/bin/env python3 +""" +Validate markdown link integrity for runtime-adjacent docs trees. + +Scope: +- skills/*/docs/**/*.md +- /README.md +- /.catalog/*.md + +Checks: +- local markdown link targets exist +- symlink targets resolve +- no symlink loops +- resolved targets do not escape pack root +""" + +from __future__ import annotations + +import argparse +import json +import os +import re +import sys +from pathlib import Path +from typing import Iterable + +DEFAULT_PACKS = [ + "rh-sre", + "rh-developer", + "ocp-admin", + "rh-virt", + "rh-ai-engineer", + "rh-automation", +] + +MD_LINK_RE = re.compile(r"\[[^\]]+\]\(([^)]+)\)") + + +def is_external(target: str) -> bool: + lower = target.lower() + return ( + lower.startswith("http://") + or lower.startswith("https://") + or lower.startswith("mailto:") + or lower.startswith("#") + ) + + +def resolve_packs(paths: Iterable[str]) -> set[Path]: + packs: set[Path] = set() + for p in paths: + path = Path(p) + if path.is_file(): + if path.name == "SKILL.md" and path.parent.parent.name == "skills": + packs.add(path.parent.parent.parent.resolve()) + elif path.name.endswith(".md"): + # If file belongs to a pack directory, infer it. + parts = path.resolve().parts + if "skills" in parts: + idx = parts.index("skills") + packs.add(Path(*parts[:idx]).resolve()) + continue + if path.is_dir(): + if (path / "skills").exists(): + packs.add(path.resolve()) + continue + # Maybe path is pack name that exists in cwd + if (Path.cwd() / path / "skills").exists(): + packs.add((Path.cwd() / path).resolve()) + return packs + + +def scan_targets(pack_root: Path) -> list[Path]: + targets: list[Path] = [] + targets.extend(sorted((pack_root / "skills").glob("*/docs/**/*.md"))) + readme = pack_root / "README.md" + if readme.exists(): + targets.append(readme) + catalog = pack_root / ".catalog" + if catalog.exists(): + targets.extend(sorted(catalog.glob("*.md"))) + return targets + + +def validate_file(path: Path, pack_root: Path) -> list[str]: + errs: list[str] = [] + text = path.read_text(encoding="utf-8", errors="ignore") + is_skill_docs = "/skills/" in path.as_posix() and "/docs/" in path.as_posix() + is_pack_meta = (path == (pack_root / "README.md")) or (path.parent == (pack_root / ".catalog")) + for line_no, line in enumerate(text.splitlines(), start=1): + for m in MD_LINK_RE.finditer(line): + raw = m.group(1).strip() + if is_external(raw): + continue + base = raw.split("#", 1)[0].strip() + if not base.endswith(".md"): + continue + + # For pack README / catalog fragments, validate only pack-local docs references. + if is_pack_meta: + if not (base.startswith("docs/") or base.startswith("skills/")): + continue + link_path = (pack_root / base) + else: + link_path = (path.parent / base) + try: + resolved = link_path.resolve(strict=True) + except FileNotFoundError: + errs.append(f"{path}:{line_no}: missing linked doc '{raw}'") + continue + except RuntimeError: + errs.append(f"{path}:{line_no}: symlink loop for '{raw}'") + continue + + if is_skill_docs: + try: + resolved.relative_to(pack_root) + except ValueError: + errs.append( + f"{path}:{line_no}: link escapes pack root '{raw}' -> '{resolved}'" + ) + + if link_path.is_symlink(): + raw_link = os.readlink(link_path) + immediate = ( + link_path.parent / raw_link + if not os.path.isabs(raw_link) + else Path(raw_link) + ) + if immediate.is_symlink(): + errs.append( + f"{path}:{line_no}: symlink chain detected for '{raw}'" + ) + return errs + + +def main() -> int: + parser = argparse.ArgumentParser( + description="Validate markdown links in skills docs trees, pack README, and catalog fragments" + ) + parser.add_argument( + "paths", + nargs="*", + default=DEFAULT_PACKS, + help="Pack directories or SKILL.md paths", + ) + parser.add_argument("--json-out", help="Optional JSON summary output path") + args = parser.parse_args() + + packs = resolve_packs(args.paths) + if not packs: + packs = {Path(p).resolve() for p in DEFAULT_PACKS if (Path(p) / "skills").exists()} + + all_errors: list[str] = [] + scanned_files = 0 + for pack in sorted(packs): + for f in scan_targets(pack): + scanned_files += 1 + all_errors.extend(validate_file(f, pack)) + + summary = { + "packs_scanned": len(packs), + "files_scanned": scanned_files, + "error_count": len(all_errors), + } + + if args.json_out: + Path(args.json_out).write_text( + json.dumps({"summary": summary, "errors": all_errors}, indent=2), + encoding="utf-8", + ) + + if all_errors: + print("❌ Docs tree link validation failed:") + for err in all_errors: + print(f" • {err}") + print(json.dumps(summary, indent=2)) + return 1 + + print("✅ Docs tree links validated successfully") + print(json.dumps(summary, indent=2)) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/validate_skill_doc_links.py b/scripts/validate_skill_doc_links.py new file mode 100644 index 00000000..774a6b47 --- /dev/null +++ b/scripts/validate_skill_doc_links.py @@ -0,0 +1,196 @@ +#!/usr/bin/env python3 +""" +Validate skill markdown links to enforce skill-local docs convention. + +Rules: +- Forbid upward traversal into pack docs (../docs, ../../docs, etc). +- Internal docs links must use docs/... path from skill directory. +- Linked docs files must exist (symlinks allowed, dangling symlinks rejected). +- Resolved targets must stay within the pack root. +""" + +from __future__ import annotations + +import argparse +import json +import os +import re +import sys +from dataclasses import dataclass, field +from pathlib import Path +from typing import Iterable + +DEFAULT_PACKS = [ + "rh-sre", + "rh-developer", + "ocp-admin", + "rh-virt", + "rh-ai-engineer", + "rh-automation", +] + +MD_LINK_RE = re.compile(r"\[[^\]]+\]\(([^)]+)\)") + + +@dataclass +class ValidationResult: + scanned_files: int = 0 + scanned_links: int = 0 + checked_docs_links: int = 0 + errors: list[str] = field(default_factory=list) + + +def iter_skill_files(paths: Iterable[str]) -> list[Path]: + files: list[Path] = [] + for p in paths: + path = Path(p) + if path.is_file() and path.name == "SKILL.md": + files.append(path) + continue + if path.is_dir(): + skills_dir = path / "skills" + if skills_dir.exists(): + files.extend(sorted(skills_dir.glob("*/SKILL.md"))) + continue + pack_path = Path(p) + if (pack_path / "skills").exists(): + files.extend(sorted((pack_path / "skills").glob("*/SKILL.md"))) + dedup = sorted(set(files)) + return dedup + + +def is_external_link(target: str) -> bool: + lower = target.lower() + return ( + lower.startswith("http://") + or lower.startswith("https://") + or lower.startswith("mailto:") + or lower.startswith("#") + ) + + +def validate_skill_file(skill_file: Path, result: ValidationResult) -> None: + skill_dir = skill_file.parent + pack_root = skill_file.parent.parent.parent.resolve() + text = skill_file.read_text(encoding="utf-8") + + for line_no, line in enumerate(text.splitlines(), start=1): + for m in MD_LINK_RE.finditer(line): + result.scanned_links += 1 + raw_target = m.group(1).strip() + if is_external_link(raw_target): + continue + + target = raw_target.split("#", 1)[0].strip() + if ".md" not in target or "docs/" not in target: + continue + + result.checked_docs_links += 1 + normalized = target.replace("\\", "/") + + # Forbid upward traversal to docs. + if normalized.startswith("../") or "/../" in normalized: + result.errors.append( + f"{skill_file}:{line_no}: forbidden upward docs path '{raw_target}'" + ) + + # Enforce skill-local docs path. + if not normalized.startswith("docs/"): + result.errors.append( + f"{skill_file}:{line_no}: docs link must be skill-local 'docs/...', got '{raw_target}'" + ) + continue + + link_path = skill_dir / normalized + try: + resolved = link_path.resolve(strict=True) + except FileNotFoundError: + result.errors.append( + f"{skill_file}:{line_no}: missing linked doc '{raw_target}'" + ) + continue + except RuntimeError: + result.errors.append( + f"{skill_file}:{line_no}: symlink loop for '{raw_target}'" + ) + continue + + try: + resolved.relative_to(pack_root) + except ValueError: + result.errors.append( + f"{skill_file}:{line_no}: linked doc escapes pack root '{raw_target}' -> '{resolved}'" + ) + + if link_path.is_symlink(): + raw_link = os.readlink(link_path) + immediate = ( + link_path.parent / raw_link + if not os.path.isabs(raw_link) + else Path(raw_link) + ) + if immediate.is_symlink(): + result.errors.append( + f"{skill_file}:{line_no}: symlink chain detected for '{raw_target}'" + ) + + if link_path.is_symlink() and not link_path.exists(): + result.errors.append( + f"{skill_file}:{line_no}: dangling symlink '{raw_target}'" + ) + + +def main() -> int: + parser = argparse.ArgumentParser( + description="Validate skill docs links (skill-local docs convention)" + ) + parser.add_argument( + "paths", + nargs="*", + default=DEFAULT_PACKS, + help="Pack directories or SKILL.md paths to validate", + ) + parser.add_argument( + "--json-out", + help="Optional path to write machine-readable summary JSON", + ) + args = parser.parse_args() + + skill_files = iter_skill_files(args.paths) + result = ValidationResult(scanned_files=len(skill_files)) + + if not skill_files: + print("No SKILL.md files found for docs-link validation.") + return 0 + + print("🔍 Validating skill docs links...") + for sf in skill_files: + validate_skill_file(sf, result) + + summary = { + "scanned_files": result.scanned_files, + "scanned_links": result.scanned_links, + "checked_docs_links": result.checked_docs_links, + "error_count": len(result.errors), + } + + if args.json_out: + Path(args.json_out).write_text( + json.dumps({"summary": summary, "errors": result.errors}, indent=2), + encoding="utf-8", + ) + + if result.errors: + print("❌ Skill docs link validation failed:") + for err in result.errors: + print(f" • {err}") + print(json.dumps(summary, indent=2)) + return 1 + + print("✅ Skill docs links validated successfully") + print(json.dumps(summary, indent=2)) + return 0 + + +if __name__ == "__main__": + sys.exit(main())