Help us improve
Share bugs, ideas, or general feedback.
From claude-ecosystem
Tracks health of 27 Claude Code extensibility components across 6 tiers (plugins, CLI, auth, integrations). Audits status, documentation, staleness; applies updates and orchestrates checks.
npx claudepluginhub melodic-software/claude-code-plugins --plugin claude-ecosystemHow this skill is triggered — by the user, by Claude, or both
Slash command
/claude-ecosystem:ecosystem-healthThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
> **CRITICAL:** This skill follows the anti-duplication principle. **ALL component details MUST be queried from docs-management at runtime.**
Audits Claude Code configurations for best practices in skills, instructions, MCP servers, hooks, plugins, security, over-engineering, and context efficiency via file scans and focused checks. Invoke with /claudit [focus-area].
Audits Claude Code project configuration for drift and collaboration issues across six layers (CLAUDE.md, rules, skills, hooks, subagents, verifiers), tiered by project complexity.
Audits Claude Code plugins for structure validation, frontmatter quality, deprecations, feature adoption, security patterns, and documentation. Ensures changelog compatibility and best practices for releases.
Share bugs, ideas, or general feedback.
CRITICAL: This skill follows the anti-duplication principle. ALL component details MUST be queried from docs-management at runtime.
| Data | Why Static |
|---|---|
| Tier structure (1-6) | Design decision, architectural choice |
Audit skills (/audit-*) | OUR skills in claude-ecosystem plugin |
| Audit types (automated/manual/documentation) | Classification policy |
| Scoring/prioritization logic | Policy decisions |
| Data | Why Dynamic | How to Get |
|---|---|---|
| CLI flags list | New flags every release | Query: docs-management: cli-reference.md CLI flags |
| Environment variables | New env vars frequently | Query: docs-management: settings.md environment variables |
| Authentication methods | New providers added | Query: docs-management: iam.md authentication methods |
| Permission modes | Modes evolve | Query: docs-management: iam.md permission modes |
| Cloud providers | New providers added | Query: docs-management: setup.md cloud providers |
| IDE integrations | New integrations added | Query: docs-management: third-party-integrations.md IDE |
| Change keywords | Terminology evolves | Derive from docs-management index keywords |
| File patterns | Locations can change | Query official docs for current patterns |
--discover and --check modes# Tier 3: Environment & CLI
"cli-reference.md CLI flags" → Get current CLI flags list
"settings.md environment variables" → Get current env vars list
"iam.md permission modes" → Get current permission modes
# Tier 4: Authentication & Access
"iam.md authentication methods" → Get current auth methods
"iam.md configuring permissions" → Get permission rule patterns
"iam.md credential management" → Get credential features
# Tier 5: Session & Runtime
"cli-reference.md session features" → Get session features (resume, checkpoints)
"security.md sandbox configuration" → Get sandbox settings
# Tier 6: Integration
"third-party-integrations.md IDE" → Get IDE integrations list
"setup.md cloud providers" → Get cloud provider list
"common-workflows.md CI/CD" → Get CI/CD platforms
# Changelog for change categorization
"CHANGELOG recent changes" → Get changelog entries
This skill tracks Claude Code ecosystem health across ALL extensibility points - not just plugin components. It monitors 27 component types across 6 tiers.
Schema v2.2 introduces the Tiered Validation Model for changelog-triggered audit staleness:
This approach provides 60-96% token savings while maintaining strict accuracy requirements.
| Tier | Category | Components | Audit Type | Description |
|---|---|---|---|---|
| 1 | Core Configuration | 4 | Mixed | User, project, and enterprise settings |
| 2 | Plugin Components | 12 | Automated | Components packaged in plugins |
| 3 | Environment & CLI | 3 | Documentation | Env vars, CLI flags, permission modes |
| 4 | Authentication & Access | 3 | Mixed | Auth methods, permission rules |
| 5 | Session & Runtime | 2 | Mixed | Session features, sandbox config |
| 6 | Integration | 3 | Documentation | IDEs, cloud providers, CI/CD |
| Type | Description | Has Audit Command? | Tracking Method |
|---|---|---|---|
automated | Full audit via /audit-* skills | Yes | Pass rate, component count |
manual | Requires human review | No | Human review tracking |
documentation | Tracks doc coverage only | No | Doc coverage via docs-management queries |
Schema v2.2 introduces a three-tier validation model that automatically invalidates audits when changelog changes affect components, while using the most token-efficient validation method appropriate for each change type.
| Change Type | Severity | Validation Requirement | Rationale |
|---|---|---|---|
feature | Minor | Targeted validation (keyword check) | New features can be verified by checking keywords exist |
deprecation | Minor | Targeted validation (keyword check) | Deprecations can be verified by checking warnings documented |
bugfix | None | No validation needed | Bugfixes don't affect plugin documentation/compliance |
behavior_change | Major | Full audit required | Behavior changes may have wide-ranging impacts |
security | Major | Full audit required | Security changes require comprehensive review |
For feature and deprecation changes:
VALIDATEDAlgorithm:
1. Load validation spec from granular_changelog change entry
2. For each keyword in validation.keywords:
a. Run grep against target_skill directory
b. If match found, record evidence (file, line, match text)
3. If matches >= required_matches:
a. Set validation_result.validated = true
b. Set confidence based on match count:
- 1 match = "medium"
- 2+ matches = "high"
4. Update component_coverage validation tracking
For behavior_change and security changes:
AUDITEDImportant: Major changes cannot be validated via targeted validation. The system must enforce this - no shortcuts.
Regardless of validation status:
Each change in granular_changelog can have a validation spec:
validation:
method: "keyword_check" # keyword_check | full_audit | manual | none
target_skill: "hook-management" # Which skill to validate (null for memory files)
keywords: # Manual list - NEVER auto-extracted
- "additionalContext"
- "additional context"
- "PreToolUse.*additionalContext" # Regex supported
required_matches: 1 # How many keywords must match
reason: "..." # Optional explanation (esp. for method: none)
# For full_audit method:
validation:
method: "full_audit"
target_skill: "permission-management"
audit_command: "/audit-settings"
reason: "Security fix - targeted validation insufficient"
After validation runs, results are recorded:
validation_result:
validated: true # Did validation pass?
validated_date: "2026-01-16" # When validated
evidence: # For keyword_check method
- file: "path/to/file.md"
line: 142
match: "matched text"
audit_performed: true # For full_audit method
audit_date: "2026-01-12" # When audit was run
confidence: "high" # high | medium | low
Component status is determined by this priority order (first match wins):
| Priority | Condition | Status |
|---|---|---|
| 1 | Has pending_major_changes | NEEDS AUDIT ⚠️ |
| 2 | Has pending_minor_changes | NEEDS VALIDATION |
| 3 | days_since(last_audit) > 90 | STALE |
| 4 | validation_version == latest AND validation_confidence == "high" | VALIDATED |
| 5 | last_audit recent AND no pending changes | OK |
| 6 | Never audited | UNKNOWN |
Conservative Rule: If ANY doubt exists, escalate to higher requirement.
The system must NEVER report "validated" unless certain. These rules are non-negotiable.
❌ Finding "context" when looking for "context: fork" is NOT a match
✅ Must match exact keyword or regex pattern
| Evidence Count | Confidence Level |
|---|---|
| 0 matches | validation_failed: true |
| 1 match | confidence: "medium" |
| 2+ matches | confidence: "high" |
If confidence is "low":
--apply output for user decision❌ security change → keyword_check (FORBIDDEN)
❌ behavior_change → keyword_check (FORBIDDEN)
✅ security change → full_audit (REQUIRED)
✅ behavior_change → full_audit (REQUIRED)
The system must reject attempts to use targeted validation for major changes.
The skill provides:
Use this skill when:
Location: .claude/ecosystem-health.yaml
This file persists ecosystem health state across sessions. It stores audit metadata ONLY - not component details (which are delegated to docs-management).
Schema v2.1 Structure:
schema_version: "2.1"
last_check:
date: "YYYY-MM-DD"
claude_code_version: "X.Y.Z"
changelog_hash: "sha256:..."
component_coverage:
# Tier 1: Core Configuration
tier1_configuration:
user_settings:
last_audit: null
components_audited: 0
pass_rate: null
audit_type: "manual"
# Query docs-management for: settings.md user configuration
project_settings:
last_audit: "YYYY-MM-DD"
components_audited: N
pass_rate: 0.XX
audit_type: "automated"
audit_command: "/audit-settings"
managed_settings: { ... }
memory_system: { ... }
# Tier 2: Plugin Components (12 components)
tier2_plugins:
skills: { audit_type: "automated", audit_command: "/audit-skills" }
agents: { audit_type: "automated", audit_command: "/audit-agents" }
# ... (12 components, each with audit_type and audit_command)
# Tier 3-6: Documentation-tracked (DELEGATE to docs-management)
tier3_environment:
environment_variables:
audit_type: "documentation"
# DELEGATE: Query docs-management for: settings.md environment variables
cli_flags: { ... }
permission_modes: { ... }
tier4_authentication: { ... }
tier5_session: { ... }
tier6_integration: { ... }
changelog_versions_checked:
- version: "X.Y.Z"
checked_date: "YYYY-MM-DD"
changes_applied: true/false
pending_updates:
- feature: "feature name"
since_version: "X.Y.Z"
affects: ["skills", "commands"]
status: "pending" | "applied" | "skipped"
last_discovery:
date: "YYYY-MM-DD"
docs_scanned: [...]
changelog_version: "X.Y.Z"
components_detected: 27
tiers_scanned: 6
gaps_found: 0
Key Design Decision: The tracking file does NOT contain tracked_* arrays (no hardcoded lists of env vars, CLI flags, auth methods, etc.). All such data must be queried from docs-management at runtime.
MANDATORY: Access changelog via docs-management skill.
Doc ID: raw-githubusercontent-com-anthropics-claude-code-refs-heads-main-CHANGELOG
Access pattern:
python plugins/claude-ecosystem/skills/docs-management/scripts/core/find_docs.py \
content raw-githubusercontent-com-anthropics-claude-code-refs-heads-main-CHANGELOG
Parse changelog for version entries:
Pattern: ^##\s*\[?(\d+\.\d+\.\d+)\]?
Examples:
"## 2.1.3" → version 2.1.3
"## [2.1.0]" → version 2.1.0
Map changelog keywords to component types across all 6 tiers.
IMPORTANT: Do NOT use hardcoded keyword lists. Query docs-management for current keywords via the index, then match changelog entries against those keywords.
| Tier | Components | Query docs-management for |
|---|---|---|
| 1 | user_settings, project_settings, managed_settings, memory_system | settings.md, iam.md, memory.md |
| 2 | skills, agents, hooks, mcp, memory, plugins, settings, output_styles, statuslines, rules, lsp | skills.md, sub-agents.md, hooks.md, mcp.md, memory.md, plugins-reference.md, terminal-config.md |
| 3 | environment_variables, cli_flags, permission_modes | settings.md, cli-reference.md, iam.md |
| 4 | authentication_methods, permission_rules, credential_management | iam.md |
| 5 | session_features, sandbox_configuration | cli-reference.md, security.md |
| 6 | ide_integrations, cloud_providers, cicd_integrations | third-party-integrations.md, setup.md, common-workflows.md |
For detailed categorization patterns, see references/change-categories.md.
Shows current ecosystem health without running audits. Displays all 6 tiers.
Algorithm:
Compares current changelog against last check. Identifies changes across all tiers.
Algorithm:
Runs audits intelligently. Only applies to Tier 2 components (automated audits).
Without type argument: Audits all stale/never-audited Tier 2 components With type argument: Audits only specified type
Priority Order:
Batching:
Audit Command Mapping (Tier 2 Only):
| Component | Audit Command |
|---|---|
| skills | /audit-skills |
| agents | /audit-agents |
| hooks | /audit-hooks |
| mcp | /audit-mcp |
| memory | /audit-memory |
| plugins | /audit-plugins |
| settings | /audit-settings |
| output_styles | /audit-output-styles |
| statuslines | /audit-statuslines |
| rules | /audit-rules |
| lsp | /audit-lsp |
Compliance Audits (Cross-Cutting):
| Audit Type | Audit Command | Description |
|---|---|---|
| docs-delegation | /audit-docs-delegation | Audits skills and memory files for proper docs-management delegation patterns |
| agent-consolidation | /audit-agent-consolidation | Analyzes agents for consolidation opportunities, groups by config, tracks references |
Tracks documentation coverage for non-auditable components (Tiers 3-6).
Algorithm:
Note: Coverage is always based on current docs-management content. There's no "tracked list" to compare against - docs-management IS the source of truth.
Interactive mode to apply pending updates.
For each pending update:
Shows all changes since a specific version, organized by tier.
Algorithm:
Detects plugin overlaps, redundancy, and consolidation opportunities.
Algorithm:
Enumerate all plugins:
plugins/*/ directoriesExtract component names:
skills/*/SKILL.mdagents/*.mdDetect duplicates:
Semantic overlap analysis:
Published standard detection:
Generate overlap report:
## Plugin Overlap Analysis
**Duplicate Components Found:**
| Component | Type | Plugins |
| --------- | ---- | ------- |
| adr-management | skill | enterprise-architecture, documentation-standards |
| journey-mapping | skill | business-analysis, requirements-elicitation |
**Semantic Overlaps:**
| Plugin A | Plugin B | Overlap % | Domain | Status |
| -------- | -------- | --------- | ------ | ------ |
| ~~contract-testing~~ | test-strategy | 85% | Testing | ✅ CONSOLIDATED (v2.0) |
| ~~observability-planning~~ | ~~quality-attributes~~ | 70% | NFRs | ✅ BOTH REMOVED (v2.0) |
**Published Standard Plugins (Consolidation Candidates):**
| Plugin | Methodology | Standard Type | Recommendation | Status |
| ------ | ----------- | ------------- | -------------- | ------ |
| ~~quality-attributes~~ | ISO 25010 | International Standard | REMOVE | ✅ REMOVED (v2.0) |
| ~~ai-ml-planning~~ | CRISP-DM | Industry Framework | REMOVE | ✅ REMOVED (v2.0) |
| ~~data-architecture~~ | Kimball | Published Methodology | REMOVE | ✅ REMOVED (v2.0) |
**Consolidation Completed (v2.0):**
1. **~~contract-testing~~ → test-strategy** - DONE: `compatibility-analyzer` agent moved
2. **8 published standard plugins** - REMOVED: MCP research replaces them
3. **content-management-system** - KEPT: unique composition patterns
Overlap Status in ecosystem-health.yaml:
plugin_overlap:
last_analysis: "2026-01-17"
total_plugins: 35
duplicate_components:
- component: "adr-management"
type: "skill"
plugins: ["enterprise-architecture", "documentation-standards"]
resolution: "pending" | "resolved" | "intentional"
published_standard_plugins:
- plugin: "quality-attributes"
methodology: "ISO 25010"
recommendation: "remove"
status: "pending" | "removed" | "kept_with_justification"
consolidation_candidates:
- source: "contract-testing"
target: "test-strategy"
assets_moved: ["compatibility-analyzer agent"]
status: "completed" # v2.0 consolidation
Scans official documentation to detect ecosystem drift across ALL 6 tiers.
Algorithm:
Query docs-management for ALL relevant doc sections:
Spawn claude-code-guide agent for live web verification of:
Build detected components list by tier:
Report findings with evidence:
What do you want to do?
--check)--audit)--doc-coverage)--apply)--since X.Y.Z)--overlap)--discover)This skill delegates to specialized skills for domain-specific guidance:
ecosystem-health
├── docs-management (MANDATORY - changelog, official docs for all tiers)
├── claude-code-guide (live verification during --discover and --check)
│
├── Tier 1 & 2 - Settings/Memory
│ ├── settings-management
│ └── memory-management
│
├── Tier 2 - Plugin Components
│ ├── skill-development (covers skills and legacy commands)
│ ├── subagent-development
│ ├── hook-management
│ ├── mcp-integration
│ ├── plugin-development
│ ├── output-customization
│ └── status-line-customization
│
├── Tier 3-4 - Auth/Environment
│ ├── settings-management
│ ├── permission-management
│ └── enterprise-security
│
├── Tier 5 - Session/Runtime
│ └── sandbox-configuration
│
└── Tier 6 - Integration (documentation tracking only)
Goal: Minimize tokens while maintaining coverage.
Strategies:
Expected savings: 60-80% compared to running all audits blindly.
The skill handles migration between schema versions:
v1.0 → v2.0: Tiered organization v2.0 → v2.1: Delegation pattern (remove hardcoded lists)
Migration algorithm:
.claude/ecosystem-health.yaml.backupFor detailed implementation guidance:
| Skill | Relationship |
|---|---|
docs-management | MANDATORY - Primary source for ALL dynamic data |
claude-code-guide | Live verification for --discover and --check modes |
skill-development | Skills and commands validation and guidance |
subagent-development | Agents validation and guidance |
settings-management | Settings guidance |
All other *-development skills | Domain-specific validation |
Query: /ecosystem-health
Expected: Creates tracking file with v2.1 schema, shows "never checked" status for all tiers
Success: Tracking file created, 27 components displayed across 6 tiers, NO hardcoded lists in file
Query: /ecosystem-health --check
Expected:
Query: /ecosystem-health --audit
Expected: Audits only stale/never-audited Tier 2 components
Success: Targeted audits run, tracking file updated (audit metadata only)
Query: /ecosystem-health --doc-coverage
Expected:
Query: /ecosystem-health --discover
Expected:
v2.3.0 (2026-01-17): Plugin Overlap Detection
--overlap mode for detecting plugin redundancy and consolidation opportunitiesv2.2.0 (2026-01-16): Tiered Validation Model
--validate (read-only check), --audit-required (shows only major changes)v2.1.0 (2026-01-10): Delegation pattern
v2.0.0 (2026-01-10): Expanded to ALL Claude Code extensibility points
v1.1.0 (2026-01-10): Added discover mode
v1.0.0 (2026-01-10): Initial release
Parse the provided arguments ($ARGUMENTS) to determine the mode:
| Argument | Mode | Description |
|---|---|---|
| (none) | status | Smart check: show status and recommendations |
--status | status | Detailed status report with validation status |
--check | check | Check changelog for new changes since last check |
--audit | audit | Run audits for stale/never-audited components |
--audit [type] | audit | Run audit for specific type only |
--audit-all | audit-all | Force full audit of all components |
--apply | apply | Interactive mode to apply/validate pending updates (tiered) |
--validate | validate | Read-only validation check (no state changes) |
--audit-required | audit-required | Show only components requiring full audits |
--since <version> | since | Show changes since specific version |
--discover | discover | Scan docs for new/changed extensibility components |
Valid component types for --audit: skills, agents, commands, hooks, mcp, memory, plugins, settings, output-styles, statuslines, rules, lsp, permissions
Determine the mode from $ARGUMENTS:
Arguments: $ARGUMENTS
Parse for:
- No args or --status -> status mode
- --check -> check mode
- --audit -> audit mode (optionally with type)
- --audit-all -> audit-all mode
- --apply -> apply mode
- --since <version> -> since mode
- --discover -> discover mode
Invoke the claude-ecosystem:ecosystem-health skill for core logic.
The skill provides:
.claude/ecosystem-health.yaml.claude/audit/ for each component typeOutput format:
Ecosystem Health Status (v2.2)
==============================
Last Check: [date] (Claude Code v[version])
or "Never checked"
Component Coverage:
| Component | Audit | Validation | Pending | Status |
|-------------|----------|------------|---------|----------------|
| hooks | 01-11 | 01-16 + | 0 | VALIDATED |
| skills | 01-11 | 01-16 + | 0 | VALIDATED |
| mcp | 01-11 | - | 2 minor | NEEDS VALID. |
| permissions | 01-12 | - | 1 MAJOR | NEEDS AUDIT |
| commands | 01-12 | - | 0 | OK (80%) |
Legend:
VALIDATED = Targeted validation passed (high confidence)
NEEDS VALID. = Minor changes pending validation
NEEDS AUDIT = Major changes requiring full audit
OK = No pending changes, within time threshold
STALE = >90 days since last audit
Pending Updates: N total (X minor, Y major)
MAJOR (require audit):
- 2.1.7-005: SECURITY fix (permissions) -> /audit-settings
MINOR (can use validation):
- 2.1.9-005: additionalContext feature (hooks)
Recommendations:
1. [action]
2. [action]
Load tracking file
Access changelog via docs-management skill:
python plugins/claude-ecosystem/skills/docs-management/scripts/core/find_docs.py \
content raw-githubusercontent-com-anthropics-claude-code-refs-heads-main-CHANGELOG
Compute SHA256 hash of changelog content
Compare to stored hash
If different:
Update tracking file
Report findings
If type specified (--audit skills):
If no type (--audit):
Audit commands:
| Component | Command |
|---|---|
| skills | /audit-skills --smart |
| agents | /audit-agents --smart |
| hooks | /audit-hooks --smart |
| mcp | /audit-mcp |
| memory | /audit-memory |
| plugins | /audit-plugins --smart |
| settings | /audit-settings |
| output-styles | /audit-output-styles --smart |
| statuslines | /audit-statuslines --smart |
| rules | /audit-rules |
| lsp | /audit-lsp |
Force run all audits regardless of staleness:
Warning: This uses significant tokens (~55,000+). Use --audit for smart targeting.
For each pending change, apply tiered validation based on severity:
For MINOR changes (feature, deprecation):
Display change details with severity classification:
[1/3] 2.1.9-005: PreToolUse additionalContext (feature)
Severity: Minor (feature) -> Targeted validation
Target: hook-management skill
Keywords: ["additionalContext", "additional context"]
Run grep-based validation against target skill
Show evidence with file, line, and matched text
Calculate confidence (high = 2+ matches, medium = 1 match)
Ask user for action:
For MAJOR changes (behavior_change, security):
Display change with warning:
[2/3] 2.1.7-005: SECURITY: Wildcard permission bypass fix
Severity: MAJOR (security) -> Full audit REQUIRED
Target: permission-management skill
Audit: /audit-settings
This is a security change. Targeted validation is not sufficient.
A full audit must be run to verify comprehensive compliance.
Ask user for action:
Update tracking file with validation/audit results
Read-only validation check without applying changes:
Shows only components requiring full audits (filters out minor changes):
pending_major_changes (security, behavior_change)pending_minor_changes where validation failedScan official documentation to detect new or changed extensibility components.
Access official docs via docs-management skill:
Parse changelog for component additions:
.claude/X/).X.json)Build detected components list:
Compare to tracked components:
Report findings with evidence:
# Quick health check with validation status
/ecosystem-health
# Detailed status (shows audit + validation columns)
/ecosystem-health --status
# Check for Claude Code updates
/ecosystem-health --check
# Run targeted audits
/ecosystem-health --audit
# Audit only skills
/ecosystem-health --audit skills
# Force full audit (expensive - ~55,000 tokens)
/ecosystem-health --audit-all
# Apply pending updates with tiered validation (v2.2)
/ecosystem-health --apply
# Read-only validation check (doesn't modify state)
/ecosystem-health --validate
# Show only components requiring full audits
/ecosystem-health --audit-required
# See what changed since v2.1.0
/ecosystem-health --since 2.1.0
# Scan docs for new extensibility components
/ecosystem-health --discover
| Scenario | Old (Full Audits) | New (Tiered) | Savings |
|---|---|---|---|
| 3 minor changes | ~15,000 | ~600 | 96% |
| 2 minor + 1 major | ~18,000 | ~4,600 | 74% |
| Periodic review | ~40,000 | ~8,000 | 80% |
Key: Major changes still require full audits, but minor changes are validated efficiently.
Date: 2026-01-17 Model: claude-opus-4-5-20251101