Skip to content

Skills must be self-contained: 26 skills reference files outside their folder #140

Description

@dmartinol

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

  1. 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
  2. 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
  3. 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

  • All 26 failing skills pass a traversal check (no ../ in markdown links, no pack-level runtime path references)
  • SKILL_DESIGN_PRINCIPLES.md §5 expanded to cover scripts and all file types, not just docs
  • validate_skills_tier2.py (or linter) enforces no upward traversal in SKILL.md links

Metadata

Metadata

Assignees

Labels

bugSomething isn't workingskills

Type

No type

Fields

No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions