Agent Legibility Skill

Purpose

Establishes a production-grade framework for structuring codebases, documentation, and configuration files so that AI coding agents can efficiently discover project conventions, navigate file structures, understand architectural constraints, and follow repository-specific instructions without human intervention. This system provides standardized file formats, progressive disclosure strategies, and navigation hint patterns that minimize agent context consumption while maximizing task-relevant information retrieval.

Core Principles

1. Machine-First Documentation: Documentation must be structured for parsing by agents first, with human readability as a secondary concern. Use explicit headers, consistent formatting, and parseable metadata blocks.
2. Progressive Context Disclosure: Never dump the entire codebase context at once. Layer information from high-level summaries to detailed specifications, letting agents load only what they need for the current task.
3. Convention over Configuration: Establish clear naming conventions, file placement rules, and structural patterns that agents can infer without reading extensive configuration files.
4. Explicit Navigation Hints: Provide explicit pointers between related files, modules, and documentation sections. Agents cannot browse; they need directed links.
5. Constraint Files as Guardrails: Use dedicated constraint and convention files to prevent agents from making architectural violations, even when they lack full codebase context.

Agent Protocol