Merge pull request #3406 from anupras-mohapatra-arm/copilot-instructions

Attempt at refactoring copilot-instructions into skills

Author: jasonrandrews

.github/copilot-instructions.md

@@ -1,45 +1,17 @@
-### Maintenance checks for Learning Paths and Install Guides
- 
-Please review the content in the specified content path and support my manual review by:
- 
-1. **Summarizing what this guide does**
-   - What the end goal is
-   - What platform(s) and environments it targets
-   - Any key assumptions the reader must meet
- 
-2. **Identifying dependencies and moving parts**
-   - OS, architecture, toolchains, frameworks, SDKs
-   - External repositories, models, downloads, or services
-   - Commands or workflows that are central to the guide
- 
-3. **Flagging potential risk areas**
-   - References to old OS versions, runtimes, or toolchains
-   - Dependencies that may be stale, deprecated, or fragile
-   - Links or resources that might require checking
-   - Steps that rely heavily on UI flows or screenshots
- 
-4. **Calling out anything that may need a closer human look**
-   - Ambiguous or unclear instructions
-   - Areas where “latest” or unpinned versions are used
-   - Places where ecosystem changes could affect correctness
- 
----
- 
-### How to behave
- 
-- Be conservative and transparent — if something is uncertain, say so.
-- Prefer **flagging** over **fixing**.
-- Do not invent new commands, tools, or workflows.
-- If suggesting changes, keep them minimal and clearly optional.
-- Treat this as a *conversation starter* for the reviewer, not a final verdict.
- 
----
- 
-### Output format (keep it lightweight)
- 
-Please respond with:
-- A short summary of the guide
-- A bulleted list of dependencies
-- A bulleted list of review flags or questions to consider
- 
-No code changes are required unless I explicitly ask for them.
+# Maintenance review guidance
+
+Use `.github/skills/stale-content-review/SKILL.md` for stale-content risk scans and maintenance triage.
+
+The skill includes:
+
+- A periodic scan workflow for Learning Paths and install guides.
+- A deterministic script for finding likely stale-content signals.
+- Reference guidance for interpreting temporal wording, screenshots, mutable dependencies, external links, old dates, and version-sensitive content.
+
+For one-off manual reviews, run:
+
+```bash
+python3 .github/skills/stale-content-review/scripts/stale_content_scan.py <content-path>
+```
+
+No content changes are required unless explicitly requested.

.github/review-guidelines.md

@@ -0,0 +1,102 @@
+---
+name: audit-images
+description: Audit and fix Markdown image alt text in Arm Learning Paths and install guides. Use when the user asks to review images, find deficient alt text, count faulty images, run project-level or path-level image audits, track before/after image quality, or update image alt text and captions against repository image guidance.
+---
+
+# Audit images
+
+## Description
+
+Audit Markdown image references in Arm Learning Paths and install guides, report deficient alt text and image syntax, and help fix alt text with useful instructional descriptions.
+
+Use the script for repeatable inventory and counting. Use assistant judgment for semantic alt-text quality and final edits.
+
+## Prerequisites
+
+- Work from the repository root.
+- Read `AGENTS.md` to locate shared guidance.
+- Read `references/image-guidance.md` before editing image alt text, captions, or image syntax.
+
+## Trigger
+
+Use this skill when the user asks to:
+
+- Audit images or alt text.
+- Find placeholder, vague, missing, malformed, or duplicated alt text.
+- Count faulty images across the project or inside one Path/guide.
+- Track image audit counts before and after fixes.
+- Fix image alt text, captions, or `#center` syntax.
+
+## Review levels
+
+### Project-level review
+
+Scan all Learning Paths and install guides unless the user gives a narrower scope.
+
+Use project-level review to:
+
+- Count total image references and faulty image references.
+- Group faults by content unit and issue type.
+- Identify high-priority directories or files for cleanup.
+- Produce a before/after baseline for tracking progress.
+
+Don't mass-edit the whole project unless the user explicitly asks. Prefer reporting the project-level inventory and then fixing one Path, guide, category, or batch.
+
+### Path/guide-level review
+
+Scan one Learning Path directory, install guide file, or install guide directory.
+
+Use path/guide-level review to:
+
+- List each faulty image with file, line, image path, current alt text, caption, and issue type.
+- Inspect surrounding Markdown context before changing alt text.
+- View local images when visual inspection is needed.
+- Fix alt text and syntax in place.
+- Re-run the audit and report before/after counts.
+
+## Workflow
+
+1. Identify whether the requested scope is project-level or path/guide-level.
+2. Run `.github/skills/audit-images/scripts/audit_images.py` on that scope.
+3. Record the baseline summary: total images, faulty images, content units affected, and issue counts.
+4. Depending on the request level, do the following:
+  - For project-level requests, summarize the results and suggest prioritized cleanup batches unless the user asked for edits.
+  - For path/guide-level edit requests, inspect the relevant Markdown context and image files.
+5. Suggest rewrites for deficient alt text using `references/image-guidance.md`.
+6. After the reviewer accepts suggestions, rewrite text, then re-run the audit on the same scope.
+7. Report before/after counts, files changed, and any remaining issues.
+
+## Validation rules
+
+- Treat the script as a detector, not the final authority. It flags likely problems for review.
+- Use `references/image-guidance.md` as the source of truth for alt text, captions, placeholder text, `#center` syntax, and figure numbering.
+- Don't replace meaningful alt text only because it is long or short; judge whether it helps the learner complete the task.
+- Preserve valid local image paths and existing captions unless they are wrong, vague, or outdated.
+- Preserve repository image syntax unless syntax cleanup is the target of the edit.
+
+## Error handling
+
+- If the script reports a missing local image path, verify whether the path is site-root-relative, file-relative, or intentionally external before changing content.
+- If an image cannot be inspected, fix only issues that can be resolved from surrounding Markdown context and state the limitation.
+- If project-level results are too large to edit safely, report the inventory and recommend a smaller batch.
+- If the audit script and visual/context review disagree, explain the judgment and leave a short note in the final response.
+
+## Script usage
+
+Run a project-level audit:
+
+```bash
+python3 .github/skills/audit-images/scripts/audit_images.py
+```
+
+Run a path-level audit:
+
+```bash
+python3 .github/skills/audit-images/scripts/audit_images.py content/learning-paths/servers-and-cloud-computing/example-path
+```
+
+Write JSON for tracking:
+
+```bash
+python3 .github/skills/audit-images/scripts/audit_images.py --format json --output image-audit.json
+```

