How does progressive disclosure improve AI performance?

It keeps the main instruction file small (under 32KiB) and links to deeper documentation, preventing the AI's context window from being overwhelmed by irrelevant details.

What is an AGENTS.md file?

AGENTS.md is a standardized file used to provide project-specific instructions, rules, and context to AI agents operating within a repository.

Does this skill work with CLAUDE.md and GEMINI.md?

Yes, it harmonizes rules across all three formats while respecting the specific style and section conventions of each AI tool.

How does the skill ensure instructions are accurate?

It performs a discovery interview and verifies all suggested commands and file paths against actual repository evidence like package.json or existing scripts.

What happens if there are contradictory instructions?

The skill identifies the conflict, stops the process, and asks the user for a decision rather than writing speculative or conflicting guidance.

AI Instruction Architect

Name: AI Instruction Architect
Author: jscraik

byjscraik

•

Learning & Documentation

Standardizes and optimizes repository-specific AI agent instructions using the AGENTS.md framework and progressive disclosure.

The AI Instruction Architect skill helps developers create and maintain high-signal AGENTS.md files and linked instruction documents to guide AI behavior within a repository. It employs a progressive disclosure model to keep root instructions minimal while routing complex guidance to specific sub-documents, ensuring AI agents operate within project-specific constraints. By verifying commands and paths against repo evidence, it eliminates hallucinations and ensures that AI tools like Claude and Gemini follow consistent, valid operating procedures without exceeding context window limits.

Key Features

01Automated creation and refactoring of AGENTS.md and linked docs

02Detection of contradictory or redundant repository instructions

03Progressive disclosure routing to minimize context window bloat

04Evidence-based command mapping from package manifests and scripts

052 GitHub stars

06Cross-tool harmonization for AGENTS.md, CLAUDE.md, and GEMINI.md

Use Cases

01Consolidating conflicting guidance across multiple AI instruction files

02Organizing fragmented or bloated repository instructions into a clean hierarchy

03Implementing repo-specific safety checks and stack-detection rules for AI agents

Key Features

01Automated creation and refactoring of AGENTS.md and linked docs

02Detection of contradictory or redundant repository instructions

03Progressive disclosure routing to minimize context window bloat

04Evidence-based command mapping from package manifests and scripts

052 GitHub stars

06Cross-tool harmonization for AGENTS.md, CLAUDE.md, and GEMINI.md

Use Cases

01Consolidating conflicting guidance across multiple AI instruction files

02Organizing fragmented or bloated repository instructions into a clean hierarchy

03Implementing repo-specific safety checks and stack-detection rules for AI agents