add skill: system-diagnostic — audits index/folder parity, trigger collisions, redundancy, and system health

system-diagnostic/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: system-diagnostic
+description: Audits the robot assistant system for consistency and health. Use this skill whenever the user asks to check system health, audit skills, run a diagnostic, verify the skill index, or find redundant/missing/outdated skills. Also trigger proactively after major changes like adding or removing multiple skills.
+---
+
+# System Diagnostic
+
+Perform a structured audit of the robot assistant system and produce a health report.
+
+## When to Run
+
+- User explicitly asks for a diagnostic, audit, or health check
+- After adding or removing several skills at once
+- When the system feels like it's drifted — skills not triggering right, index feels stale, etc.
+
+---
+
+## Audit Checklist
+
+Work through each check in order. Collect all findings before writing the report — don't stop at the first issue.
+
+### 1. Index ↔ Folder Parity
+
+- List every entry in `skills/_skill-index.md`
+- List every folder in `skills/` that contains a `SKILL.md`
+- Flag any index entry with no corresponding folder (ghost entry)
+- Flag any folder with no index entry (orphaned skill)
+
+### 2. Trigger Collision Check
+
+- Collect all trigger phrases from the Quick Trigger Reference table in the index
+- Check for exact matches or near-matches across skills (e.g., two skills that would both fire on "create a task")
+- Flag any collisions or ambiguous overlaps
+
+### 3. Redundancy Check
+
+- Read the `description` frontmatter of each `SKILL.md`
+- Identify any two skills with substantially overlapping purpose — skills that would handle the same request
+- Flag pairs where one skill likely makes the other unnecessary, or where they'd conflict
+
+### 4. AGENTS.md Health
+
+Check that AGENTS.md contains:
+- [ ] Identity section (name, role)
+- [ ] Preferences
+- [ ] Rules
+- [ ] Reference to skill index
+- [ ] Connected Tools section (even if empty)
+- [ ] Workspace structure notes
+
+### 5. Skill File Quality
+
+For each `SKILL.md`, verify:
+- [ ] Has `name` frontmatter field
+- [ ] Has `description` frontmatter field (this is the primary trigger mechanism — missing or vague descriptions cause skills to not fire)
+- [ ] Body has at least minimal instructions (not just a stub)
+
+### 6. Build Log Currency
+
+- Check which videos are logged in `skills/_build-log.md`
+- Note any skills that exist but have no corresponding build log entry
+- Flag if the log appears to be missing entries (e.g., a skill exists with no record of when or why it was built)
+
+### 7. Dependencies Check
+
+For any skill that lists dependencies (tools, CLIs, MCP connectors):
+- Note whether those dependencies are confirmed available or still pending
+- Flag anything that's listed as "TBD" or "future" and has been that way for a while
+
+---
+
+## Report Format
+
+ALWAYS use this structure:
+
+```
+# System Health Report
+Generated: [date]
+
+## Summary
+One-paragraph overview of overall system state — healthy, needs attention, or has critical gaps.
+
+## Passing Checks
+- [List what's clean and working]
+
+## Issues Found
+### [Issue Title]
+**Type:** Ghost entry / Orphan / Collision / Redundancy / Missing field / etc.
+**Details:** What exactly is wrong and where
+**Suggested fix:** What to do about it
+
+[Repeat for each issue]
+
+## Recommendations
+- [Next skill to build, based on gaps or the user's work context]
+- [Any maintenance actions worth doing soon]
+
+## Maintenance Checklist
+Things to verify whenever the system grows:
+- [ ] Every skill folder has a SKILL.md
+- [ ] Every skill in the index has a folder
+- [ ] No trigger phrase collisions
+- [ ] Build log reflects current skill set
+- [ ] AGENTS.md Connected Tools section is current
+- [ ] Skill descriptions match what the skills actually do
+```
+
+---
+
+## Output
+
+Save the report as `system-health-report.md` in the workspace root (overwrite if one already exists). Then summarize findings in the conversation — focus on issues and recommendations, not the full report.