docs-health

name	docs-health
description	Audit custom element manifest documentation for completeness and quality. Use when the user asks to "check docs", "audit documentation", "review manifest quality", "find missing descriptions", "docs health", or mentions "undocumented" attributes, slots, events, or CSS properties.
tools	Read, Bash

Documentation Health Check

Audit custom element manifests for documentation completeness and quality using cem health.

Workflow

Phase 1: Run Health Analysis

Run cem health with JSON output to get structured scoring data:

cem health --format json

To filter to specific components or modules:

# Single component
cem health --format json --component my-button

# Specific modules
cem health --format json --module src/components/button.js

The JSON output has this structure:

{
  "modules": [
    {
      "path": "src/components/button.js",
      "score": 18,
      "maxScore": 20,
      "declarations": [
        {
          "tagName": "my-button",
          "name": "MyButton",
          "score": 18,
          "maxScore": 20,
          "categories": [
            {
              "id": "description",
              "category": "Description",
              "points": 5,
              "maxPoints": 5,
              "status": "pass",
              "findings": [...]
            },
            {
              "id": "attributes",
              "category": "Attribute Documentation",
              "points": 3,
              "maxPoints": 5,
              "status": "warn",
              "findings": [
                {
                  "check": "attribute 'variant' has description",
                  "points": 1,
                  "max": 1
                },
                {
                  "check": "attribute 'size' has description",
                  "points": 0,
                  "max": 1,
                  "message": "Add a description for attribute 'size'"
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "overallScore": 18,
  "overallMax": 20,
  "recommendations": [
    "my-button: Add a description for attribute 'size' (Attribute Documentation, +1 pts)"
  ]
}

Phase 2: Interpret Results

The health categories scored by cem health are:

Category	What it checks
description	Element has a description and summary
attributes	Every attribute has a description, type, and default
slots	Every slot has a description
css	CSS custom properties, parts, and states have descriptions
events	Every event has a description and type
demos	Element has demo links

Status values:

• pass (>=80%): Well documented
• warn (40-79%): Has gaps
• fail (<40%): Major gaps

Phase 3: Report

Present the results in a readable format. Use the JSON data to build:

## Documentation Health Report

### Summary
- Components audited: X
- Overall score: X/Y (Z%)
- Components passing: X
- Components needing attention: X

### Per-Component Scores

| Component | Score | Description | Attrs | Slots | Events | CSS | Demos |
|-----------|-------|-------------|-------|-------|--------|-----|-------|
| `<my-button>` | 90% | pass | pass | pass | warn | pass | fail |

### Findings

#### `<my-button>` (18/20, 90%)
- **Attribute Documentation** (warn): Add a description for attribute 'size'
- **Demos** (fail): No demo links found

### Top Recommendations
[List the recommendations from the JSON output — these are already
sorted by point impact]

Phase 4: Deeper Investigation (Optional)

If the user wants more detail on specific gaps, read the element's MCP resources:

cem://element/{tagName}
cem://element/{tagName}/attributes
cem://element/{tagName}/slots

This provides the full manifest data so you can show exactly what's missing and suggest what to document.

Phase 5: Suggesting Fixes

When reporting gaps, show the user how to fix them.

!cat ${CLAUDE_SKILL_DIR}/html-comment-syntax.md

Guidelines

• Use cem health as the source of truth: Don't reinvent the scoring — it already checks descriptions, types, defaults, etc.
• Surface recommendations first: The recommendations array is sorted by impact — present those prominently
• Suggest, don't fabricate: Flag gaps for the element author to fill, don't invent descriptions
• Flag inconsistencies: If some elements score 100% and others score 30%, highlight the gap
• Use --component for focused audits: When the user asks about a specific element, filter to avoid noise