ESLint · CLI · GitHub Action · Agent Skills

Your agent writes
bad Astro.
This catches it.

13 proprietary rules and up to 71 checks for .astro projects — with a health score, CLI, and native GitHub Action.

Get started GitHub

$pnpmadd -D @santi020k/astro-doctor

astro-doctor scan

$ astro-doctor

Scanning /my-astro-project...

✗ error src/pages/blog.astro:12 — no-missing-alt

✗ error src/components/Hero.astro:8 — no-set-html

⚠ warn src/components/Counter.astro:3 — no-client-load-overuse

⚠ warn src/pages/index.astro:24 — use-astro-image

14 files scanned · 2 errors · 2 warnings

Astro Doctor Score:72/100 (C)🟡

Process exited with code 1

Know exactly how healthy your codebase is

Every scan produces a 0–100 health score with a letter grade, so you can set thresholds and track improvement over time.

S100Zero diagnostics

A90–99Excellent

B75–89Good

C60–74Fair

D40–59Needs attention

F0–39Critical

Score = max(0, 100 − (errors×10 + warnings×3) / files)

Everything you need to ship better Astro

One install, multiple touch points — from your editor to your CI pipeline.

ESLint Plugin

Drop-in flat-config plugin. Works with any ESLint 10 setup — standalone or alongside your existing config.

VS Code Extension

Official extension for VS Code and Cursor. Real-time inline diagnostics, hover explanations, quick fixes, and a health sidebar.

CLI Scanner

pnpm dlx @santi020k/astro-doctor — scan any directory, output JSON reports, and integrate into any CI pipeline.

Health Score

0–100 score with S–F grade. Set --fail-on thresholds. Track codebase health across PRs and releases.

GitHub Action

Composite action with PR diff mode — scan only changed files, post a sticky summary comment on every PR.

JSON Reports

Machine-readable output with --json. Pipe into other tools, dashboards, or custom notification systems.

Agent Skills

Pre-built skill files for Claude, Cursor, Copilot Workspace. Your AI agent knows the rules — and how to fix them.

13 rules we own. 71 checks in all.

Each rule targets a specific class of mistake that agents and developers commonly make in Astro projects.

astro-doctor/no-client-load-overusePerformance

Prefer client:idle or client:visible over client:load for interactive islands.

astro-doctor/use-astro-imagePerformance

Use <Image> from astro:assets instead of raw <img> tags.

astro-doctor/require-image-dimensionsPerformance

Require dimensions for public and remote astro:assets images.

astro-doctor/no-missing-altAccessibility

All <img>, <Image>, and <Picture> elements must include an alt attribute.

astro-doctor/no-set-htmlSecurity

Avoid set:html to prevent cross-site scripting (XSS) vulnerabilities.

astro-doctor/no-public-secret-envSecurity

Warn when PUBLIC_ environment variables appear to contain secrets.

astro-doctor/prefer-class-listBest Practices

Use class:list directive for conditional or dynamic class names.

astro-doctor/no-blocking-scriptPerformance

Disallow render-blocking <script src="..."> tags — add defer, async, or type="module".

astro-doctor/no-unprocessed-script-surprisesPerformance

Warn when script attributes opt out of Astro script processing.

astro-doctor/no-missing-langAccessibility

Require a lang attribute on the <html> element.

astro-doctor/require-island-fallbackAccessibility

Require fallback content for client-only and deferred server islands.

astro-doctor/no-process-envBest Practices

Disallow process.env in Astro files — use import.meta.env instead.

astro-doctor/prefer-content-collectionsBest Practices

Prefer Content Collections over Astro.glob() or import.meta.glob() for Markdown and MDX files.

View all rules with examples

Up and running in 2 minutes

Install once, catch issues everywhere.

1
Install the package
bash
```
pnpm add -D @santi020k/astro-doctor
```

2

Add to your ESLint config

// eslint.config.js
import astroDoctorPlugin from '@santi020k/eslint-plugin-astro-doctor'

export default [
  astroDoctorPlugin.configs.recommended,
]

3
Scan your project
bash
```
pnpm astro-doctor
```

Full quick start guide Installation options

CI / CD

PR-aware scanning with sticky comments

The composite GitHub Action scans only the files changed in a pull request and posts a sticky summary comment with the score and all diagnostics. Updated on every push, never duplicated.

Scans only changed Astro Doctor files with diff-only: true
Posts and updates a single sticky PR comment
Outputs score, errors, warnings as Action step outputs
Configurable fail-on threshold (error / warning / off)

GitHub Action docs

name: Astro Doctor
on:
  pull_request:
    paths: ['**/*.astro']

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - uses: santi020k/astro-doctor@v1
        with:
          diff-only: true
          comment: true
          fail-on: error

AI-native

Built for the age of coding agents

Agent skills teach your AI assistant every rule — what to avoid, why, and how to fix it. Install once with astro-doctor install.

astro-rules

All 13 rules with before/after examples your agent can reference.

ClaudeCursorCopilot

astro-performance

Islands architecture, image optimization, View Transitions, Server Islands.

ClaudeCursorCopilot

add-rule

Step-by-step TDD workflow for contributing new rules to the plugin.

ClaudeCursor

astro-doctor install copies skill files to .agents/skills/ in your project

Special Thanks

Astro Doctor was deeply inspired by react-doctor by Million Software, Inc. They pioneered this concept and philosophy for the React ecosystem, and we built Astro Doctor to bring the same excellent developer experience to Astro. Huge thanks to their team!

Start fixing bad Astro today

One package. Up to 71 checks. A score your team can improve sprint over sprint.

Read the docs Star on GitHub ⭐