From ff03c7d05227550a29e0ba6e5b2fca760b60695d Mon Sep 17 00:00:00 2001 From: Connor Rhodes Date: Sun, 5 Apr 2026 14:39:46 -0500 Subject: [PATCH] =?UTF-8?q?add=20skill:=20system-diagnostic=20=E2=80=94=20?= =?UTF-8?q?audits=20index/folder=20parity,=20trigger=20collisions,=20redun?= =?UTF-8?q?dancy,=20and=20system=20health?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- _skill-index.md | 7 +++ system-diagnostic/SKILL.md | 112 +++++++++++++++++++++++++++++++++++++ 2 files changed, 119 insertions(+) create mode 100644 system-diagnostic/SKILL.md diff --git a/_skill-index.md b/_skill-index.md index 612a7b8..898f805 100644 --- a/_skill-index.md +++ b/_skill-index.md @@ -22,6 +22,7 @@ description: Master index of all skills in your robot assistant system. Your ass | "write a business case for a pro dev expense," "professional development business case," "justify a pro dev expense," "pro dev justification" | **pro-dev-justification** | | "update the skill index," "sync the skill index," "refresh the skill index," "clean up the skill index," "garbage collect the index" | **update-skill-index** | | "add a task," "create a task," "what's on my plate," "show today's tasks," "mark that done," "delete that task," "what's due," "upcoming tasks" | **vikunja-tasks** | +| "run system diagnostic," "audit my skills," "check system health," "skill audit," "health check" | **system-diagnostic** | --- @@ -81,6 +82,12 @@ description: Master index of all skills in your robot assistant system. Your ass **File:** `skills/vikunja-tasks/SKILL.md` **Dependencies:** `vik` CLI installed at `$HOME/.local/bin/vik` +### System Diagnostic +**Purpose:** Audits the robot assistant system for consistency and health. Checks index/folder parity, trigger collisions, skill redundancy, AGENTS.md completeness, skill file quality, build log currency, and dependency status. +**Triggers:** "run system diagnostic," "audit my skills," "check system health," "skill audit," "health check" +**File:** `skills/system-diagnostic/SKILL.md` +**Dependencies:** None + --- ## Adding New Skills diff --git a/system-diagnostic/SKILL.md b/system-diagnostic/SKILL.md new file mode 100644 index 0000000..abd2567 --- /dev/null +++ b/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.