AI Context Linter — Summary

AI Context Linter is a GitHub Action by MrDwarf7 that statically validates AI coding context files (CLAUDE.md, .cursorrules, AGENTS.md, COPILOT.md, .windsurfrules, .clinerules) against 12 rules covering security issues, structural problems, AI anti-patterns, and best practices — catching problems in CI before they silently degrade agent behavior.

Problem it solves: Context files written quickly or carelessly often contain hardcoded API keys, vague instructions ("follow best practices"), conflicting rules, or structural issues that make them harder for agents to parse. These problems are invisible until the agent produces bad output. The linter catches them automatically in CI.

Distinctive trait: It is the only framework in this batch that operates as a GitHub Action for CI integration rather than as an agent tool — it validates the inputs to agents rather than governing agent behavior. It also ships a custom config file (.ai-context-linter.yml) to disable rules or adjust token limits.

Scope: 12 rules across 4 categories: Security (2 errors), Structure (4 warnings), AI Anti-Patterns (3 warnings), Best Practices / File-Type Specific (3+ info). Configurable via YAML config file. Outputs issue count and files-checked as GitHub Action outputs.

Relationship: Sister repo to MrDwarf7/ai-context-templates — designed as the validate step for context files created with those templates.

Differs from seeds: No direct seed parallel exists — none of the 11 seeds include a CI linter for context files. The closest analogy is caliber (same batch) which has a caliber score command that evaluates context file quality with a 100-point rubric; ai-context-linter is a lightweight GitHub Action version of that concept with hardcoded rules rather than LLM-assisted scoring.

AI Context Linter — Overview

Origin

Published by MrDwarf7 on GitHub. 1 star, 0 forks, MIT license. Last commit: 2026-04-21. Language: JavaScript (Node.js 20 Action).

Philosophy

The core premise:

"If you're using Claude Code, Cursor, Copilot, or any AI coding agent, you've probably written a CLAUDE.md or .cursorrules file. Maybe you wrote it at 2 AM. Maybe it has your OpenAI key hardcoded in an example. Maybe it says 'follow best practices' and nothing else. Your AI agent reads that file every time it starts. If the file is wrong, the agent is wrong."

The design follows the standard CI quality gate pattern: catch problems early, before they reach production. Context files are treated as code artifacts that deserve lint enforcement.

Design Decisions

• Zero AI calls: Scoring is deterministic static analysis — regex patterns and structural checks, no LLM involved
• GitHub Action first: Designed as uses: MrDwarf7/ai-context-linter@v1 — one-liner CI integration
• Configurable: .ai-context-linter.yml disables rules or adjusts maxTokens
• Auto-detection: Scans for known context filenames by default, not just the specified glob
• Three severity levels: Error (fail build), Warning (optional fail), Info (suggestions)
• Cross-tool: Auto-detects CLAUDE.md, .cursorrules, AGENTS.md, COPILOT.md, .windsurfrules, .clinerules

Relationship to ai-context-templates

The README explicitly pairs them:

"Need Good Templates? This linter checks your files against best practices. If you want context files that pass every check on the first try: [AI Context Engineering Templates]"

AI Context Linter — Architecture

Distribution

• Type: GitHub Action (npm-package internally)
• License: MIT
• Language: JavaScript (Node.js 20)
• Runtime: Node.js 20 (runs: using: 'node20')

Install Method

# Minimal usage in GitHub Actions workflow
- uses: MrDwarf7/ai-context-linter@v1

# Full configuration
- uses: MrDwarf7/ai-context-linter@v1
  with:
    files: '**/{CLAUDE.md,.cursorrules,AGENTS.md}'
    max-tokens: '3000'
    fail-on-warnings: 'false'
    config: '.ai-context-linter.yml'

Directory Tree

ai-context-linter/
├── src/
│   ├── index.js        # Main action runner + file discovery
│   └── rules.js        # 12 lint rules
├── dist/
│   └── index.js        # Compiled bundle (deployed to Actions)
├── __tests__/          # Test suite
├── action.yml          # Action manifest
├── package.json
└── README.md

Custom Config File

.ai-context-linter.yml in project root:

maxTokens: 3000
disabledRules:
  - bp-too-short
  - struct-missing-description

Target Files (auto-detected)

• CLAUDE.md / .claude
• .cursorrules / .cursorrules.json
• AGENTS.md / AGENTS
• COPILOT.md / .copilot
• .windsurfrules
• CONVENTIONS.md
• .clinerules
• system-prompt.md
• agent-prompt.md

AI Context Linter — Components

12 Lint Rules

Security (severity: error — fails build)

Structure (severity: warning)

AI Anti-Patterns (severity: warning)

Best Practices / File-Type Specific (severity: info)

Action Inputs

Action Outputs

AI Context Linter — Uniqueness & Positioning

Differs From Seeds

None of the 11 seeds include a CI linter for context files. This is a genuinely distinct category: an input validator for AI context rather than an agent framework. The closest seed analogy is the quality-gate concept in spec-kit (18 hooks that run before/after each command) or caliber (deterministic scoring of context file quality) — but both of those are agent-side mechanisms; ai-context-linter is a CI-side mechanism that runs before the agent ever starts.

Positioning

Positioned as CI hygiene for AI teams: "catch these problems before they become problems in production." Competes with no named tools; the space of "AI context file linters" appears to be this tool and caliber's caliber score command.

Observable Failure Modes

• 12 rules is a minimal set; real problems like inconsistent naming conventions, missing test runner specification, or contradictory architectural patterns are not caught
• No rule explains how to fix an issue — the linter identifies problems but the fix is entirely up to the user
• The ai-vague-instructions and bp-redundant-instructions rules require pattern matching on common phrases; novel vague instructions (custom to a project) pass undetected
• Security rules sec-api-key catch obvious patterns but not obfuscated or custom key formats
• No baseline comparison — a file that was fine before and now has new issues requires the user to diff manually

Cross-Tool Coverage

Detects: CLAUDE.md, .cursorrules, AGENTS.md, COPILOT.md, .windsurfrules, .clinerules. Notable gaps: .kiro/steering/, .openspec/, custom context formats.

Pair with ai-context-templates

The create/validate workflow: write context files with ai-context-templates, validate them with ai-context-linter. Both repos by the same author.