A GitHub Action that checks your AI coding context files for problems before your agent starts writing bad code.
What it checks:
CLAUDE.md/.cursorrules/AGENTS.md/COPILOT.md/.windsurfrules/.clinerules- Security issues (leaked API keys, private file paths)
- Structural problems (missing sections, empty headings, wall-of-text files)
- AI anti-patterns (vague instructions, conflicting rules, redundant directives)
- File-type specific checks (tool guidance for CLAUDE.md, file scope for .cursorrules)
- uses: MrDwarf7/ai-context-linter@v1That's it. It auto-detects your context files and runs 12 rules against them.
name: Lint AI Context Files
on: [push, pull_request]
jobs:
lint-context:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: MrDwarf7/ai-context-linter@v1
with:
files: '**/{CLAUDE.md,.cursorrules,AGENTS.md}'
max-tokens: '3000'
fail-on-warnings: 'false'| Rule | What it catches |
|---|---|
sec-api-key |
Hardcoded API keys (OpenAI, Stripe, GitHub PAT, Slack tokens) |
sec-private-path |
Leaked home directory paths (/home/user/.ssh/...) |
| Rule | What it catches |
|---|---|
struct-too-long |
Files over the token limit — wastes context window, dilutes instructions |
struct-no-sections |
500+ chars with no ## headings — AI agents parse structured files better |
struct-empty-sections |
A heading followed immediately by another heading — empty section |
struct-missing-description |
No overview/description section — agent doesn't know what the project is |
| Rule | What it catches |
|---|---|
ai-vague-instructions |
"Be good", "follow best practices", "don't be stupid" — says nothing useful |
ai-conflicting-rules |
"Always use tabs" + "never use tabs" — confuses the agent |
bp-redundant-instructions |
"Write code that works" — the AI already tries to do this |
| Rule | What it catches |
|---|---|
bp-no-structure-hints |
No formatting/style guidance — consider adding it |
bp-too-short |
Under 50 words — might not be enough context |
bp-html-comments |
Large hidden HTML comments (possible prompt injection vector) |
| Rule | What it catches |
|---|---|
ft-claude-missing-tools |
CLAUDE.md with no tool/command references |
ft-cursor-no-globs |
.cursorrules with no file scope patterns |
| Output | Description |
|---|---|
issues-found |
Total count of errors + warnings + suggestions |
files-checked |
Number of context files found and checked |
Create .ai-context-linter.yml in your repo root:
maxTokens: 3000
disabledRules:
- bp-too-short
- struct-missing-descriptionThen reference it:
- uses: MrDwarf7/ai-context-linter@v1
with:
config: '.ai-context-linter.yml'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. This action catches those problems in CI before they become problems in production.
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 →
Battle-tested templates for Claude Code, Cursor, multi-agent setups, and more. Written by someone who's spent 200+ hours figuring out what actually makes AI agents write better code.
MIT — use it however you want.