Problem
Skills must be self-contained — everything needed to execute a skill (docs, scripts, referenced files) must live inside skills/<skill-name>/. Three packs violate this, referencing files via upward traversal (../, ../../) or runtime absolute paths.
This breaks portability: a skill installed in isolation will have broken links or missing dependencies.
Violations (26 skills across 3 packs)
| Pack |
Failing Skills |
Root Cause |
rh-ai-engineer |
11/11 |
All skills link to a shared skills/references/ folder via ../references/*.md |
ocp-admin |
7/7 |
Skills reference pack-level scripts via ../../scripts/ or absolute $(git rev-parse --show-toplevel)/ocp-admin/scripts/; cluster-creator has a broken link to a non-existent skills/README.md |
rh-sre |
8/13 |
Skills link to sibling skill files via ../sibling/SKILL.md; execution-summary implicitly reads pack-level docs/ paths |
Fixes
- rh-ai-engineer — symlink or copy the 4 shared files (
skill-conventions.md, common-issues.md, openshift-fallback-templates.md, live-doc-lookup.md) into each skill's own references/ subfolder and update links to references/<file>.md
- ocp-admin — move shared scripts into each skill's folder, or consolidate the 4 CVE-related skills that share the same script directory into a single skill with a local
scripts/ subfolder; fix broken link in cluster-creator
- rh-sre — inline the referenced policy sections from sibling SKILL.md files, or extract them to a local
docs/ file within each skill; add a local docs/ folder to execution-summary with the required pack-level docs
Acceptance Criteria
Problem
Skills must be self-contained — everything needed to execute a skill (docs, scripts, referenced files) must live inside
skills/<skill-name>/. Three packs violate this, referencing files via upward traversal (../,../../) or runtime absolute paths.This breaks portability: a skill installed in isolation will have broken links or missing dependencies.
Violations (26 skills across 3 packs)
rh-ai-engineerskills/references/folder via../references/*.mdocp-admin../../scripts/or absolute$(git rev-parse --show-toplevel)/ocp-admin/scripts/;cluster-creatorhas a broken link to a non-existentskills/README.mdrh-sre../sibling/SKILL.md;execution-summaryimplicitly reads pack-leveldocs/pathsFixes
skill-conventions.md,common-issues.md,openshift-fallback-templates.md,live-doc-lookup.md) into each skill's ownreferences/subfolder and update links toreferences/<file>.mdscripts/subfolder; fix broken link incluster-creatordocs/file within each skill; add a localdocs/folder toexecution-summarywith the required pack-level docsAcceptance Criteria
../in markdown links, no pack-level runtime path references)SKILL_DESIGN_PRINCIPLES.md§5 expanded to cover scripts and all file types, not just docsvalidate_skills_tier2.py(or linter) enforces no upward traversal in SKILL.md links