AgentLint

Audit websites for AI/agent-friendliness. Runs 17 rules across 5 categories, produces a 0-100 AgentScore, and guides remediation.

Workflow

Step 1: Run the CLI

npx @cjavdev/agent-lint <url> --agent

The --agent flag outputs a structured markdown report optimized for parsing. If the user wants raw JSON, use --json instead.

Common flags:

Exit codes: 0 = no errors found, 1 = errors found, 2 = invalid input/system error.

Step 2: Parse Results

Extract from the CLI output:

• Score (0-100) and letter grade (A/B/C/D/F)
• Violations grouped by severity: errors, warnings, info
• Per-page details for page-specific violations

Step 3: Present Remediation Plan

Prioritize fixes by impact:

1. Errors first (-10 pts each) — These are the biggest score killers
2. High-ROI warnings (-4 pts each) — Fix easy ones first (e.g., adding a sitemap vs. restructuring content)
3. Info items (-1 pt each) — Nice-to-have improvements

For each violation, provide:

• What's wrong and why it matters
• Concrete fix steps (reference references/remediation-guide.md for detailed instructions)
• Expected score improvement

Score Interpretation

Scoring formula: Start at 100. Subtract 10 per error, 4 per warning, 1 per info. Clamped to 0-100.

Rule Quick Reference

Errors (-10 pts each)

Warnings (-4 pts each)

Info (-1 pt each)

Prioritization Logic

When presenting a remediation plan, order fixes by points recoverable per unit of effort:

Quick wins (fix first):

• discoverability/llms-txt — Create a single file, recover 10 pts
• structure/lang-attribute — One-line HTML change, recover 1 pt
• structure/meta-description — Add meta tags, recover 1 pt per page
• discoverability/sitemap — Most frameworks auto-generate this

Medium effort:

• transport/content-type-valid — Usually a server config fix
• structure/heading-hierarchy — HTML structure fixes
• structure/anchor-ids — Add a rehype/markdown plugin
• agent/agent-usage-guide — Write a dedicated docs page
• transport/robots-txt — Create/update a text file

High effort, high impact:

• transport/accept-markdown — Requires server-side content negotiation (10 pts)
• tokens/page-token-count — May require content restructuring
• tokens/boilerplate-duplication — Requires template/layout changes

Configuration

Sites can customize behavior via agent-lint.config.json:

{
  "maxDepth": 3,
  "maxPages": 30,
  "tokenThreshold": 4000,
  "ignorePatterns": ["/blog/*"],
  "rules": {
    "tokens/page-token-count": {
      "severity": "info",
      "ignorePaths": ["/docs/changelog"]
    }
  }
}

Detailed Remediation

For step-by-step fix instructions with code examples for each rule (Nginx, Cloudflare Workers, Next.js, Express, static HTML), see references/remediation-guide.md.