Agent Document Reviewer

Agent Document Reviewer

Overview

This skill helps review and improve documents intended for AI agent consumption (like AGENTS.md, Claude.md, or custom agent instructions). It identifies common issues that reduce document effectiveness:

• Bloat: Documents become too long, causing agents to miss critical instructions
• Poor structure: Important rules buried late in the document
• Redundancy: Repeated information wasting context window
• Monolithic design: All details in one file instead of using progressive disclosure

Workflow

Follow this sequence when reviewing a document:

1. Initial Analysis

Run the quantitative analysis script to get objective metrics:

# Default: Analyze file + all linked files (recommended)
node scripts/analyze_document.js --root-dir <root-directory> <file-path>

# Analyze single file only (skip link analysis)
node scripts/analyze_document.js --no-include-links <file-path>

⚠️ SECURITY: The --root-dir parameter is REQUIRED for link analysis. It enforces a security sandbox, preventing malicious documents from accessing sensitive files (like ~/.ssh/id_rsa or ~/.aws/credentials) through directory traversal attacks (../../../etc/passwd).

Default behavior: Link analysis is enabled by default when --root-dir is specified. This ensures progressive disclosure evaluation includes the entire documentation system (main doc + linked docs).

Link analysis:

• Follows internal markdown links automatically
• Reports missing files (broken links)
• Blocks links outside root directory (security sandbox)
• Provides aggregate quality metrics across all documents

For detailed usage including path options and output format, see Using the Analysis Script below.

1.5. Scope & Overrides (Convention-Aware)