refactor: standardize skill documentation on references/ layout (#156)

* chore: standardize skill documentation on references/ layout

* fix: update files that point at docs/

* fix: review fixes and validation adding

* fix: review fixes

* docs: replaced 22 duplicate files with symlinks across 11 skills

* fix: remove redundant CLAUDE line from reference doc

Author: rhartuv

.claude/skills/agentic-contribution-skill/SKILL.md

@@ -118,7 +118,7 @@ Ask concisely, validate before proceeding. Make additional questions if needed t
 4. **Workflow**: "Steps with MCP tools?" (e.g., "1. Validate VM - resources_get")
 5. **Common Issues**: "3+ issues: problem: cause: solution"
 6. **Prerequisites**: "Special requirements? (env vars, permissions)"
-7. **External Resources**: "Any external docs/links/KB articles referenced?" (will be saved to `docs/` folder)
+7. **External Resources**: "Any external references/links/KB articles referenced?" (will be saved to `references/` folder)
 
 **Quality over Speed**: Focus on gathering complete, accurate information. Validation and iteration will ensure correctness - prioritize quality of final result over generation time.
 
@@ -210,7 +210,7 @@ Show complete spec:
 **Workflow**: <N> steps
 **Common Issues**: <N> documented
 **MCP Tools**: <tool_count> tools (verified to exist)
-**External Resources**: <count> (will be saved to docs/)
+**External Resources**: <count> (will be saved to references/)
 **Human-in-the-Loop**: <Yes/No>
 
 [If >10 steps or complex workflow]:
@@ -229,26 +229,26 @@ Proceed with generation? (yes/no)
 ```bash
 mkdir -p <pack>/skills/<skill-name>/
 # If external resources provided by user:
-mkdir -p <pack>/skills/<skill-name>/docs/
+mkdir -p <pack>/skills/<skill-name>/references/
 ```
 
 **Generate files**:
 1. **SKILL.md**: YAML frontmatter + mandatory sections (follow SKILL_DESIGN_PRINCIPLES.md template - already consulted in Phase 3)
    - Focus on complete, production-ready content
    - Include all relevant information from user and verified sources
-   - Keep main skill focused; detailed content can go to `docs/` if needed
-2. **docs/ folder** (if applicable):
-   - `docs/workflow-details.md` - Extended workflow explanations if skill is concise
-   - `docs/common-issues.md` - Detailed troubleshooting with full KB article content
-   - `docs/examples.md` - Comprehensive usage examples
-   - `docs/external-resources.md` - Any external docs/links/KB articles mentioned by user
+   - Keep main skill focused; detailed content can go to `references/` if needed
+2. **references/ folder** (if applicable):
+   - `references/workflow-details.md` - Extended workflow explanations if skill is concise
+   - `references/common-issues.md` - Detailed troubleshooting with full KB article content
+   - `references/examples.md` - Comprehensive usage examples
+   - `references/external-resources.md` - Any external references/links/KB articles mentioned by user
 3. **Update <pack>/AGENTS.md**: Add intent routing entry
 4. **Create <pack>/mcps.json**: If new MCP server needed (use `${ENV_VAR}` format)
 5. **Compass manifests**: Run **compass-manifest-maintenance** (`.claude/skills/compass-manifest-maintenance/`) for registered packs — skill `catalog-info.yaml`, Location targets, bidirectional `dependsOn`/`dependencyOf` on plugin and MCP manifests
 6. **Update marketplace/rh-agentic-collection.yml** in [agentic-catalog](https://github.com/RHEcosystemAppEng/agentic-catalog): If new pack (register pack for Lola installation)
 7. **Create pack structure**: If new pack (README.md, AGENTS.md, skills/ directory)
 
-Generate SKILL.md following the mandatory section template in SKILL_DESIGN_PRINCIPLES.md (already consulted in Phase 3). If SKILL.md becomes too long, move detailed content to `docs/` with references in main file.
+Generate SKILL.md following the mandatory section template in SKILL_DESIGN_PRINCIPLES.md (already consulted in Phase 3). If SKILL.md becomes too long, move detailed content to `references/` with references in main file.
 
 ### Phase 5: Validation & Iteration
 
@@ -267,18 +267,18 @@ uv run python scripts/validate_skills_tier2.py <pack>/skills/<skill-name>/SKILL.
 **Report clearly**:
 - ✅ PASSED → Proceed to Phase 6
 - ⚠️ WARNINGS → Review warnings with user
-  - Non-standard subdirectory (docs/) is acceptable if needed
+  - Non-standard subdirectory (references/) is acceptable if needed
   - Description buzzwords acceptable if accurate for critical skills
   - Ask: "Warnings acceptable? (yes/no)"
 - ❌ ERRORS → **Fix required**, iterate until validation passes
 
 **Iteration Protocol** (if validation fails):
 1. **Analyze errors**: Identify specific issues (line count, missing sections, format problems)
 2. **Determine fix strategy**:
-   - Line count exceeded → Move detailed content to `docs/` folder, keep main skill concise
+   - Line count exceeded → Move detailed content to `references/` folder, keep main skill concise
    - Missing sections → Add required sections per DP7
    - Format issues → Correct frontmatter, section headers, or structure
-3. **Apply fixes**: Edit SKILL.md and/or create docs/ files
+3. **Apply fixes**: Edit SKILL.md and/or create references/ files
 4. **Re-validate**: Run both Tier 1 and Tier 2 again
 5. **Repeat until ✅ PASSED**
 
@@ -358,23 +358,23 @@ curl -LsSf https://astral.sh/uv/install.sh | sh
 
 **Cause**: Skill content is comprehensive but exceeds agentskills.io 500-line limit
 
-**Fix**: Iterate to move detailed content to `docs/` folder:
-1. Create `<skill>/docs/` directory
-2. Move detailed workflow explanations to `docs/workflow-details.md`
-3. Move full troubleshooting KB articles to `docs/common-issues.md`
-4. Move comprehensive examples to `docs/examples.md`
-5. Keep main SKILL.md concise with references to docs/
+**Fix**: Iterate to move detailed content to `references/` folder:
+1. Create `<skill>/references/` directory
+2. Move detailed workflow explanations to `references/workflow-details.md`
+3. Move full troubleshooting KB articles to `references/common-issues.md`
+4. Move comprehensive examples to `references/examples.md`
+5. Keep main SKILL.md concise with references to references/
 6. Re-run validation
 
 **Example**:
 ```markdown
 ## Common Issues
 
-See [docs/common-issues.md](docs/common-issues.md) for detailed solutions.
+See [references/common-issues.md](references/common-issues.md) for detailed solutions.
 
 ### Issue 1: Snapshot Fails
 Storage doesn't support snapshots.
-**Solution**: Use snapshot-capable storage. [Details](docs/common-issues.md#issue-1)
+**Solution**: Use snapshot-capable storage. [Details](references/common-issues.md#issue-1)
 ```
 
 ## Dependencies
@@ -443,7 +443,7 @@ See [Prerequisites](#prerequisites) section for required system tools (git, uv,
 
 ## Example Usage
 
-**See [docs/examples.md](docs/examples.md) for comprehensive examples.**
+**See [references/examples.md](references/examples.md) for comprehensive examples.**
 
 ### Quick Example: Creating VM Backup Skill
 
@@ -461,8 +461,8 @@ Skill guides through:
 Result: Production-ready skill in rh-virt/skills/vm-backup-create/
 ```
 
-**More examples**: [docs/examples.md](docs/examples.md)
+**More examples**: [references/examples.md](references/examples.md)
 - Example 1: VM backup skill (complete create interaction)
 - Example 2: Non-representative name correction
 - Example 3: Importing an existing skill (analysis, adaptation, validation)
-- Example 4: Large skill requiring docs/ folder with iteration
+- Example 4: Large skill requiring references/ folder with iteration

…ntic-contribution-skill/docs/examples.md …ontribution-skill/references/examples.md.claude/skills/agentic-contribution-skill/docs/examples.md renamed to .claude/skills/agentic-contribution-skill/references/examples.md .claude/skills/agentic-contribution-skill/docs/examples.md renamed to .claude/skills/agentic-contribution-skill/references/examples.md

@@ -210,7 +210,7 @@ Ready to commit? (yes/no)
 [Git workflow with confirmations]
 ```
 
-## Example 4: Large Skill Requires docs/ Folder
+## Example 4: Large Skill Requires references/ Folder
 
 ```
 [After Phase 2 - Definition]
@@ -236,14 +236,14 @@ Running validation...
 
 ❌ Tier 1: FAILED - Line count exceeds 500 (got 1533)
 
-**Iteration 1**: Moving detailed content to docs/ folder...
+**Iteration 1**: Moving detailed content to references/ folder...
 
-Creating docs/:
-✅ docs/workflow-details.md (extended step explanations)
-✅ docs/common-issues.md (full KB articles with solutions)
-✅ docs/examples.md (comprehensive success/rollback scenarios)
+Creating references/:
+✅ references/workflow-details.md (extended step explanations)
+✅ references/common-issues.md (full KB articles with solutions)
+✅ references/examples.md (comprehensive success/rollback scenarios)
 
-Updating SKILL.md with references to docs/...
+Updating SKILL.md with references to references/...
 
 Running validation again...
 
@@ -254,9 +254,9 @@ Running validation again...
 
 **Files**:
 ✅ ocp-admin/skills/cluster-upgrade/SKILL.md (323 lines)
-✅ ocp-admin/skills/cluster-upgrade/docs/workflow-details.md
-✅ ocp-admin/skills/cluster-upgrade/docs/common-issues.md
-✅ ocp-admin/skills/cluster-upgrade/docs/examples.md
+✅ ocp-admin/skills/cluster-upgrade/references/workflow-details.md
+✅ ocp-admin/skills/cluster-upgrade/references/common-issues.md
+✅ ocp-admin/skills/cluster-upgrade/references/examples.md
 
 **Quality**: Production-ready, comprehensive, validation compliant
 

.claude/skills/compass-manifest-maintenance/SKILL.md

@@ -96,6 +96,19 @@ test -f CLAUDE.md && echo "✓ repo root" || echo "✗ wrong directory"
 
 7. **Reconcile plugin MCP deps** — plugin `dependsOn` = union of all `mcpserver:` refs across pack skill manifests.
 
+8. **Verify skill documentation layout** ([agent-plugins.org](https://agent-plugins.org/specification) / agentskills.io):
+   - Skill-local documentation belongs in `skills/<skill-name>/references/`, not `docs/`.
+   - **Allowed locations only:** pack-level `<pack>/references/` or skill-level `skills/<name>/references/`. **No** `references/references/` nesting inside a skill.
+   - **Scan** every `skills/<skill-name>/` for a `docs/` directory.
+   - **If `docs/` exists:**
+     1. Rename or merge into `references/` (merge file-by-file when both exist).
+     2. If `docs/references/` existed, flatten into `skills/<name>/references/` (not `references/references/`).
+     3. Update markdown links in `SKILL.md` and all files under the skill directory: `docs/...` → `references/...` (also `./docs/...` and relative `../docs/...` segments).
+     4. **Delete** the `docs/` directory after migration — do not leave an empty or stale `docs/` folder.
+     5. Update symlinks under `references/` that still target `docs/` paths to `references/`.
+   - Shared reference pools (e.g. `common-issues.md`, `live-doc-lookup.md`) symlinked into multiple skills must use link targets that resolve when opened through the symlink (same-directory or `references/...` paths from the symlink location).
+   - Run `uv run python scripts/validate_compass_manifests.py` to confirm (includes manifest roster, bidirectional refs, and references layout).
+
 ### 2. Register a new pack in Compass
 
 1. Create `<pack>/<pack>-plugin.yaml` from [assets/plugin-catalog-info.yaml](assets/plugin-catalog-info.yaml) with **`spec.lifecycle: development`** (default for new packs; confirm with user before raising maturity).
@@ -106,7 +119,7 @@ test -f CLAUDE.md && echo "✓ repo root" || echo "✗ wrong directory"
 
 ### 3. Drift / compliance audit
 
-Run `uv run python scripts/validate_compass_manifests.py` (or `make validate-compass-manifests`). It enforces the same structural rules as this table:
+Run `uv run python scripts/validate_compass_manifests.py` (or `make validate-compass-manifests`). It enforces manifest roster, bidirectional refs, and skill references layout:
 
 | Check | Rule |
 |-------|------|
@@ -117,6 +130,7 @@ Run `uv run python scripts/validate_compass_manifests.py` (or `make validate-com
 | Dangling refs | Every ref resolves to on-disk manifest or documented canonical MCP |
 | Forbidden | No `partOf`/`hasPart` on AiResource/MCPServer; no redundant `dependsOn: system:default/agentic-plugins` on plugins |
 | Namespace | Refs use `ai5-marketplace` except `mcpserver:redhat/*` and `default/agentic-plugins` |
+| Skill docs layout | No `skills/<name>/docs/` (delete after migrate); no `references/references/` nesting; links use `references/...` or `./references/...`, not `docs/...` |
 
 Report violations with file path and fix per workflow §1. Do not weaken checks.
 
@@ -131,6 +145,7 @@ Report violations with file path and fix per workflow §1. Do not weaken checks.
 - If skill on disk has no manifest → create from `assets/skill-catalog-info.yaml` and add Location target.
 - If inverse `dependencyOf` missing on plugin or MCP → update per [relationship-rules.md](references/relationship-rules.md).
 - If MCP ref cannot be resolved → grep pack manifests; do not invent new `mcpserver:` refs.
+- If `skills/<name>/docs/` exists or markdown links use `docs/...` → rename/merge to `references/`, flatten any `references/references/`, update link paths, **delete** `docs/`, fix symlinks; re-run `validate_compass_manifests.py`.
 
 ## Self-review checklist
 
@@ -141,6 +156,7 @@ Report violations with file path and fix per workflow §1. Do not weaken checks.
 - [ ] Pack Location lists every skill manifest path.
 - [ ] Plugin `dependencyOf` lists every skill in the pack.
 - [ ] No `partOf`/`hasPart` on custom kinds.
+- [ ] Skill documentation uses `references/` only — no leftover `docs/` directory, no `references/references/` nesting; links use `references/...` or `./references/...`.
 
 ## Dependencies
 
@@ -159,7 +175,6 @@ None — uses Read, Glob, Grep, Bash.
 
 ### Reference Documentation
 
-- [CLAUDE.md](../../CLAUDE.md) — entity kinds, namespaces, reference formats
 - `scripts/validate_compass_manifests.py` — CI roster and bidirectional ref checks
 - [references/relationship-rules.md](references/relationship-rules.md)
 - [references/mcp-mapping.md](references/mcp-mapping.md)
@@ -171,11 +186,12 @@ None — uses Read, Glob, Grep, Bash.
 - **Orchestration gaps** — `remediation`-style skills missing skill→skill edges or inverse `dependencyOf` on depended skills.
 - **Canonical vs owned** — Lightspeed and Security use `mcpserver:redhat/...`; do not register duplicates in `mcps/`.
 - **Unregistered packs** — `rh-developer`, `rh-ai-engineer`, `rh-automation` exist on disk but are not in root Location until explicitly added.
+- **`docs/` vs `references/`** — agent-plugins.org expects `references/` for skill-local docs; rename/merge, flatten `references/references/`, update links, **delete** `docs/`, then run `make validate-compass-manifests`.
 
 ## Example usage
 
 ```bash
-# CI structural validation (roster + bidirectional refs)
+# CI structural validation (roster + bidirectional refs + references layout)
 uv run python scripts/validate_compass_manifests.py
 # or: make validate-compass-manifests
 

CONTRIBUTING.md

@@ -62,6 +62,7 @@ Both tiers must pass before submitting a PR.
 
 - [ ] Tier 1 validation passed (agentskills.io spec)
 - [ ] Tier 2 validation passed (design principles)
+- [ ] Compass manifests and references layout validated: `make validate-compass-manifests`
 - [ ] Skill doc links validated: `uv run python scripts/validate_skill_doc_links.py <pack>/skills/<skill-name>/SKILL.md`
 - [ ] Skill doc tree links validated: `uv run python scripts/validate_docs_tree_links.py <pack>/skills/<skill-name>/SKILL.md`
 - [ ] Pack AGENTS.md intent routing updated

Makefile

@@ -9,7 +9,7 @@ help:
 	@echo "  validate-structure            - Structure, links, compliance, MCP tools (no per-skill tier checks)"
 	@echo "  validate-collection-schema    - Schema + roster + banners (subset of compliance)"
 	@echo "  validate-collection-compliance - Full .catalog compliance (includes collection.json drift)"
-	@echo "  validate-compass-manifests     - Compass catalog-info.yaml roster and bidirectional refs"
+	@echo "  validate-compass-manifests     - Compass manifests, roster, refs, and skill references/ layout"
 	@echo "  validate-skill-design         - Validate all skills (use PACK=rh-sre for a specific pack)"
 	@echo "  validate-skill-design-changed - Validate only changed skills (staged + unstaged, for local dev)"
 	@echo "  validate-mcp-tools            - Validate allowed-tools against live MCP servers (requires podman)"
@@ -56,6 +56,8 @@ validate: check-uv
 	uv run python scripts/validate_skill_doc_links.py || EXIT=1; \
 	echo "=== Validating docs tree links..."; \
 	uv run python scripts/validate_docs_tree_links.py || EXIT=1; \
+	echo "=== Running compass layout regression tests..."; \
+	uv run python scripts/test_validate_compass_layout.py || EXIT=1; \
 	echo "=== Validating collection compliance (.catalog/)..."; \
 	uv run python scripts/validate_collection_compliance.py || EXIT=1; \
 	echo "=== Validating Compass manifests..."; \
@@ -80,6 +82,8 @@ validate-structure: check-uv
 	uv run python scripts/validate_skill_doc_links.py || EXIT=1; \
 	echo "=== Validating docs tree links..."; \
 	uv run python scripts/validate_docs_tree_links.py || EXIT=1; \
+	echo "=== Running compass layout regression tests..."; \
+	uv run python scripts/test_validate_compass_layout.py || EXIT=1; \
 	echo "=== Validating collection compliance (.catalog/)..."; \
 	uv run python scripts/validate_collection_compliance.py || EXIT=1; \
 	echo "=== Validating Compass manifests..."; \

SKILL_DESIGN_PRINCIPLES.md

@@ -182,10 +182,13 @@ Every skill MUST include a **Dependencies** section listing:
 ```
 
 **Skill-local docs rule (required):**
-- Internal docs consumed by a skill must resolve under that skill directory using `docs/...` links.
-- Do **not** use upward traversal links to pack-level docs such as `../docs/...`, `../../docs/...`, or `../../../docs/...`.
-- Shared docs may be reused via symlinks under `skills/<skill>/docs/...`.
-- Pack-level `docs/INDEX.md` and `docs/SOURCES.md` may exist for repository navigation/source attribution, but skills must not depend on them at execution time.
+- Internal docs consumed by a skill must resolve under that skill directory using `references/...` or `./references/...` links in `SKILL.md`.
+- Do **not** use upward traversal links to pack-level docs such as `../references/...`, `../../references/...`, or `../../../references/...`.
+- Shared docs may be reused via symlinks under `skills/<skill>/references/...`. Link targets inside shared pool files must resolve when the file is opened through a skill symlink (use same-directory or `references/...` paths from the symlink location).
+- After migrating `docs/` → `references/`, **delete** the `skills/<name>/docs/` directory — do not leave empty or stale folders.
+- Do **not** nest `references/references/` inside a skill. If `docs/references/` existed, flatten files into `skills/<name>/references/`.
+- Pack-level `<pack>/references/` or skill-level `skills/<name>/references/` are the only allowed reference locations.
+- Pack-level `references/INDEX.md` and `references/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.
 

ocp-admin/AGENTS.md

@@ -67,11 +67,11 @@ Security validation skills use Python helper scripts in `scripts/security-valida
    - Triggering cluster installation
    - Applying static network configuration
 3. **Verify prerequisites** — before executing skills, check that required environment variables are set (OFFLINE_TOKEN for cluster creation/inventory, KUBECONFIG for cluster reports).
-4. **Reference documentation** — when users encounter errors, point them to specific docs:
-   - Cluster creation issues → `docs/troubleshooting.md`
-   - Network configuration → `docs/networking.md`, `docs/static-networking-guide.md`
-   - Hardware requirements → `docs/host-requirements.md`
-   - Multi-cluster authentication → `docs/multi-cluster-auth.md`
+4. **Reference documentation** — when users encounter errors, point them to skill-local references under `skills/cluster-creator/references/`:
+   - Cluster creation issues → `skills/cluster-creator/references/troubleshooting.md`
+   - Network configuration → `skills/cluster-creator/references/networking.md`, `skills/cluster-creator/references/static-networking-guide.md`
+   - Hardware requirements → `skills/cluster-creator/references/host-requirements.md`
+   - Multi-cluster authentication → `skills/cluster-creator/references/multi-cluster-auth.md`
 5. **Installation monitoring** — for `/cluster-creator`, actively monitor installation progress and report validation errors from cluster events. Don't just trigger installation and disappear.
 6. **OpenShift cluster verification** — `/cluster-report` verifies each kubeconfig context is a genuine OpenShift cluster before reporting. Non-OpenShift contexts are skipped by default to avoid errors.
 7. **Suggest next steps** — after completing a skill, suggest related skills or documentation the user might need next.