Help individual power users maintain their own skill collections over the long term, preventing time rot, upgrade breakage, and external dependency zombification.
Trigger scenarios (strictly based on real user language)
When the user says any of the following, activate this skill immediately:
- "My skills stopped working" "After the upgrade, the old skills aren't recognized anymore"
- "The skills have rotted" "The external dependencies are broken" "My personal Arsenal is a mess"
- "Help me check skill health" "Skill lifecycle" "Long-term skill maintenance"
- "The Skill that worked so well for me 1-2 years ago is now completely unrecognized by Claude"
- "My deployment-type skills can't be executed anymore, the external project is offline"
- "After upgrading Claude Code, lots of skills no longer trigger"
Especially suited for heavy users maintaining personal skill collections (a mix of Arsenal symlinks + custom + community copies) for over 1 year.
Workflow (diagnosis first + user gating)
Phase 1: Read-only discovery (never modify without authorization)
- Scan the
~/.claude/skillsdirectory - Distinguish each skill'ssource：
- Arsenal official symlink (
ln -spoints to this repository) - Purely custom (written by the user)
- Community copy / fork (historical snapshot)
- Arsenal official symlink (
- Extract frontmatter metadata (with special attention to the newly added version, last_verified, external_deps, provenance)
- Scan skill content for hard dependencies:
- GitHub repository URLs (especially those without a pinned commit)
pip install/npm installno version locking- Specific file path assumptions
Phase 2: Multi-dimensional health diagnosis
Score + evidence across the following 4 dimensions:
- Time rot risk(last_verified more than 6 months / more than 12 months ago)
- Trigger description failure risk(description outdated, lacking the real pain-point language of current Claude users, conflicting with known mechanism changes)
- External dependency zombification risk(repository 404, API changes, package disappearance)
- Structural health risk(missing health self-check module, overly complex, no graceful degrade, violating progressive disclosure)
Phase 3: Output a structured health report
Must include:
- Overall health score (🔴 severe / 🟡 warning / 🟢 healthy)
- Risk-gradedissue list(each item with concrete evidence: file path + line number + last verification time)
- For each issue, aminimal actionable fix recommendation(prefer "update metadata" over "major overhaul")
- One-click runnable commands (actually run only after the user says "execute")
- Collaboration recommendations with
codex-retrospective(distill the patterns found this time into AGENTS.md rules)
See the complete report template at references/健康报告模板.md。
Phase 4: Safe execution (any write operation must pass user confirmation)
- Before any modification, a dry-run + explicit diff display is required
- Provide a rollback plan
- Never touch the user's CLAUDE.md / AGENTS.md (unless the user explicitly says "write it into AGENTS.md for me")
- For serious issues, prioritize recommending "first back up the entire ~/.claude/skills"
Recommended health self-check module (all long-term Skills should have this built in)
Core principles(from long-term health research):
- Declare the current version + last_verified + tested_on (claude_version + arsenal_commit)
- List external dependencies + last verification time + risk rating
- Provide a graceful_degrade declaration
- Automatically trigger the self-check when the user asks about "health/after upgrade/rot"
Complete reusable template See:
references/health-module.md(embedded module + integration method with retrospective)references/健康报告模板.md(output format)
Suggestion: For every Skill you write, copy and paste the declaration section from health-module.md at the end of SKILL.md. This is the lowest-cost insurance to prevent your future self from rotting.
Synergy with existing tools (personal maintenance loop)
Most recommended combination：
- This skill diagnoses the problem → output an evidence list
- Feed the evidence to
codex-retrospective→ distill 1-2 "long-term maintenance rules" and persist them to AGENTS.md (evidence-driven, minimal change) - In conjunction with
codex-fluentestablish a "personal Arsenal health ritual" every 3-6 months (report-only + recurring reminder)
Other synergies:
- The output can be fed directly to trigger-related skills to optimize the description
- Recommended to combine with
vibeguardto perform task contract regression checks
Safety Contract (iron rules)
- Read-only first: By default, never modify any files
- Any modification must only be made after the user **explicitly says "execute" or "confirm fix"**
- Always protect the user's existing CLAUDE.md, AGENTS.md, and custom configurations
- When serious issues are found, **prioritize giving the advice "back up first, then operate"**
- Chinese output, clear structure, convenient for personal archiving and long-term tracking
- Never hardcode any paths, ports, or personal repository names
Health and version declaration
Current version：v1.0 Last manual verification: 2026-05-28 (Claude Code 20250514 + Arsenal main branch) Design goal: Turn "being able to still use a personal Arsenal after 1-2 years of maintenance" from luck into a repeatable engineering practice.
Limitations (honest disclosure)
This skillwill not：
- automatically fix "behavior drift" that requires a large amount of human semantic judgment (for example, a Skill's core logic failing because Claude's reasoning style has changed)
- scan skills that you have not placed in
~/.claude/skills(including rules written directly in CLAUDE.md) - replace
codex-retrospective's evidence-driven rule distillation
What it is best at isdiscovering, at low cost and with high recall, problems that "metadata + heuristics can detect", and provide clear next-step action recommendations.
Evaluation use cases
Use during regression checks evals/evals.json, to confirm that read-only priority, backup recommendations, user confirmation gating, health report format, and long-term rot risk identification have not regressed.
For complex semantic failures, it is strongly recommended to immediately call codex-retrospective after diagnosis to do a deeper retrospective.
Correct usage posture: The user says "a lot of my skills are no longer recognized, help me check" → this skill scans + outputs an evidence-backed health report + a minimal action plan → executes the specific fixes after user confirmation.
This is the first line of defense for individual power users against "collective failure after Arsenal upgrades".