agents md lint

Security Community

Skill notes

Modes

Default (rewrite): Produces a report and rewrites the instruction files with only the surviving facts. Dry-run: Produces the report but does not modify any files. Use this when the user wants to see what would change before committing, or says things like "just show me," "report only," or "what's redundant." Ask which mode the user wants if it's ambiguous.

1. Discover and normalize instruction files

Scan the repo for instruction files. Common names: AGENTS.md, CLAUDE.md, CONVENTIONS.md, .cursorrules, .github/copilot-instructions.md. Ask the user if there are others, or if any should be excluded. CLAUDE.md → AGENTS.md normalization: If a CLAUDE.md exists but no AGENTS.md, rename CLAUDE.md to AGENTS.md and create a symlink CLAUDE.md → AGENTS.md. This keeps AGENTS.md as the canonical name while preserving compatibility with tools that look for CLAUDE.md. If both files already exist as separate files, leave them as-is and audit each independently. Skip this normalization in dry-run mode.

2. Extract facts

Read each instruction file. List every distinct fact as a numbered item, grouped by file. A "fact" is any single claim, convention, instruction, or piece of context — e.g., "tests use vitest," "branch names follow feature/JIRA-123 format," "never mock the database in integration tests."

3. Chunk facts for testing

Sub-agents get unreliable when asked too many questions at once. If a file contains more than 25 facts, split them into batches of 20–25 and spawn a separate sub-agent for each batch. Each batch should be self-contained — include enough context in the prompt so the sub-agent understands the domain without needing to see the other batches.

4. Spawn blind reviewer(s)

For each batch of facts, spawn a sub-agent with this task template. The key insight here is that the sub-agent must not have access to the instruction files — it should rely only on what it can find by searching the code. Rather than renaming or moving files (which risks data loss if something goes wrong), tell the sub-agent explicitly which files to ignore: Use a capable model (opus or equivalent) for reliable results.

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Security
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@tomevault-io · no license declared
Token usage
Lean
Setup complexity
Guided setup
External API key
Not required
Operating systems
Unspecified (assume cross-platform)
Runtime requirements
No explicit requirements detected
Detected file/system behavior
  • Read-only
  • Write / modify
  • Shell exec
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

Output preview agents-md-lint.preview
# 5. Score results

Compare each sub-agent's answers against the original facts. The scoring accounts for both correctness and practical discoverability — a fact that's technically in the code but requires insider knowledge to find is still worth documenting. | Agent confidence | Agent correct? | Verdict | |-----------------|----------------|---------| | HIGH | Yes | **Remove** — easily discoverable | | HIGH | Partially | **Keep** the missing detail only | | MEDIUM | Yes | **Keep** — findable but buried; an agent without docs would likely miss it or waste time searching | | MEDIUM | Partially | **Keep** — not rel

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.