.github/skills/audit-images/SKILL.md

@@ -0,0 +1,93 @@
+# Image guidance
+
+## Image formatting, alt text, and captions
+
+In this repository, the text before `#center` in an image tag is the alt text.
+
+Use this format:
+
+```md
+![Descriptive alt text#center](image.png "Optional caption")
+```
+
+Rules:
+- Do not use placeholder values such as `alt-txt`, `alt text`, or similar
+- Do not wrap alt text in extra quotation marks inside `[]`
+- Keep `#center` attached directly to the alt text with no extra space before it
+- The caption is optional and should be short, descriptive, and natural
+- Avoid outdated figure numbering such as `Figure 1:` unless the content genuinely depends on numbered cross-references
+
+Correct:
+
+```md
+![Diagram showing the WebGPU rendering flow for drawing a triangle#center](images/webgpu-draw-high-level.svg "WebGPU rendering flow for drawing a triangle")
+```
+
+Incorrect:
+
+```md
+!["Triangle using WebGPU" #center](images/webgpu-draw-high-level.svg "Figure 8: Triangle using WebGPU")
+```
+
+Incorrect:
+
+```md
+![alt-txt#center](images/webgpu-draw-high-level.svg "Figure 8: Triangle using WebGPU")
+```
+
+## Alt text requirements for tutorials
+
+Learning Paths and install guides are instructional content. Images are usually not decorative. Alt text must help the learner understand what they would otherwise miss.
+
+For every image, alt text should explain:
+- What is shown
+- What the learner should notice
+- Why it matters in the current step
+
+For screenshots:
+- Name the screen, tool, or interface shown
+- Mention the relevant UI element, tab, field, button, or output
+- Explain what the learner should look for in the screenshot
+- Connect the image to the current step or expected result
+
+For diagrams:
+- Describe the components and relationships shown
+- Explain the purpose of the diagram in the current task
+- Focus on the workflow, architecture, or sequence the learner needs to understand
+
+For terminal or output images:
+- State what command result or status is shown
+- Highlight the important confirmation, value, or error message
+- Explain why that output matters
+
+For hardware images:
+- Describe the device or setup only if it helps the learner complete the task
+- Avoid purely decorative descriptions
+
+## Alt text quality rules
+
+- Write meaningful alt text, not placeholders
+- Keep it concise but complete. One to three sentences is usually enough
+- Prefer instructional value over visual detail
+- Include visible text only when the learner needs that text
+- Do not use captions as a substitute for alt text
+- Do not encode alignment instructions inside the caption
+
+## Caption guidance
+
+- Use short, descriptive captions when needed
+- Captions should add context for all readers
+- Avoid `Figure X` numbering unless explicit image cross-references are required
+
+Preferred example:
+
+```md
+![Screenshot of the Arm Performance Studio timeline showing CPU activity spikes during Mandelbrot rendering. The Timeline tab is selected and the spike region is highlighted so the learner can identify where CPU activity increases during the run.#center](images/timeline-spike.png "Arm Performance Studio timeline showing CPU activity during Mandelbrot rendering")
+```
+
+## Image cleanup workflow
+
+- Replace all placeholder alt text such as `alt-txt` with meaningful descriptions
+- Keep the repository-specific `#center` syntax when fixing alt text
+- Do not remove valid alignment syntax during cleanup
+- For bulk cleanup, update the guidance first, then fix content by category or directory in manageable batches